View Javadoc

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  }