001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr;
005:
006: import org.xml.sax.ContentHandler;
007:
008: import javax.jcr.nodetype.ConstraintViolationException;
009: import javax.jcr.nodetype.NodeTypeManager;
010: import javax.jcr.observation.ObservationManager;
011: import javax.jcr.query.QueryManager;
012: import javax.jcr.version.Version;
013: import javax.jcr.version.VersionException;
014: import javax.jcr.lock.LockException;
015: import java.io.IOException;
016: import java.io.InputStream;
017:
018: /**
019: * The <code>Workspace</code> object represents a "view" of an actual repository workspace
020: * entity as seen through the authorization settings of its associated <code>Session</code>.
021: * Each <code>Workspace</code> object is associated one-to-one with a <code>Session</code>
022: * object. The <code>Workspace</code> object can be acquired by calling
023: * <code>{@link Session#getWorkspace()}</code> on the associated <code>Session</code> object.
024: */
025: public interface Workspace {
026:
027: /**
028: * Returns the <code>Session</code> object through which this <code>Workspace</code>
029: * object was acquired.
030: *
031: * @return a <code>{@link Session}</code> object.
032: */
033: public Session getSession();
034:
035: /**
036: * Returns the name of the actual persistent workspace represented by this
037: * <code>Workspace</code> object. This the name used in <code>Repository.login</code>.
038: *
039: * @return the name of this workspace.
040: */
041: public String getName();
042:
043: /**
044: * This method copies the node at <code>srcAbsPath</code> to the new
045: * location at <code>destAbsPath</code>. Returns the path of the node at its
046: * new position. Note that the returned path will indicate the resulting
047: * same-name sibling index of the destination, if necessary, unlike the
048: * supplied <code>destAbsPath</code> parameter (see below).
049: * <p/>
050: * This operation is performed entirely within the persistent workspace, it
051: * does not involve transient storage and therefore does not require a
052: * <code>save</code>.
053: * <p/>
054: * The new copies of nodes are automatically given new identifiers and
055: * referenceable nodes in particular are always given new referenceable
056: * identifiers.
057: * <p/>
058: * When the source subtree in a <code>copy</code> operation includes both a reference
059: * property (<code>P</code>) and the node to which it refers (<code>N</code>)
060: * then not only does the new copy of the referenceable node (<code>N'<code>)
061: * get a new identifier but the new copy of the reference property (<code>P'</code>)
062: * is changed so that it points to <code>N'</code>, thus preserving the
063: * reference within the subtree.
064: * <p/>
065: * The <code>destAbsPath</code> provided must not have an index on its final
066: * element. If it does then a <code>RepositoryException</code> is thrown.
067: * Strictly speaking, the <code>destAbsPath</code> parameter is actually an
068: * <i>absolute path</i> to the parent node of the new location, appended
069: * with the new <i>name</i> desired for the copied node. It does not specify
070: * a position within the child node ordering. If ordering is supported by
071: * the node type of the parent node of the new location, then the new copy
072: * of the node is appended to the end of the child node list. The resulting
073: * position within a same-name sibling set can, however, be determined from
074: * the path returned by this method, which will include an index if one is
075: * required.
076: * <p/>
077: * This method cannot be used to copy just an individual property by itself.
078: * It copies an entire node and its subtree (including, of course, any properties contained therein).
079: * <p/>
080: * A <code>ConstraintViolationException</code> is thrown if the operation would violate a node-type
081: * or other implementation-specific constraint.
082: * <p/>
083: * A <code>VersionException</code> is thrown if the parent node of <code>destAbsPath</code> is
084: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
085: * checked-in.
086: * <p/>
087: * An <code>AccessDeniedException</code> is thrown if the current session (i.e. the session that
088: * was used to acquire this <code>Workspace</code> object) does not have sufficient access rights
089: * to complete the operation.
090: * <p/>
091: * A <code>PathNotFoundException</code> is thrown if the node at <code>srcAbsPath</code> or the
092: * parent of <code>destAbsPath</code> does not exist.
093: * <p/>
094: * An <code>ItemExistException</code> is thrown if a node already exists at
095: * <code>destAbsPath</code> and same-name siblings are not allowed. Note that
096: * if a property already exists at <code>destAbsPath</code>, the operation
097: * succeeds, since a node may have a child node and property with the same name.
098: * <p/>
099: * A <code>LockException</code> is thrown if a lock prevents the copy.
100: *
101: * @param srcAbsPath the path of the node to be copied.
102: * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
103: * is to be copied.
104: * @return the path of the node at its new position.
105: * @throws ConstraintViolationException if the operation would violate a
106: * node-type or other implementation-specific constraint.
107: * @throws VersionException if the parent node of <code>destAbsPath</code> is
108: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
109: * checked-in.
110: * @throws AccessDeniedException if the current session does not have
111: * sufficient access rights to complete the operation.
112: * @throws PathNotFoundException if the node at <code>srcAbsPath</code> or
113: * the parent of <code>destAbsPath</code> does not exist.
114: * @throws ItemExistsException if a node already exists at
115: * <code>destAbsPath</code> and same-name siblings are not allowed.
116: * @throws LockException if a lock prevents the copy.
117: * @throws RepositoryException if the last element of <code>destAbsPath</code>
118: * has an index or if another error occurs.
119: */
120: public String copy(String srcAbsPath, String destAbsPath)
121: throws ConstraintViolationException, VersionException,
122: AccessDeniedException, PathNotFoundException,
123: ItemExistsException, LockException, RepositoryException;
124:
125: /**
126: * This method copies the subtree at <code>srcAbsPath</code> in <code>srcWorkspace</code>
127: * to <code>destAbsPath</code> in <code>this</code> workspace. Returns the
128: * path of the node at its new position. Note that the returned path will
129: * indicate the resulting same-name sibling index of the destination,
130: * if necessary, unlike the supplied <code>destAbsPath</code> parameter
131: * (see below).
132: * <p/>
133: * Unlike <code>clone</code>, this method does assign new referenceable
134: * identifiers to the new copies of referenceable nodes. In the case of
135: * non-referenceable nodes, this method <i>may</i> assign new identifiers. This
136: * operation is performed entirely within the persistent workspace, it does
137: * not involve transient storage and therefore does not require a <code>save</code>.
138: * <p/>
139: * When the source subtree in a <code>copy</code> operation includes both a reference
140: * property (<code>P</code>) and the node to which it refers (<code>N</code>)
141: * then not only does the new copy of the referenceable node (<code>N'<code>)
142: * get a new identifier but the new copy of the reference property (<code>P'</code>)
143: * is changed so that it points to <code>N'</code>, thus preserving the
144: * reference within the subtree.
145: * <p/>
146: * The <code>destAbsPath</code> provided must not have an index on its final
147: * element. If it does then a <code>RepositoryException</code> is thrown.
148: * Strictly speaking, the <code>destAbsPath</code> parameter is actually an
149: * <i>absolute path</i> to the parent node of the new location, appended
150: * with the new <i>name</i> desired for the copied node. It does not specify
151: * a position within the child node ordering. If ordering is supported by
152: * the node type of the parent node of the new location, then the new copy
153: * of the node is appended to the end of the child node list. The resulting
154: * position within a same-name sibling set can, however, be determined from
155: * the path returned by this method, which will include an index if one is
156: * required.
157: * <p/>
158: * This method cannot be used to copy just an individual property by itself.
159: * It copies an entire node and its subtree (including, of course, any properties contained therein).
160: * <p/>
161: * A <code>NoSuchWorkspaceException</code> is thrown if <code>srcWorkspace</code> does not
162: * exist or if the current Session does not have permission to access it.
163: * <p/>
164: * A <code>ConstraintViolationException</code> is thrown if the operation would violate a node-type
165: * or other implementation-specific constraint.
166: * <p/>
167: * A <code>VersionException</code> is thrown if the parent node of <code>destAbsPath</code> is
168: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
169: * checked-in.
170: * <p/>
171: * An <code>AccessDeniedException</code> is thrown if the current session (i.e. the session that
172: * was used to acquire this <code>Workspace</code> object) does not have sufficient access rights
173: * to complete the operation.
174: * <p/>
175: * A <code>PathNotFoundException</code> is thrown if the node at <code>srcAbsPath</code> in
176: * <code>srcWorkspace</code> or the parent of <code>destAbsPath</code> in this workspace does not exist.
177: * <p/>
178: * An <code>ItemExistException</code> is thrown if a node already exists at
179: * <code>destAbsPath</code> and same-name siblings are not allowed. Note that
180: * if a property already exists at <code>destAbsPath</code>, the operation
181: * succeeds, since a node may have a child node and property with the same name.
182: * <p/>
183: * A <code>LockException</code> is thrown if a lock prevents the copy.
184: *
185: * @param srcWorkspace the name of the workspace from which the copy is to be made.
186: * @param srcAbsPath the path of the node to be copied.
187: * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
188: * is to be copied in <code>this</code> workspace.
189: * @return the path of the node at its new position.
190: * @throws NoSuchWorkspaceException if <code>srcWorkspace</code> does not
191: * exist or if the current <code>Session</code> does not have permission to access it.
192: * @throws ConstraintViolationException if the operation would violate a
193: * node-type or other implementation-specific constraint
194: * @throws VersionException if the parent node of <code>destAbsPath</code> is
195: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
196: * checked-in.
197: * @throws AccessDeniedException if the current session does have permission to access
198: * <code>srcWorkspace</code> but otherwise does not have sufficient access rights to
199: * complete the operation.
200: * @throws PathNotFoundException if the node at <code>srcAbsPath</code> in <code>srcWorkspace</code> or
201: * the parent of <code>destAbsPath</code> in this workspace does not exist.
202: * @throws ItemExistsException if a node already exists at <code>destAbsPath</code>
203: * and same-name siblings are not allowed.
204: * @throws LockException if a lock prevents the copy.
205: * @throws RepositoryException if the last element of <code>destAbsPath</code>
206: * has an index or if another error occurs.
207: */
208: public String copy(String srcWorkspace, String srcAbsPath,
209: String destAbsPath) throws NoSuchWorkspaceException,
210: ConstraintViolationException, VersionException,
211: AccessDeniedException, PathNotFoundException,
212: ItemExistsException, LockException, RepositoryException;
213:
214: /**
215: * Clones the subtree at the node <code>srcAbsPath</code> in <code>srcWorkspace</code> to the new location at
216: * <code>destAbsPath</code> in <code>this</code> workspace. Returns the path
217: * of the node at its new position. Note that the returned
218: * path will indicate the resulting same-name sibling index of the
219: * destination, if necessary, unlike the supplied <code>destAbsPath</code>
220: * parameter (see below).
221: * <p/>
222: * Unlike the signature of <code>copy</code> that copies between workspaces,
223: * this method <i>does not</i> assign new identifiers to the newly cloned nodes
224: * but preserves the identifiers of their respective source nodes. This applies
225: * to both referenceable and non-referenceable nodes.
226: * <p/>
227: * In some implementations there may be cases where preservation of a
228: * non-referenceable identifier is not possible, due to how non-referenceable
229: * identifiers are constructed in that implementation. In such a case this
230: * method will throw a <code>RepositoryException</code>.
231: * <p/>
232: * If <code>removeExisting</code> is true and an existing node in this workspace
233: * (the destination workspace) has the same identifier as a node being cloned from
234: * <code>srcWorkspace</code>, then the incoming node takes precedence, and the
235: * existing node (and its subtree) is removed. If <code>removeExisting</code>
236: * is false then an identifier collision causes this method to throw a
237: * <code>ItemExistsException</code> and no changes are made.
238: * <p/>
239: * If successful, the change is persisted immediately, there is no need to call <code>save</code>.
240: * <p/>
241: * The <code>destAbsPath</code> provided must not have an index on its final
242: * element. If it does then a <code>RepositoryException</code> is thrown.
243: * Strictly speaking, the <code>destAbsPath</code> parameter is actually an
244: * <i>absolute path</i> to the parent node of the new location, appended
245: * with the new <i>name</i> desired for the cloned node. It does not specify
246: * a position within the child node ordering. If ordering is supported by
247: * the node type of the parent node of the new location, then the new clone
248: * of the node is appended to the end of the child node list. The resulting
249: * position within a same-name sibling set can, however, be determined from
250: * the path returned by this method, which will include an index, if one is
251: * required.
252: * <p/>
253: * This method cannot be used to clone just an individual property by itself. It clones an
254: * entire node and its subtree (including, of course, any properties contained therein).
255: * <p/>
256: * A <code>NoSuchWorkspaceException</code> is thrown if <code>srcWorkspace</code> does not
257: * exist or if the current <code>Session</code> does not have permission to access it.
258: * <p/>
259: * A <code>ConstraintViolationException</code> is thrown if the operation would violate a node-type
260: * or other implementation-specific constraint or if <code>srcWorkspace</code> is the name of this workspace.
261: * In other words, if an attempt is made to clone a subtree into the same workspace.
262: * <p/>
263: * A <code>VersionException</code> is thrown if the parent node of <code>destAbsPath</code> is
264: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
265: * checked-in. This exception will also be thrown if <code>removeExisting</code> is <code>true</code>,
266: * and an identifier conflict occurs that would require the moving and/or altering of a node that is checked-in.
267: * <p/>
268: * An <code>AccessDeniedException</code> is thrown if the current session (i.e. the session that
269: * was used to acquire this <code>Workspace</code> object) does not have sufficient access rights
270: * to complete the operation.
271: * <p/>
272: * A <code>PathNotFoundException</code> is thrown if the node at <code>srcAbsPath</code> in
273: * <code>srcWorkspace</code> or the parent of <code>destAbsPath</code> in this workspace does not exist.
274: * <p/>
275: * An <code>ItemExistsException</code> is thrown if a node or property already exists at
276: * <code>destAbsPath</code>
277: * <p/>
278: * An <code>ItemExistException</code> is thrown if a node already exists at
279: * <code>destAbsPath</code> and same-name siblings are not allowed or if
280: * <code>removeExisting</code> is <code>false</code> and an identifier conflict occurs.
281: * <p/>
282: * Note that if a property already exists at <code>destAbsPath</code>, the
283: * operation succeeds, since a node may have a child node and property with
284: * the same name.
285: * <p/>
286: * A <code>LockException</code> is thrown if a lock prevents the clone.
287: *
288: * @param srcWorkspace The name of the workspace from which the node is to be copied.
289: * @param srcAbsPath the path of the node to be copied in <code>srcWorkspace</code>.
290: * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
291: * is to be copied in <code>this</code> workspace.
292: * @param removeExisting if <code>false</code> then this method throws an
293: * <code>ItemExistsException</code> on identifier conflict with an incoming node.
294: * If <code>true</code> then a identifier conflict is resolved by removing the existing node
295: * from its location in this workspace and cloning (copying in) the one from
296: * <code>srcWorkspace</code>.
297: * @return the path of the node at its new position.
298: * @throws NoSuchWorkspaceException if <code>destWorkspace</code> does not exist.
299: * @throws ConstraintViolationException if the operation would violate a
300: * node-type or other implementation-specific constraint.
301: * @throws VersionException if the parent node of <code>destAbsPath</code> is
302: * versionable and checked-in, or is non-versionable but its nearest versionable ancestor is
303: * checked-in. This exception will also be thrown if <code>removeExisting</code> is <code>true</code>,
304: * and an identifier conflict occurs that would require the moving and/or altering of a node that is checked-in.
305: * @throws AccessDeniedException if the current session does not have
306: * sufficient access rights to complete the operation.
307: * @throws PathNotFoundException if the node at <code>srcAbsPath</code> in
308: * <code>srcWorkspace</code> or the parent of <code>destAbsPath</code> in this workspace does not exist.
309: * @throws ItemExistsException if a node already exists at
310: * <code>destAbsPath</code> and same-name siblings are not allowed or if
311: * <code>removeExisting</code> is <code>false</code> and an identifier conflict occurs.
312: * @throws LockException if a lock prevents the clone.
313: * @throws RepositoryException if the last element of <code>destAbsPath</code>
314: * has an index or if another error occurs.
315: */
316: public String clone(String srcWorkspace, String srcAbsPath,
317: String destAbsPath, boolean removeExisting)
318: throws NoSuchWorkspaceException,
319: ConstraintViolationException, VersionException,
320: AccessDeniedException, PathNotFoundException,
321: ItemExistsException, LockException, RepositoryException;
322:
323: /**
324: * Moves the node at <code>srcAbsPath</code> (and its entire subtree) to the
325: * new location at <code>destAbsPath</code>. Returns the path of the node at
326: * its new position. Note that the returned path will indicate the resulting
327: * same-name sibling index of the destination, if necessary, unlike the
328: * supplied <code>destAbsPath</code> parameter (see below).
329: * <p/>
330: * If successful,
331: * the change is persisted immediately, there is no need to call <code>save</code>.
332: * Note that this is in contrast to {@link Session#move} which operates within the
333: * transient space and hence requires a <code>save</code>.
334: * <p/>
335: * The identifiers of referenceable nodes must not be changed by a <code>move</code>.
336: * The identifiers of non-referenceable nodes <i>may</i> change.
337: * <p/>
338: * The <code>destAbsPath</code> provided must not
339: * have an index on its final element. If it does then a <code>RepositoryException</code>
340: * is thrown. Strictly speaking, the <code>destAbsPath</code> parameter is actually an <i>absolute path</i>
341: * to the parent node of the new location, appended with the new <i>name</i> desired for the
342: * moved node. It does not specify a position within the child node
343: * ordering. If ordering is supported by the node type of
344: * the parent node of the new location, then the newly moved node is appended to the end of the
345: * child node list. The resulting position within a same-name sibling set can,
346: * however, be determined from the path returned by this method,
347: * which will include an index if one is required.
348: * <p/>
349: * This method cannot be used to move just an individual property by itself.
350: * It moves an entire node and its subtree (including, of course, any properties contained therein).
351: * <p/>
352: * The identifiers of referenceable nodes must not be changed by a <code>move</code>.
353: * The identifiers of non-referenceable nodes may change.
354: * <p/>
355: * A <code>ConstraintViolationException</code> is thrown if the operation would violate a node-type
356: * or other implementation-specific constraint.
357: * <p/>
358: * A <code>VersionException</code> is thrown if the parent node of <code>destAbsPath</code>
359: * or the parent node of <code>srcAbsPath</code> is versionable and checked-in, or is
360: * non-versionable but its nearest versionable ancestor is checked-in.
361: * <p/>
362: * An <code>AccessDeniedException</code> is thrown if the current session (i.e. the session that
363: * was used to acquire this <code>Workspace</code> object) does not have sufficient access rights
364: * to complete the operation.
365: * <p/>
366: * A <code>PathNotFoundException</code> is thrown if the node at <code>srcAbsPath</code> or the
367: * parent of <code>destAbsPath</code> does not exist.
368: * <p/>
369: * An <code>ItemExistException</code> is thrown if a node already exists at
370: * <code>destAbsPath</code> and same-name siblings are not allowed.
371: * <p/>
372: * Note that if a property already exists at <code>destAbsPath</code>, the
373: * operation succeeds, since a node may have a child node and property with
374: * the same name
375: * <p/>
376: * A <code>LockException</code> if a lock prevents the move.
377: *
378: * @param srcAbsPath the path of the node to be moved.
379: * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
380: * is to be moved.
381: * @return the path of the node at its new position.
382: * @throws ConstraintViolationException if the operation would violate a
383: * node-type or other implementation-specific constraint
384: * @throws VersionException if the parent node of <code>destAbsPath</code>
385: * or the parent node of <code>srcAbsPath</code> is versionable and checked-in,
386: * or is non-versionable but its nearest versionable ancestor is checked-in.
387: * @throws AccessDeniedException if the current session (i.e. the session that
388: * was used to aqcuire this <code>Workspace</code> object) does not have
389: * sufficient access rights to complete the operation.
390: * @throws PathNotFoundException if the node at <code>srcAbsPath</code> or
391: * the parent of <code>destAbsPath</code> does not exist.
392: * @throws ItemExistsException if a node already exists at
393: * <code>destAbsPath</code> and same-name siblings are not allowed.
394: * @throws LockException if a lock prevents the move.
395: * @throws RepositoryException if the last element of <code>destAbsPath</code>
396: * has an index or if another error occurs.
397: */
398: public String move(String srcAbsPath, String destAbsPath)
399: throws ConstraintViolationException, VersionException,
400: AccessDeniedException, PathNotFoundException,
401: ItemExistsException, LockException, RepositoryException;
402:
403: /**
404: * Restores a set of versions at once. Used in cases where a "chicken and egg" problem of
405: * mutually referring <code>REFERENCE</code> properties would prevent the restore in any
406: * serial order.
407: * <p>
408: * If the restore succeeds the changes made to <code>this</code> node are
409: * persisted immediately, there is no need to call <code>save</code>.
410: * <p>
411: * The following restrictions apply to the set of versions specified:
412: * <p>
413: * If <code>S</code> is the set of versions being restored simultaneously,
414: * <ul>
415: * <li>
416: * For every version <code>V</code> in <code>S</code> that corresponds to
417: * a <i>missing</i> node, there must also be a parent of V in S.
418: * </li>
419: * <li>
420: * <code>S</code> must contain at least one version that corresponds to
421: * an existing node in the workspace.
422: * </li>
423: * <li>
424: * No <code>V</code> in <code>S</code> can be a root version (<code>jcr:rootVersion</code>).
425: * </li>
426: * </ul>
427: * If any of these restrictions does not hold, the restore will fail
428: * because the system will be unable to determine the path locations to which
429: * one or more versions are to be restored. In this case a
430: * <code>VersionException</code> is thrown.
431: * <p/>
432: * The versionable nodes in this workspace that correspond to the versions being restored
433: * define a set of (one or more) subtrees. An identifier collision occurs when this workspace
434: * contains a node <i>outside these subtrees</i> that has the same identifier as one of the nodes
435: * that would be introduced by the <code>restore</code> operation <i>into one of these subtrees</i>.
436: * The result in such a case is governed by the <code>removeExisting</code> flag.
437: * If <code>removeExisting</code> is <code>true</code> then the incoming node takes precedence,
438: * and the existing node (and its subtree) is removed. If <code>removeExisting</code>
439: * is <code>false</code> then a <code>ItemExistsException</code> is thrown and no changes are made.
440: * Note that this applies not only to cases where the restored
441: * node itself conflicts with an existing node but also to cases where a conflict occurs with any
442: * node that would be introduced into the workspace by the restore operation. In particular, conflicts
443: * involving subnodes of the restored node that have <code>OnParentVersion</code> settings of
444: * <code>COPY</code> or <code>VERSION</code> are also governed by the <code>removeExisting</code> flag.
445: * <p/>
446: * An <code>UnsupportedRepositoryOperationException</code> is thrown if one or more of the nodes to be restored
447: * is not versionable.
448: * <p/>
449: * An <code>InvalidItemStateException</code> is thrown if this <code>Session</code>
450: * has pending unsaved changes.
451: * <p/>
452: * A <code>LockException</code> is thrown if a lock prevents the restore.
453: *
454: * @param versions The set of versions to be restored
455: * @param removeExisting governs what happens on identifier collision.
456: *
457: * @throws ItemExistsException if <code>removeExisting</code> is <code>false</code>
458: * and an identifier collision occurs with a node being restored.
459: * @throws UnsupportedRepositoryOperationException if one or more of the nodes to be
460: * restored is not versionable.
461: * @throws VersionException if the set of versions to be restored is such that the
462: * original path location of one or more of the versions cannot be determined or
463: * if the <code>restore</code> would change the state of a existing verisonable
464: * node that is currently checked-in or if a root version (<code>jcr:rootVersion</code>)
465: * is among those being restored.
466: * @throws LockException if a lock prevents the restore.
467: * @throws InvalidItemStateException if this <code>Session</code> has pending unsaved changes.
468: * @throws RepositoryException if another error occurs.
469: */
470: public void restore(Version[] versions, boolean removeExisting)
471: throws ItemExistsException,
472: UnsupportedRepositoryOperationException, VersionException,
473: LockException, InvalidItemStateException,
474: RepositoryException;
475:
476: /**
477: * Returns the <code>QueryManager</code> object, through search methods are accessed.
478: *
479: * @throws RepositoryException if an error occurs.
480: * @return the <code>QueryManager</code> object.
481: */
482: public QueryManager getQueryManager() throws RepositoryException;
483:
484: /**
485: * Returns the <code>NamespaceRegistry</code> object, which is used to access the mapping between
486: * prefixes and namespaces. In level 2 repositories the <code>NamespaceRegistry</code> can also be
487: * used to change the namespace mappings.
488: *
489: * @throws RepositoryException if an error occurs.
490: * @return the <code>NamespaceRegistry</code>.
491: */
492: public NamespaceRegistry getNamespaceRegistry()
493: throws RepositoryException;
494:
495: /**
496: * Returns the <code>NodeTypeManager</code> through which node type
497: * information can be queried. There is one node type registry per
498: * repository, therefore the <code>NodeTypeManager</code> is not
499: * workspace-specific; it provides introspection methods for the
500: * global, repository-wide set of available node types. In
501: * repositories that support it, the <code>NodeTypeManager</code>
502: * can also be used to register new node types.
503: *
504: * @throws RepositoryException if an error occurs.
505: * @return a <code>NodeTypeManager</code> object.
506: */
507: public NodeTypeManager getNodeTypeManager()
508: throws RepositoryException;
509:
510: /**
511: * Returns the <code>ObservationManager</code> object.
512: * <p/>
513: * If the implementation does not support observation, an
514: * <code>UnsupportedRepositoryOperationException</code> is thrown.
515: *
516: * @throws UnsupportedRepositoryOperationException if the implementation does
517: * not support observation.
518: * @throws RepositoryException if an error occurs.
519: *
520: * @return an <code>ObservationManager</code> object.
521: */
522: public ObservationManager getObservationManager()
523: throws UnsupportedRepositoryOperationException,
524: RepositoryException;
525:
526: /**
527: * Returns a string array containing the names of all workspaces
528: * in this repository that are accessible to this user, given the
529: * <code>Credentials</code> that were used to get the <code>Session</code>
530: * to which this <code>Workspace</code> is tied.
531: * <p/>
532: * In order to access one of the listed workspaces, the user performs another
533: * <code>Repository.login</code>, specifying the name of the desired workspace,
534: * and receives a new <code>Session</code> object.
535: *
536: * @return string array of names of accessible workspaces.
537: * @throws RepositoryException if an error occurs
538: */
539: public String[] getAccessibleWorkspaceNames()
540: throws RepositoryException;
541:
542: /**
543: * Returns an <code>org.xml.sax.ContentHandler</code> which can be used to push SAX events into the repository.
544: * If the incoming XML stream (in the form of SAX events) does not appear to be a JCR system view XML document then it is
545: * interpreted as a document view XML document.
546: * <p>
547: * The incoming XML is deserialized into a subtree of items immediately below the node at
548: * <code>parentAbsPath</code>.
549: * <p>
550: * This method simply returns the <code>ContentHandler</code> without altering the state of the
551: * repository; the actual deserialization is done through the methods of the <code>ContentHandler</code>.
552: * Invalid XML data will cause the <code>ContentHandler</code> to throw a <code>SAXException</code>.
553: * <p>
554: * As SAX events are fed into the <code>ContentHandler</code>, changes are made directly at the
555: * workspace level, without going through the <code>Session</code>. As a result, there is not need
556: * to call <code>save</code>. The advantage of this
557: * direct-to-workspace method is that a large import will not result in a large cache of pending
558: * nodes in the <code>Session</code>. The disadvantage is that structures that violate node type constraints
559: * cannot be imported, fixed and then saved. Instead, a constraint violation will cause the
560: * <code>ContentHandler</code> to throw a <code>SAXException</code>. See <code>Session.getImportContentHandler</code> for a version of
561: * this method that <i>does</i> go through the <code>Session</code>.
562: * <p>
563: * The flag <code>uuidBehavior</code> governs how the identifiers of incoming (deserialized) nodes are
564: * handled. There are four options:
565: * <ul>
566: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming nodes are assigned newly
567: * created identifiers upon addition to the workspace. As a result identifier collisions never occur.
568: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an incoming node
569: * has the same identifier as a node already existing in the workspace, then the already exisitng node
570: * (and its subtree) is removed from wherever it may be in the workspace before the incoming node
571: * is added. Note that this can result in nodes "disappearing" from locations in the workspace that
572: * are remote from the location to which the incoming subtree is being written.
573: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}: If an incoming node
574: * has the same identifier as a node already existing in the workspace then the already existing node
575: * is replaced by the incoming node in the same position as the existing node. Note that this may
576: * result in the incoming subtree being disaggregated and "spread around" to different locations
577: * in the workspace. In the most extreme case this behavior may result in no node at all
578: * being added as child of <code>parentAbsPath</code>. This will occur if the topmost element
579: * of the incoming XML has the same identifier as an existing node elsewhere in the workspace.
580: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If an incoming node
581: * has the same identifier as a node already existing in the workspace then a <code>SAXException</code>
582: * is thrown by the returned <code>ContentHandler</code> during deserialization.
583: * </ul>
584: * A <code>SAXException</code> will be thrown by the returned <code>ContentHandler</code>
585: * during deserialization if the top-most element of the incoming XML would deserialize to
586: * a node with the same name as an existing child of <code>parentAbsPath</code> and that
587: * child does not allow same-name siblings.
588: * <p>
589: * A <code>SAXException</code> will also be thrown by the returned <code>ContentHandler</code>
590: * during deserialzation if <code>uuidBehavior</code> is set to
591: * <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code> and an incoming node has the same identifier as
592: * the node at <code>parentAbsPath</code> or one of its ancestors.
593: * <p>
594: * A <code>PathNotFoundException</code> is thrown if no node exists at <code>parentAbsPath</code>.
595: * <p>
596: * A <code>ConstraintViolationException</code> is thrown if the new subtree cannot be added to the node at
597: * <code>parentAbsPath</code> due to node-type or other implementation-specific constraints, and this can
598: * be determined before the first SAX event is sent. Unlike {@link Session#getImportContentHandler},
599: * this method also enforces node type constraints by throwing <code>SAXException</code>s during
600: * deserialization. However, which node type constraints are enforced depends upon whether node type
601: * information in the imported data is respected, and this is an implementation-specific issue.
602: * <p/>
603: * A <code>VersionException</code> is thrown if the node at <code>parentAbsPath</code> is versionable
604: * and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in.
605: * <p>
606: * A <code>LockException</code> is thrown if a lock prevents the addition ofthe subtree.
607: * <p>
608: * An <code>AccessDeniedException</code> is thrown if the session associated with this <code>Workspace</code> object does not have
609: * sufficient permissions to perform the import.
610: *
611: * @param parentAbsPath the absolute path of a node under which (as child) the imported subtree will be built.
612: * @param uuidBehavior a four-value flag that governs how incoming identifiers are handled.
613: * @return an org.xml.sax.ContentHandler whose methods may be called to feed SAX events into the deserializer.
614: *
615: * @throws PathNotFoundException if no node exists at <code>parentAbsPath</code>.
616: * @throws ConstraintViolationException if the new subtree cannot be added to the node at
617: * <code>parentAbsPath</code> due to node-type or other implementation-specific constraints,
618: * and this can be determined before the first SAX event is sent.
619: * @throws VersionException if the node at <code>parentAbsPath</code> is versionable
620: * and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in.
621: * @throws LockException if a lock prevents the addition of the subtree.
622: * @throws AccessDeniedException if the session associated with this <code>Workspace</code> object does not have
623: * sufficient permissions to perform the import.
624: * @throws RepositoryException if another error occurs.
625: */
626: public ContentHandler getImportContentHandler(String parentAbsPath,
627: int uuidBehavior) throws PathNotFoundException,
628: ConstraintViolationException, VersionException,
629: LockException, AccessDeniedException, RepositoryException;
630:
631: /**
632: * Deserializes an XML document and adds the resulting item subtree as a child of the node at
633: * <code>parentAbsPath</code>.
634: * <p/>
635: * If the incoming XML stream does not appear to be a JCR system view XML document then it is interpreted as a
636: * <b>document view</b> XML document.
637: * <p/>
638: * The passed <code>InputStream</code> is closed before this method returns either
639: * normally or because of an exception.
640: * <p/>
641: * Changes are made directly at the workspace level, without going through the <code>Session</code>.
642: * As a result, there is not need to call <code>save</code>. The advantage of this
643: * direct-to-workspace method is that a large import will not result in a large cache of
644: * pending nodes in the <code>Session</code>. The disadvantage is that invalid data cannot
645: * be imported, fixed and then saved. Instead, invalid data will cause this method to throw an
646: * <code>InvalidSerializedDataException</code>. See <code>Session.importXML</code> for
647: * a version of this method that <i>does</i> go through the <code>Session</code>.
648: * <p/>
649: * The flag <code>uuidBehavior</code> governs how the identifiers of incoming (deserialized) nodes are
650: * handled. There are four options:
651: * <ul>
652: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming nodes are assigned newly
653: * created identifiers upon additon to the workspace. As a result identifier collisions never occur.
654: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an incoming node
655: * has the same identifier as a node already existing in the workspace then the already exisitng node
656: * (and its subtree) is removed from wherever it may be in the workspace before the incoming node
657: * is added. Note that this can result in nodes "disappearing" from locations in the workspace that
658: * are remote from the location to which the incoming subtree is being written. If an incoming node
659: * has the same identifier as the existing root node of this workspace then
660: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}: If an incoming node
661: * has the same identifier as a node already existing in the workspace then the already existing node
662: * is replaced by the incoming node in the same position as the existing node. Note that this may
663: * result in the incoming subtree being disaggregated and "spread around" to different locations
664: * in the workspace. In the most extreme edge case this behavior may result in no node at all
665: * being added as child of <code>parentAbsPath</code>. This will occur if the topmost element
666: * of the incoming XML has the same identifier as an existing node elsewhere in the workspace.
667: * <li>{@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If an incoming node
668: * has the same identifier as a node already existing in the workspace then an <code>ItemExistsException</code>
669: * is thrown.
670: * </ul>
671: * An <code>ItemExistsException</code> will be thrown if the top-most element
672: * of the incoming XML would deserialize to a node with the same name as an
673: * existing child of <code>parentAbsPath</code> and that child does not allow
674: * same-name siblings.
675: * <p/>
676: * An <code>IOException</code> is thrown if an I/O error occurs.
677: * <p/>
678: * If no node exists at <code>parentAbsPath</code>, a <code>PathNotFoundException</code> is thrown.
679: * <p/>
680: * If node-type or other implementation-specific constraints prevent the
681: * addition of the subtree, a <code>ConstraintViolationException</code> is
682: * thrown.
683: * <p/>
684: * A <code>ConstraintViolationException</code> will also be thrown if
685: * <code>uuidBehavior</code> is set to <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code>
686: * and an incoming node has the same identifier as the node at <code>parentAbsPath</code>
687: * or one of its ancestors.
688: * <p/>
689: * A <code>VersionException</code> is thrown if the node at <code>parentAbsPath</code> is versionable
690: * and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in.
691: * <p/>
692: * A <code>LockException</code> is thrown if a lock prevents the addition of the subtree.
693: * <p/>
694: * An <code>AccessDeniedException</code> is thrown if the session associated with this <code>Workspace</code> object does not have
695: * sufficient permissions to perform the import.
696: *
697: * @param parentAbsPath the absolute path of the node below which the deserialized subtree is added.
698: * @param in The <code>Inputstream</code> from which the XML to be deserilaized is read.
699: * @param uuidBehavior a four-value flag that governs how incoming identifiers are handled.
700: *
701: * @throws java.io.IOException if an error during an I/O operation occurs.
702: * @throws PathNotFoundException if no node exists at <code>parentAbsPath</code>.
703: * @throws ConstraintViolationException if node-type or other implementation-specific constraints
704: * prevent the addition of the subtree or if <code>uuidBehavior</code>
705: * is set to <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code> and an incoming node has the same
706: * identifier as the node at <code>parentAbsPath</code> or one of its ancestors.
707: * @throws VersionException if the node at <code>parentAbsPath</code> is versionable
708: * and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in.
709: * @throws InvalidSerializedDataException if incoming stream is not a valid XML document.
710: * @throws ItemExistsException if the top-most element of the incoming XML would deserialize
711: * to a node with the same name as an existing child of <code>parentAbsPath</code> and that
712: * child does not allow same-name siblings, or if a <code>uuidBehavior</code> is set to
713: * <code>IMPORT_UUID_COLLISION_THROW</code> and an identifier collision occurs.
714: * @throws LockException if a lock prevents the addition of the subtree.
715: * @throws AccessDeniedException if the session associated with this <code>Workspace</code> object does not have
716: * sufficient permissions to perform the import.
717: * @throws RepositoryException is another error occurs.
718: */
719: public void importXML(String parentAbsPath, InputStream in,
720: int uuidBehavior) throws IOException,
721: PathNotFoundException, ItemExistsException,
722: ConstraintViolationException,
723: InvalidSerializedDataException, LockException,
724: AccessDeniedException, RepositoryException;
725:
726: /**
727: * Creates a new <code>Workspace</code> with the specified
728: * <code>name</code>. The new workspace is empty, meaning it contains only
729: * root node.
730: * <p/>
731: * The new workspace can be accessed through a <code>login</code>
732: * specifying its name.
733: * <p/>
734: * Throws an <code>AccessDeniedException</code> if the session through which
735: * this <code>Workspace</code> object was acquired does not have permission
736: * to create the new workspace.
737: * <p/>
738: * Throws an <code>UnsupportedRepositoryOperationException</code> if the repository does
739: * not support the creation of workspaces.
740: * <p/>
741: * A <code>RepositoryException</code> is thrown if another error occurs.
742: *
743: * @param name A <code>String</code>, the name of the new workspace.
744: * @throws AccessDeniedException if the session through which
745: * this <code>Workspace</code> object was acquired does not have permission
746: * to create the new workspace.
747: * @throws UnsupportedRepositoryOperationException if the repository does
748: * not support the creation of workspaces.
749: * @throws RepositoryException if another error occurs.
750: * @since JCR 2.0
751: */
752: public void createWorkspace(String name)
753: throws AccessDeniedException,
754: UnsupportedRepositoryOperationException,
755: RepositoryException;
756:
757: /**
758: * Creates a new <code>Workspace</code> with the specified <code>name</code>
759: * initialized with a <code>clone</code> of the content of the workspace
760: * <code>srcWorkspace</code>. Semantically, this method is equivalent to
761: * creating a new workspace and manually cloning <code>srcWorkspace</code>
762: * to it; however, this method may assist some implementations in optimizing
763: * subsequent <code>Node.update</code> and <code>Node.merge</code> calls
764: * between the new workspace and its source.
765: * <p/>
766: * The new workspace can be accessed through a <code>login</code>
767: * specifying its name.
768: * <p/>
769: * Throws an <code>AccessDeniedException</code> if the session through which
770: * this <code>Workspace</code> object was acquired does not have permission
771: * to create the new workspace.
772: * <p/>
773: * Throws an <code>UnsupportedRepositoryOperationException</code> if the repository does
774: * not support the creation of workspaces.
775: * <p/>
776: * A <code>RepositoryException</code> is thrown if another error occurs.
777: *
778: * @param name A <code>String</code>, the name of the new workspace.
779: * @param srcWorkspace The name of the workspace from which the new workspace is to be cloned.
780: * @throws AccessDeniedException if the session through which
781: * this <code>Workspace</code> object was acquired does not have permission
782: * to create the new workspace.
783: * @throws UnsupportedRepositoryOperationException if the repository does
784: * not support the creation of workspaces.
785: * @throws RepositoryException if another error occurs.
786: * @since JCR 2.0
787: */
788: public void createWorkspace(String name, String srcWorkspace)
789: throws AccessDeniedException,
790: UnsupportedRepositoryOperationException,
791: RepositoryException;
792:
793: /**
794: * Deletes the workspace with the specified <code>name</code> from the
795: * repository, deleting all content within it.
796: * <p/>
797: * Throws an <code>AccessDeniedException</code> if the session through which
798: * this <code>Workspace</code> object was acquired does not have permission
799: * to remove the workspace.
800: * <p/>
801: * Throws an <code>UnsupportedRepositoryOperationException</code> if the
802: * repository does not support the removal of workspaces.
803: *
804: * @param name A <code>String</code>, the name of the workspace to be deleted.
805: * @throws AccessDeniedException if the session through which
806: * this <code>Workspace</code> object was acquired does not have permission
807: * to remove the workspace.
808: * @throws UnsupportedRepositoryOperationException if the
809: * repository does not support the removal of workspaces.
810: * @throws RepositoryException if another error occurs.
811: * @since JCR 2.0
812: */
813: public void deleteWorkspace(String name)
814: throws AccessDeniedException,
815: UnsupportedRepositoryOperationException,
816: RepositoryException;
817:
818: /**
819: * This method creates a new <code>nt:activity</code> at an implementation-determined
820: * location in the <code>/jcr:system/jcr:activities</code> subtree.
821: * <p/>
822: * The repository may, but is not required to, use the <code>title</code>
823: * as a hint for what to name the new activity node. The new activity
824: * <code>Node</code> is returned.
825: * <p/>
826: * The new node is persisted immediately and does not require a <code>save</code>.
827: * <p/>
828: * An <code>UnsupportedRepositoryOperationException</code> is thrown if the
829: * repository does not support activities.
830: * <p/>
831: * A <code>RepositoryException</code> is thrown if another error occurs.
832: *
833: * @param title a String
834: * @return the new activity <code>Node</code>.
835: * @throws UnsupportedRepositoryOperationException if the repsoitory does not support activities.
836: * @throws RepositoryException if another error occurs.
837: * @since JCR 2.0
838: */
839: public Node createActivity(String title)
840: throws UnsupportedRepositoryOperationException,
841: RepositoryException;
842:
843: /**
844: * This method merges the changes that were made under the specified
845: * activity into this workspace.
846: * <p/>
847: * An activity <i>A</i> will be associated with a set of versions through the
848: * <code>jcr:activity</code> reference of each version node in the set.
849: * We call each such associated version a <i>member of A</i>.
850: * <p/>
851: * For each version history <i>H</i> that contains one or more members of
852: * <i>A</i>, one such member will be the latest member of <i>A</i> in <i>H</i>.
853: * The latest member of <i>A</i> in <i>H</i> is the version in <i>H</i> that
854: * is a member of <i>A</i> and that has no successor versions (to any degree)
855: * that are also members of <i>A</i>.
856: * <p/>
857: * The set of versions that are the latest members of <i>A</i> in their
858: * respective version histories is called the change set of <i>A</i>. It
859: * fully describes the changes made under the activity <i>A</i>.
860: * <p/>
861: * This method performs a shallow merge into this workspace of each version
862: * in the change set of the activity specified by <code>activityNode</code>.
863: * If there is no corresponding node in this workspace for a given member of
864: * the change set, that member is ignored.
865: * <p/>
866: * This method returns a <code>NodeIterator</code> over all versionable
867: * nodes in the subtree that received a merge result of <i>fail</i>.
868: * <p/>
869: * A <code>VersionException</code> is thrown if the specified node is not
870: * an <code>nt:activity</code> node.
871: * <p/>
872: * A <code>MergeException</code> is thrown in the same cases as in a regular
873: * shallow merge (see {@link Node#merge(String, boolean, boolean)}).
874: * <p/>
875: * If the current session does not have sufficient permissions to perform
876: * the operation, then an <code>AccessDeniedException</code> is thrown.
877: * <p/>
878: * An <code>InvalidItemStateException</code> is thrown if this <code>Session</code>
879: * has pending unsaved changes.
880: * <p/>
881: * A <code>LockException</code> is thrown if a lock prevents the merge.
882: * <p/>
883: * An <code>UnsupportedRepositoryOperationException</code> is thrown if
884: * this operation is not supported by this implementation.
885: * <p/>
886: * A <code>RepositoryException</code> is thrown if another error occurs.
887: *
888: * @param activityNode an <code>nt:activity</code> node
889: * @return a <code>NodeIterator</code>
890: * @throws AccessDeniedException if the current session does not have sufficient
891: * rights to perform the operation.
892: * @throws VersionException if the specified node is not an <code>nt:activity</code> node.
893: * @throws MergeException in the same cases as in a regular shallow merge
894: * (see {@link Node#merge(String, boolean, boolean)}).
895: * @throws LockException if a lock prevents the merge.
896: * @throws InvalidItemStateException if this <code>Session</code> has pending unsaved changes.
897: * @throws RepositoryException if another error occurs.
898: * @since JCR 2.0
899: */
900: public NodeIterator merge(Node activityNode)
901: throws VersionException, AccessDeniedException,
902: MergeException, LockException, InvalidItemStateException,
903: RepositoryException;
904: }
|