1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // GenericReadOnlyDao.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 /**
26 * <b>Data Access Object (DAO) Pattern</b>: Abstracts from any direct type of
27 * database or persistence mechanism. Provides specific operations without
28 * exposing details of the database.
29 * <br/><br/>
30 * <b>Responsibility</b> : Partial Data Access Object abstraction
31 * providing Read-Only features:
32 * <br/>
33 * <br/>
34 * <ul>
35 * <li>Find an Element by ID</li>
36 * <li>Find all Elements of a given type in the persistent storage</li>
37 * <li>Find all Elements in the persistent storage matching a given Example</li>
38 * <li>Ask if it contains a given Element</li>
39 * <li>Ask for the total number of records</li>
40 * </ul>
41 *
42 * @param <Id> Identification type
43 * @param <Element> Element type
44 *
45 * @see <a href="http://en.wikipedia.org/wiki/Data_Access_Object">Data Access
46 * Object wiki definition</a>
47 * @see <a href="http://www.ibm.com/developerworks/java/library/j-genericdao.
48 * html">Don't repeat the DAO!</a>
49 *
50 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
51 * @version $Revision: 1.0 $ $Date: Nov 26, 2007 8:23:22 PM $
52 */
53 public
54 interface IGenericReadOnlyDao<Id, Element>
55 extends IBaseReadOnlyDao<Id, Element>
56 {
57 //------------------------------------------------------------------------
58 // public
59 //------------------------------------------------------------------------
60 /**
61 * Returns the List of Elements that match the search criteria specified
62 * through the Example. Searches all Elements that match the properties set
63 * in the Example Element.
64 *
65 * @param anElement Example Element to search for.
66 * @param anExcludeProperties Array of Java Bean property names to exclude
67 * @return List of Elements that match the search criteria specified
68 * through all properties set in the Example.
69 * @throws DaoException
70 * @throws IllegalArgumentException 'anId' must not be null
71 * @throws IllegalArgumentException 'anExcludeProperties' must not be null
72 */
73 public List<Element>
74 findByExample(Element anElement, String ... anExcludeProperties)
75 throws DaoException, IllegalArgumentException;
76 }