1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // IBaseDao.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 /**
24 * <b>Data Access Object (DAO) Pattern</b>: Abstracts from any direct type of
25 * database or persistence mechanism. Provides specific operations without
26 * exposing details of the database.
27 * <br/><br/>
28 * <b>Responsibility</b> : Base Data Access Object definition including:
29 * <br/>
30 * <br/>
31 * <ul>
32 * <li>Creating a new record in the underlying persistent storage</li>
33 * <li>Reading existing records from the underlying persistence
34 * storage through the finder methods as defined in {@link IBaseReadOnlyDao}
35 * </li>
36 * <li>Update an existing record in the underlying persistent storage</li>
37 * <li>Delete an existing record in the underlying persistent storage</li>
38 * <li>Delete all records from the underlying persistent storage</li>
39 * </ul>
40 *
41 * @param <Id> Identification type
42 * @param <Element> Element type
43 *
44 * @see <a href="http://en.wikipedia.org/wiki/Data_Access_Object">Data Access
45 * Object wiki definition</a>
46 *
47 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
48 * @version $Revision: 1.0 $Date: Feb 19, 2009 11:08:28 AM $
49 */
50 public
51 interface IBaseDao<Id, Element>
52 extends IBaseReadOnlyDao<Id, Element>
53 {
54 //------------------------------------------------------------------------
55 // public
56 //------------------------------------------------------------------------
57 /**
58 * Returns the ID of the newly created Element. Creates an Element in the
59 * persistent storage and returns its ID.
60 *
61 * @param anElement Element to create
62 * @return ID of the newly created Element
63 * @throws DaoException
64 * @throws IllegalArgumentException 'anElement' must not be null.
65 */
66 public Id
67 create(Element anElement)
68 throws DaoException, IllegalArgumentException;
69
70 //------------------------------------------------------------------------
71 /**
72 * Returns true if the Element was updated, false otherwise i.e. the
73 * Element was not found. Updates the given Element in the persistent
74 * storage.
75 *
76 * @param anElement Element to update
77 * @return true if the Element was updated, false otherwise.
78 * @throws DaoException
79 * @throws IllegalArgumentException 'anElement' must not be null.
80 */
81 public boolean
82 update(Element anElement)
83 throws DaoException, IllegalArgumentException;
84
85 //------------------------------------------------------------------------
86 /**
87 * Returns true if the Element was deleted, false otherwise i.e. the
88 * Element was not found. Deletes the given Element from the persistent
89 * storage.
90 *
91 * @param anElement Element to delete
92 * @return true if the Element was deleted, false otherwise.
93 * @throws DaoException
94 * @throws IllegalArgumentException 'anElement' must not be null.
95 */
96 public boolean
97 delete(Element anElement)
98 throws DaoException, IllegalArgumentException;
99
100 //------------------------------------------------------------------------
101 /**
102 * Deletes all Element from the persistent storage.
103 *
104 * @throws DaoException
105 */
106 public void
107 deleteAll()
108 throws DaoException;
109 }