1 //----------------------------------------------------------------------
2 //
3 // PerfectJPattern: "Design patterns are good but components are better!"
4 // ISession.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 org.perfectjpattern.core.api.structural.adapter.*;
24
25 /**
26 * Abstract definition of Session available for the DAO implementation.
27 * The DAO API exposes this interface but it will be automatically adapted
28 * from the underlying JPA-specific implementation (see {@link IAdapter}).
29 * <br/><br/>
30 * JPA and specific implementations define similar abstractions e.g.
31 * Session vs EntityManager but despite their similarities, their types
32 * actually mismatch making it difficult to provide a generic unified DAO
33 * solution.
34 * <br/><br/>
35 * Note that this is a subset of the functionality that the underlying
36 * implementation offers. This is the subset required to make the DAO
37 * portable. If required, it is possible to get the underlying
38 * implementation using {@link ISession#getDelegate()}
39 *
40 * @author <a href="mailto:bravegag@hotmail.com">Giovanni Azua</a>
41 * @version $Revision: 1.0 $Date: Feb 10, 2009 5:47:08 PM $
42 */
43 public
44 interface ISession
45 {
46 //------------------------------------------------------------------------
47 // public
48 //------------------------------------------------------------------------
49 /**
50 * Clears the {@link Session}, removing all cached changes without
51 * applying them. The underlying implementation is JPA implementation-
52 * specific.
53 *
54 * @throws DaoException
55 */
56 public void
57 clear()
58 throws DaoException;
59
60 //------------------------------------------------------------------------
61 /**
62 * Closes the {@link Session}. The underlying implementation is JPA
63 * implementation-specific.
64 *
65 * @throws DaoException
66 */
67 public void
68 close()
69 throws DaoException;
70
71 //------------------------------------------------------------------------
72 /**
73 * Flushes the {@link Session} by applying all cached changes to the
74 * persistent store. The underlying implementation is JPA implementation-
75 * specific.
76 *
77 * @throws DaoException
78 */
79 public void
80 flush()
81 throws DaoException;
82
83 //------------------------------------------------------------------------
84 /**
85 * Returns true if the instance belongs to the current persistence context,
86 * false otherwise
87 *
88 * @param anEntity The entity to check
89 * @return true if the instance belongs to the current persistence context,
90 * false otherwise
91 */
92 public boolean
93 contains(Object anEntity);
94
95 //------------------------------------------------------------------------
96 /**
97 * Returns the Entity instance if found, null if the entity does not exist
98 *
99 * @param <E>
100 * @param aPersistentClass Persistent class
101 * @param anId The Id to look for
102 * @return Entity instance if found, null if the entity does not exist
103 */
104 public <E> E
105 find(Class<E> aPersistentClass, Object anId);
106
107 //------------------------------------------------------------------------
108 /**
109 * Returns the {@link ITransaction} adapted from the implementation-specific
110 *
111 * @see IAdapter
112 * @return {@link ITransaction} adapted from the implementation-specific
113 */
114 public ITransaction
115 getTransaction();
116
117 //------------------------------------------------------------------------
118 /**
119 * Removes Object from the persistent store
120 *
121 * @param anObject The Object to remove
122 */
123 public void
124 remove(Object anObject);
125
126 //------------------------------------------------------------------------
127 /**
128 * Returns the Id of the newly persisted Object. Creates the Object in
129 * the persistent store. Note that not all adapted implementations will
130 * return an Id e.g. adapted Hibernate does but using pure JPA will not.
131 *
132 * @param anObject The Object to persist
133 * @return Id of the newly persisted Object
134 */
135 public <Id> Id
136 persist(Object anObject);
137
138 //------------------------------------------------------------------------
139 /**
140 * Updates the Object in the persistent store
141 *
142 * @param anObject The Object to update
143 */
144 public void
145 update(Object anObject);
146
147 //------------------------------------------------------------------------
148 /**
149 * Refresh the state of the instance from the database, overwriting
150 * changes made to the entity, if any
151 *
152 * @param anObject The Object to refresh
153 */
154 public void
155 refresh(Object anObject);
156
157 //------------------------------------------------------------------------
158 /**
159 * Returns instance of JPA implementation-specific Query for executing
160 * JPA-specific Queries e.g. HQL queries.
161 *
162 * @param aSqlString SQL query input
163 * @return instance of JPA implementation-specific Query
164 */
165 public IQuery
166 createQuery(String aSqlString);
167
168 //------------------------------------------------------------------------
169 /**
170 * Returns instance of JPA implementation-specific Query for executing
171 * native SQL queries.
172 *
173 * @param aSql SQL query input
174 * @return instance of JPA implementation-specific Query
175 */
176 public IQuery
177 createNativeQuery(String aSqlString, Class<?> aPersistentClass);
178
179 //------------------------------------------------------------------------
180 /**
181 * Returns the implementation-specific Session
182 *
183 * @return implementation-specific Session
184 */
185 public <S> S
186 getDelegate();
187 }