1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IBaseReadOnlyDao.java Copyright (c) 2009 Giovanni Azua Garcia
5 // bravegag@hotmail.com
6 //
7 // This program is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU General Public License
9 // as published by the Free Software Foundation; either version 3
10 // of the License, or (at your option) any later version.
11 //
12 // This program is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
16 //
17 // You should have received a copy of the GNU General Public License
18 // along with this program; if not, see <http://www.gnu.org/licenses/>.
19 //
20 //----------------------------------------------------------------------
21 package org.perfectjpattern.jee.api.integration.dao;
22
23 import java.util.*;
24
25 import org.perfectjpattern.core.api.structural.adapter.*;
26
27 /**
28 * <b>Data Access Object (DAO) Pattern</b>: Abstracts from any direct type of
29 * database or persistence mechanism. Provides specific operations without
30 * exposing details of the database.
31 * <br/><br/>
32 * <b>Responsibility</b> : Partial base Data Access Object abstraction
33 * providing Read-Only features:
34 * <br/>
35 * <br/>
36 * <ul>
37 * <li>Find an Element by ID</li>
38 * <li>Find all Elements of a given type in the persistent storage</li>
39 * <li>Ask if it contains a given Element</li>
40 * <li>Ask for the total number of records</li>
41 * </ul>
42 *
43 * @param <Id> Identification type
44 * @param <Element> Element type
45 *
46 * @see <a href="http://en.wikipedia.org/wiki/Data_Access_Object">Data Access
47 * Object wiki definition</a>
48 *
49 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
50 * @version $Revision: 1.0 $Date: Feb 19, 2009 11:08:44 AM $
51 */
52 public
53 interface IBaseReadOnlyDao<Id, Element>
54 {
55 //------------------------------------------------------------------------
56 // public
57 //------------------------------------------------------------------------
58 /**
59 * Returns true if the specified Element exists in the persistent storage,
60 * false otherwise.
61 *
62 * @param anElement Element to find in this persistent storage.
63 * @return true if Element exists in the persistent storage, false otherwise
64 * @throws DaoException
65 * @throws IllegalArgumentException 'anId' must not be null.
66 */
67 public boolean
68 contains(Element anElement)
69 throws DaoException, IllegalArgumentException;
70
71 //------------------------------------------------------------------------
72 /**
73 * Returns the total number of records. Provides a high-level reusable means
74 * to do a <code>"SELECT * FROM ..."</code>. Noteworthy that every call to
75 * this function will trigger a new execution of a statement. Therefore if
76 * the count value is needed several times in the client code it is a good
77 * idea to cache it there.
78 *
79 * @return total number of records
80 * @throws DaoException
81 */
82 public int
83 count()
84 throws DaoException;
85
86 //------------------------------------------------------------------------
87 /**
88 * Returns the Element matching the given ID. Retrieves an Element from
89 * the persistent storage using as input its ID.
90 *
91 * @param anId ID of the Element to retrieve.
92 * @return Element matching the given ID
93 * @throws DaoException
94 * @throws IllegalArgumentException 'anId' must not be null.
95 */
96 public Element
97 findById(Id anId)
98 throws DaoException, IllegalArgumentException;
99
100 //------------------------------------------------------------------------
101 /**
102 * Returns all Elements from the persistent storage.
103 *
104 * @return all Elements from the persistent storage.
105 * @throws DaoException
106 */
107 public List<Element>
108 findAll()
109 throws DaoException;
110
111 //------------------------------------------------------------------------
112 /**
113 * Returns the {@link ISession} adapted from the implementation-specific
114 *
115 * @see IAdapter
116 * @return {@link ISession} adapted from the implementation-specific
117 */
118 public ISession
119 getSession();
120
121 //------------------------------------------------------------------------
122 /**
123 * Returns the {@link ITransaction} adapted from the implementation-specific
124 *
125 * @see IAdapter
126 * @return {@link ITransaction} adapted from the implementation-specific
127 */
128 public ITransaction
129 getTransaction();
130 }