1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.portals.graffito.jcr.persistence;
17
18 import java.util.Collection;
19 import java.util.Iterator;
20
21 import javax.jcr.version.VersionException;
22
23 import org.apache.portals.graffito.jcr.exception.IllegalUnlockException;
24 import org.apache.portals.graffito.jcr.exception.LockedException;
25 import org.apache.portals.graffito.jcr.exception.PersistenceException;
26 import org.apache.portals.graffito.jcr.query.Query;
27 import org.apache.portals.graffito.jcr.query.QueryManager;
28 import org.apache.portals.graffito.jcr.version.Version;
29 import org.apache.portals.graffito.jcr.version.VersionIterator;
30
31 /***
32 * The persistence manager encapsulates a JCR session.
33 * This is the main component used to manage objects into the JCR repository.
34 *
35 * @author Sandro Boehme
36 * @author <a href="mailto:christophe.lombart@sword-technologies.com">Lombart Christophe </a>
37 *
38 */
39 public interface PersistenceManager
40 {
41
42 /***
43 * Check if an object exists
44 * @param path the object path
45 * @return true if the item exists
46 * @throws PersistenceException when it is not possible to check if the item exist
47 */
48 public boolean objectExists(String path) throws PersistenceException;
49
50
51 /***
52 * Can this persistence manager insert, update, delete, ... that type?
53 *
54 * @param clazz class for question
55 * @return <code>true</code> if the class is persistence
56 */
57 boolean isPersistent(Class clazz);
58
59
60 /***
61 * Insert an object into the JCR repository
62 *
63 * @param object the object to add
64 * @throws PersistenceException when it is not possible to insert the object
65 */
66 public void insert(Object object) throws PersistenceException;
67
68 /***
69 * Update an object
70 *
71 * @param object the object to update
72 * @throws PersistenceException when it is not possible to update the object
73 */
74 public void update(Object object) throws PersistenceException;
75
76 /***
77 * Get an object from the JCR repository
78 * @param path the object path
79 * @return the object found or null
80 *
81 * @throws PersistenceException when it is not possible to retrieve the object
82 */
83 public Object getObject( String path) throws PersistenceException;
84
85 /***
86 * Get an object from the JCR repository
87 * @param path the object path
88 * @param versionNumber The desired object version number
89 * @return the object found or null
90 *
91 * @throws PersistenceException when it is not possible to retrieve the object
92 */
93 public Object getObject(String path, String versionNumber) throws PersistenceException;
94
95 /***
96 * Get an object from the JCR repository
97 * @param objectClass the object class
98 * @param path the object path
99 * @return the object found or null
100 *
101 * @throws PersistenceException when it is not possible to retrieve the object
102 */
103 public Object getObject(Class objectClass, String path) throws PersistenceException;
104
105 /***
106 * Get an object from the JCR repository
107 * @param objectClass the object class
108 * @param path the object path
109 * @param versionNumber The desired object version number
110 * @return the object found or null
111 *
112 * @throws PersistenceException when it is not possible to retrieve the object
113 */
114 public Object getObject(Class objectClass, String path, String versionNumber) throws PersistenceException;
115
116
117 /***
118 * Retrieve the specified attribute for the given persistent object.
119 * this attribute is either a bean or a collection. This method is usefull if the corresponding descriptor has an autoRetrieve="false"
120 *
121 * @param object The persistent object
122 * @param attributeName The name of the attribute to retrieve
123 */
124 public void retrieveMappedAttribute(Object object, String attributeName);
125
126
127 /***
128 * Retrieve all mapped attributes for the given persistent object.
129 * @param object The persistent object
130 */
131 public void retrieveAllMappedAttributes(Object object);
132
133
134 /***
135 * Remove an object from a JCR repository
136 * @param path the object path
137 * @throws PersistenceException when it is not possible to remove the object
138 *
139 */
140 public void remove(String path) throws PersistenceException;
141
142
143 /***
144 * Remove an object from a JCR repository
145 * @param object the object to remove
146 * @throws PersistenceException when it is not possible to remove the object
147 *
148 */
149 public void remove(Object object) throws PersistenceException;
150
151 /***
152 * Remove all objects matching to a query
153 * @param query The query used to find the objects to remove
154 * @throws PersistenceException when it is not possible to remove all objects
155 *
156 */
157 public void remove(Query query) throws PersistenceException;
158
159
160 /***
161 * Retrieve an object matching to a query
162 * @param query The Graffito Query object used to seach the object
163 * @return The object found or null
164 * @throws PersistenceException when it is not possible to retrieve the object
165 *
166 */
167 public Object getObject(Query query) throws PersistenceException;
168
169
170 /***
171 * Retrieve some objects matching to a query
172 * @param query The query used to seach the objects
173 * @return a collection of objects found
174 * @throws PersistenceException when it is not possible to retrieve the objects
175 *
176 */
177 public Collection getObjects(Query query) throws PersistenceException;
178
179
180 /***
181 * Retrieve some objects matching to a query.
182 *
183 * @param query The query used to seach the objects
184 * @return an iterator of objects found
185 * @throws PersistenceException when it is not possible to retrieve the objects
186 */
187 public Iterator getObjectIterator (Query query) throws PersistenceException;
188
189
190 /***
191 * Checkout - Create a new version
192 * This is only possible if the object is based on mix:versionable node type
193 *
194 * @param path The object path
195 * @throws VersionException when it is not possible to create a new version
196 */
197 public void checkout(String path) throws VersionException;
198
199 /***
200 * Checkin an object
201 * @param path the object path
202 * @throws VersionException when it is not possible to checkin
203 */
204 public void checkin(String path) throws VersionException;
205
206 /***
207 * Checkin an object and apply some labels to this new version
208 * Within a particular object path, a given label may appear a maximum of once
209 * @param path The object path
210 * @param versionLabels the version labels to apply to the new version
211 * @throws VersionException when it is possible to checkin
212 */
213 public void checkin(String path, String[] versionLabels) throws VersionException;
214
215
216 /***
217 * Get all version labels assigned to a particular object version
218 * @param path the object path
219 * @param versionName the object version name (1.0, ...)
220 * @return a array of string (version labels)
221 * @throws VersionException when it is not to get all version labels
222 */
223 public String[] getVersionLabels(String path, String versionName) throws VersionException;
224
225
226 /***
227 * Get all version labels assigned to all versions
228 * @param path the object path
229 * @return a array of string (version labels)
230 * @throws VersionException when it is not to get all version labels
231 */
232 public String[] getAllVersionLabels(String path) throws VersionException;
233
234 /***
235 * Add a new label to a particular version
236 * @param path the object path
237 * @param versionName the object versio name (1.0, 1.1, ...)
238 * @param versionLabel The new label to apply
239 * @throws VersionException when it is not possible to add a new version label to this version
240 */
241 public void addVersionLabel(String path, String versionName, String versionLabel) throws VersionException;
242
243
244 /***
245 * Get all object versions
246 * @param path the object path
247 * @return a version iterator
248 * @throws VersionException when it is not possible to retrieve all versions
249 */
250 public VersionIterator getAllVersions(String path) throws VersionException;
251
252 /***
253 * Get the first object version
254 * @param path the object path
255 * @return the first version found
256 * @throws VersionException when it is not possible to get the root version
257 */
258 public Version getRootVersion(String path) throws VersionException;
259
260 /***
261 * Get the lastest object version
262 * @param path the object path
263 * @return the last version found
264 * @throws VersionException when it is not possible to get the last version
265 */
266 public Version getBaseVersion(String path) throws VersionException;
267 /***
268 * Get a particular version
269 * @param path the object path
270 * @param versionName the version name
271 * @return the version found or null
272 * @throws VersionException when it is not possible to retrieve this particular version
273 */
274 public Version getVersion(String path, String versionName) throws VersionException;
275
276
277 /***
278 * Save all modifications made by the persistence manager
279 *
280 * @throws PersistenceException when it is not possible to save all pending operation into the JCR repo
281 */
282 public void save() throws PersistenceException;
283
284 /***
285 * Close the session
286 * @throws PersistenceException when it is not possible to logout
287 */
288 public void logout() throws PersistenceException;
289
290 /***
291 * Lock object saved on {@param path }.
292 *
293 * @param path
294 * path to saved object.
295 * @param isDeep
296 * is lock deep? See JCR spec: 8.4.3 Shallow and Deep Locks
297 * @param isSessionScoped
298 * is lock session scoped? See JCR spec: Session-scoped and Open-scoped Locks
299 * @return lock token - see JCR spec: 8.4.6 Lock Token; Other user with this token can perform unlock
300 *
301 * @throws LockedException
302 * if path is locked (cannot lock same path again)
303 */
304 public String lock(String path, boolean isDeep, boolean isSessionScoped) throws LockedException;
305
306 /***
307 * Unlock object stored on {@param path }.
308 *
309 * @param path path to stored object
310 *
311 *
312 * @param lockToken
313 * see JCR spec: 8.4.6 Lock Token; can be <code>null</code>
314 *
315 * @throws IllegalUnlockException
316 * throws if the current operation does not own the current lock
317 */
318 public void unlock(String path, String lockToken) throws IllegalUnlockException;
319
320 /***
321 * Is that path locked?
322 *
323 * @param absPath
324 * @return <code>true</code> if path locked
325 */
326 public boolean isLocked(String absPath);
327
328 /***
329 *
330 * @return The query manager reference
331 */
332 public QueryManager getQueryManager();
333
334 }