0001: /*
0002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
0003: */
0004: package javax.jcr;
0005:
0006: import org.xml.sax.ContentHandler;
0007: import org.xml.sax.SAXException;
0008: import javax.jcr.lock.LockException;
0009: import javax.jcr.lock.Lock;
0010: import javax.jcr.nodetype.ConstraintViolationException;
0011: import javax.jcr.nodetype.NoSuchNodeTypeException;
0012: import javax.jcr.version.VersionException;
0013: import javax.jcr.security.AccessControlManager;
0014: import java.io.IOException;
0015: import java.io.InputStream;
0016: import java.io.OutputStream;
0017:
0018: /**
0019: * The <code>Session</code> object provides read and (in level 2) write access to the content of a
0020: * particular workspace in the repository.
0021: * <p/>
0022: * The <code>Session</code> object is returned by {@link Repository#login(Credentials, String) Repository.login()}.
0023: * It encapsulates both the authorization settings of a particular user (as specified by the
0024: * passed <code>Credentials</code>) and a binding to the workspace specified by the
0025: * <code>workspaceName</code> passed on <code>login</code>.
0026: * <p/>
0027: * Each <code>Session</code> object is associated one-to-one with a <code>Workspace</code> object.
0028: * The <code>Workspace</code> object represents a "view" of an actual repository workspace entity
0029: * as seen through the authorization settings of its associated <code>Session</code>.
0030: */
0031: public interface Session {
0032:
0033: /**
0034: * Returns the <code>Repository</code> object through which this session was
0035: * acquired.
0036: *
0037: * @return a <code>{@link Repository}</code> object.
0038: */
0039: public Repository getRepository();
0040:
0041: /**
0042: * Gets the user ID associated with this <code>Session</code>. How the
0043: * user ID is set is up to the implementation, it may be a string passed in
0044: * as part of the credentials or it may be a string acquired in some other
0045: * way. This method is free to return an "anonymous user ID" or
0046: * <code>null</code>.
0047: *
0048: * @return the user ID associated with this <code>Session</code>.
0049: */
0050: public String getUserID();
0051:
0052: /**
0053: * Returns the names of the attributes set in this session as a result of the
0054: * <code>Credentials</code> that were used to acquire it. Not all
0055: * <code>Credentials</code> implementations will contain attributes (though,
0056: * for example, <code>SimpleCredentials</code> does allow for them). This
0057: * method returns an empty array if the <code>Credentials</code> instance did
0058: * not provide attributes.
0059: *
0060: * @return A string array containing the names of all attributes passed in
0061: * the credentials used to acquire this session.
0062: */
0063: public String[] getAttributeNames();
0064:
0065: /**
0066: * Returns the value of the named attribute as an <code>Object</code>, or
0067: * <code>null</code> if no attribute of the given name exists.
0068: * See {@link Session#getAttributeNames}.
0069: *
0070: * @param name the name of an attribute passed in the credentials used to
0071: * acquire this session.
0072: *
0073: * @return the value of the attribute or <code>null</code> if no attribute
0074: * of the given name exists.
0075: */
0076: public Object getAttribute(String name);
0077:
0078: /**
0079: * Returns the <code>Workspace</code> attached to this <code>Session</code>.
0080: *
0081: * @return a <code>{@link Workspace}</code> object.
0082: */
0083: public Workspace getWorkspace();
0084:
0085: /**
0086: * Returns the root node of the workspace, "/". This node is the main
0087: * access point to the content of the workspace.
0088: * <p/>
0089: * A <code>RepositoryException</code> is thrown if an error occurs.
0090: *
0091: * @return The root node of the workspace: a <code>{@link Node}</code> object.
0092: *
0093: * @throws RepositoryException if an error occurs.
0094: */
0095: public Node getRootNode() throws RepositoryException;
0096:
0097: /**
0098: * Returns a new session in accordance with the specified (new) Credentials.
0099: * Allows the current user to "impersonate" another using incomplete or
0100: * relaxed credentials requirements (perhaps including a user name but no
0101: * password, for example), assuming that this <code>Session</code> gives
0102: * them that permission.
0103: * <p/>
0104: * The new <code>Session</code> is tied to a new <code>Workspace</code> instance.
0105: * In other words, <code>Workspace</code> instances are not re-used. However,
0106: * the <code>Workspace</code> instance returned represents the same actual
0107: * persistent workspace entity in the repository as is represented by the
0108: * <code>Workspace</code> object tied to this <code>Session</code>.
0109: * <p/>
0110: * A <code>LoginException</code> is thrown if this session does not have
0111: * sufficient permissions to perform the operation.
0112: * <p/>
0113: * A <code>RepositoryException</code> is thrown if another error occurs.
0114: *
0115: * @param credentials A <code>Credentials</code> object
0116: * @return a <code>Session</code> object
0117: * @throws LoginException if the current session does not have sufficient
0118: * permissions to perform the operation.
0119: * @throws RepositoryException if another error occurs.
0120: */
0121: public Session impersonate(Credentials credentials)
0122: throws LoginException, RepositoryException;
0123:
0124: /**
0125: * Returns the node specifed by the given UUID. Only applies to nodes that
0126: * expose a UUID, in other words, those of mixin node type
0127: * <code>mix:referenceable</code>
0128: *
0129: * @deprecated As of JCR 2.0, {@link #getNodeByIdentifier(String)} should
0130: * be used instead.
0131: *
0132: * @param uuid A universally unique identifier.
0133: * @return A <code>Node</code>.
0134: * @throws ItemNotFoundException if the specified UUID is not found.
0135: * @throws RepositoryException if another error occurs.
0136: */
0137: public Node getNodeByUUID(String uuid)
0138: throws ItemNotFoundException, RepositoryException;
0139:
0140: /**
0141: * Returns the node specified by the given identifier. Applies to both
0142: * referenceable and non-referenceable nodes.
0143: * <p/>
0144: * An <code>ItemNotFoundException</code> is thrown if no node with the
0145: * specified identifier exists. This exception is also thrown if this
0146: * <code>Session<code> does not have read access to the node with the
0147: * specified identifier.
0148: * <p/>
0149: * A <code>RepositoryException</code> is thrown if another error occurs.
0150: *
0151: * @param id An identifier.
0152: * @return A <code>Node</code>.
0153: * @throws ItemNotFoundException if the specified identifier is not found.
0154: * @throws RepositoryException if another error occurs.
0155: * @since JCR 2.0
0156: */
0157: public Node getNodeByIdentifier(String id)
0158: throws ItemNotFoundException, RepositoryException;
0159:
0160: /**
0161: * Returns the node at the specified absolute path in the workspace.
0162: * If no such node exists, then it returns the property at the specified path.
0163: * If no such property exists a <code>PathNotFoundException</code> is thrown.
0164: * <p/>
0165: * This method should only be used if the application does not know whether
0166: * the item at the indicated path is property or node. In cases where the
0167: * application has this information, either {@link #getNode} or
0168: * {@link #getProperty} should be used, as appropriate. In many repository
0169: * implementations the node and property-specific methods are likely to be
0170: * more efficient than <code>getItem</code>.
0171: * <p/>
0172: * A <code>RepositoryException</code> is thrown if another error occurs.
0173: *
0174: * @param absPath An absolute path.
0175: * @return the specified <code>Item</code>.
0176: * @throws PathNotFoundException if the specified path cannot be found.
0177: * @throws RepositoryException if another error occurs.
0178: */
0179: public Item getItem(String absPath) throws PathNotFoundException,
0180: RepositoryException;
0181:
0182: /**
0183: * Returns the node at the specified absolute path in the workspace.
0184: * If no node exists, then a <code>PathNotFoundException</code> is thrown.
0185: *
0186: * @param absPath An absolute path.
0187: * @return the specified <code>Node</code>.
0188: * @throws PathNotFoundException If no node exists.
0189: * @throws RepositoryException If another error occurs.
0190: * @since JCR 2.0
0191: */
0192: public Node getNode(String absPath) throws PathNotFoundException,
0193: RepositoryException;
0194:
0195: /**
0196: * Returns the property at the specified absolute path in the workspace.
0197: * If no property exists, then a <code>PathNotFoundException</code> is thrown.
0198: *
0199: * @param absPath An absolute path.
0200: * @return the specified <code>Property</code>.
0201: * @throws PathNotFoundException If no property exists.
0202: * @throws RepositoryException if another error occurs.
0203: * @since JCR 2.0
0204: */
0205: public Property getProperty(String absPath)
0206: throws PathNotFoundException, RepositoryException;
0207:
0208: /**
0209: * Returns <code>true</code> if an item exists at <code>absPath</code>
0210: * and this <code>Session</code> has read access to it; otherwise returns
0211: * <code>false</code>.
0212: * <p/>
0213: * Throws a <code>RepositoryException</code> if <code>absPath</code> is not
0214: * a well-formed absolute path.
0215: *
0216: * @param absPath An absolute path.
0217: * @return a <code>boolean</code>
0218: * @throws RepositoryException if <code>absPath</code> is not a well-formed
0219: * absolute path.
0220: */
0221: public boolean itemExists(String absPath)
0222: throws RepositoryException;
0223:
0224: /**
0225: * Returns <code>true</code> if a node exists at <code>absPath</code>
0226: * and this <code>Session</code> has read access to it; otherwise returns
0227: * <code>false</code>.
0228: * <p/>
0229: * Throws a <code>RepositoryException</code> if <code>absPath</code>
0230: * is not a well-formed absolute path.
0231: *
0232: * @param absPath An absolute path.
0233: * @return a <code>boolean</code>
0234: * @throws RepositoryException if <code>absPath</code> is not a well-formed
0235: * absolute path.
0236: * @since JCR 2.0
0237: */
0238: public boolean nodeExists(String absPath)
0239: throws RepositoryException;
0240:
0241: /**
0242: * Returns <code>true</code> if a property exists at <code>absPath</code>
0243: * and this <code>Session</code> has read access to it; otherwise returns
0244: * <code>false</code>.
0245: * <p/>
0246: * Throws a <code>RepositoryException</code> if <code>absPath</code>
0247: * is not a well-formed absolute path.
0248: *
0249: * @param absPath An absolute path.
0250: * @return a <code>boolean</code>
0251: * @throws RepositoryException if <code>absPath</code> is not a well-formed
0252: * absolute path.
0253: * @since JCR 2.0
0254: */
0255: boolean propertyExists(String absPath) throws RepositoryException;
0256:
0257: /**
0258: * Moves the node at <code>srcAbsPath</code> (and its entire subtree) to the
0259: * new location at <code>destAbsPath</code>. Returns the path of the node at
0260: * its new position. Note that the returned path will indicate the resulting
0261: * same-name sibling index of the destination (if necessary), unlike the
0262: * supplied <code>destAbsPath</code> parameter (see below).
0263: * <p>
0264: * In order to persist the change, a <code>save</code>
0265: * must be called on either the session or a common ancestor to both the source and destination locations.
0266: * <p/>
0267: * The identifiers of referenceable nodes must not be changed by a
0268: * <code>move</code>. The identifiers of non-referenceable nodes <i>may</i> change.
0269: * <p/>
0270: * A <code>ConstraintViolationException</code> is thrown either immediately or on <code>save</code>
0271: * if performing this operation would violate a node type or implementation-specific constraint.
0272: * Implementations may differ on when this validation is performed.
0273: * <p>
0274: * As well, a <code>ConstraintViolationException</code> will be thrown on
0275: * <code>save</code> if an attempt is made to seperately <code>save</code>
0276: * either the source or destination node.
0277: * <p>
0278: * Note that this behaviour differs from that of
0279: * {@link Workspace#move}, which operates directly in the persistent
0280: * workspace and does not require a <code>save</code>.
0281: * <p/>
0282: * The <code>destAbsPath</code> provided must not have an index on its final
0283: * element. If it does then a <code>RepositoryException</code> is thrown.
0284: * Strictly speaking, the <code>destAbsPath</code> parameter is actually an
0285: * <i>absolute path</i> to the parent node of the new location, appended
0286: * with the new <i>name</i> desired for the moved node. It does not specify
0287: * a position within the child node ordering (if such ordering is
0288: * supported). If ordering is supported by the node type of the parent node
0289: * of the new location, then the newly moved node is appended to the end of
0290: * the child node list. The resulting position within a same-name sibling set
0291: * can, however, be determined from the path returned by this method, which
0292: * will include an index if one is required.
0293: * <p/>
0294: * This method cannot be used to move just an individual property by itself.
0295: * It moves an entire node and its subtree (including, of course, any properties
0296: * contained therein).
0297: * <p/>
0298: * If no node exists at <code>srcAbsPath</code> or no node exists one level above <code>destAbsPath</code>
0299: * (in other words, there is no node that will serve as the parent of the moved item) then a
0300: * <code>PathNotFoundException</code> is thrown either immediately or on <code>save</code>.
0301: * Implementations may differ on when this validation is performed.
0302: * <p/>
0303: * An <code>ItemExistsException</code> is thrown either immediately or on <code>save</code>
0304: * if a node already exists at <code>destAbsPath</code> and same-name siblings are not allowed.
0305: * Implementations may differ on when this validation is performed.
0306: * <p/>
0307: * Note that if a property already exists at <code>destAbsPath</code>, the
0308: * operation succeeds, since a node may have a child node and property with
0309: * the same name.
0310: * <p/>
0311: * A <code>VersionException</code> is thrown either immediately or on <code>save</code>
0312: * if the parent node of <code>destAbsPath</code> or the parent node of <code>srcAbsPath] is versionable and
0313: * checked-in, or is non-versionable and its nearest versionable ancestor is checked-in.
0314: * Implementations may differ on when this validation is performed.
0315: * <p/>
0316: * A <code>LockException</code> is thrown either immediately or on <code>save</code>
0317: * if a lock prevents the <code>move</code>. Implementations may differ on when this validation is performed.
0318: *
0319: * @param srcAbsPath the root of the subtree to be moved.
0320: * @param destAbsPath the location to which the subtree is to be moved.
0321: * @return the path of the node at its new position.
0322: * @throws ItemExistsException if a node already exists at <code>destAbsPath</code>
0323: * and same-name siblings are not allowed.
0324: * @throws PathNotFoundException if either <code>srcAbsPath</code> or <code>destAbsPath</code> cannot be found and this
0325: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0326: * @throws VersionException if the parent node of <code>destAbsPath</code> or the parent node of <code>srcAbsPath</code>
0327: * is versionable and checked-in, or or is non-verionable and its nearest versionable ancestor is checked-in and this
0328: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0329: * @throws ConstraintViolationException if a node-type or other constraint violation is detected immediately and this
0330: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0331: * @throws LockException if the move operation would violate a lock and this
0332: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0333: * @throws RepositoryException if the last element of <code>destAbsPath</code> has an index or if another error occurs.
0334: */
0335: public String move(String srcAbsPath, String destAbsPath)
0336: throws ItemExistsException, PathNotFoundException,
0337: VersionException, ConstraintViolationException,
0338: LockException, RepositoryException;
0339:
0340: /**
0341: * Validates all pending changes currently recorded in this <code>Session</code>. If validation of <i>all</i>
0342: * pending changes succeeds, then this change information is cleared from the <code>Session</code>.
0343: * If the <code>save</code> occurs outside a transaction, the changes are persisted and thus
0344: * made visible to other <code>Sessions</code>. If the <code>save</code> occurs within a transaction,
0345: * the changes are not persisted until the transaction is committed.
0346: * <p/>
0347: * If validation fails, then no pending changes are saved and they remain recorded on the <code>Session</code>.
0348: * There is no best-effort or partial <code>save</code>.
0349: * <p/>
0350: * The item in persistent storage to which a transient item is saved is
0351: * determined by matching identifiers and paths.
0352: * <p/>
0353: * An <code>AccessDeniedException</code> will be thrown if any of the changes
0354: * to be persisted would violate the access privileges of this
0355: * <code>Session</code>.
0356: * <p/>
0357: * If any of the changes to be persisted would cause the removal of a node
0358: * that is currently the target of a <code>REFERENCE</code> property then a
0359: * <code>ReferentialIntegrityException</code> is thrown, provided that this <code>Session</code> has
0360: * read access to that <code>REFERENCE</code> property. If, on the other hand, this
0361: * <code>Session</code> does not have read access to the <code>REFERENCE</code> property in question,
0362: * then an <code>AccessDeniedException</code> is thrown instead.
0363: * <p/>
0364: * An <code>ItemExistsException</code> will be thrown if any of the changes
0365: * to be persisted would be prevented by the presence of an already existing
0366: * item in the workspace.
0367: * <p/>
0368: * A <code>ConstraintViolationException</code> will be thrown if any of the
0369: * changes to be persisted would violate a node type restriction.
0370: * Additionally, a repository may use this exception to enforce
0371: * implementation- or configuration-dependant restrictions.
0372: * <p/>
0373: * An <code>InvalidItemStateException</code> is thrown if any of the
0374: * changes to be persisted conflicts with a change already persisted
0375: * through another session and the implementation is such that this
0376: * conflict can only be detected at <code>save</code>-time and therefore was not
0377: * detected earlier, at change-time.
0378: * <p/>
0379: * A <code>VersionException</code> is thrown if the <code>save</code> would make a result in
0380: * a change to persistent storage that would violate the read-only status of a
0381: * checked-in node.
0382: * <p/>
0383: * A <code>LockException</code> is thrown if the <code>save</code> would result
0384: * in a change to persistent storage that would violate a lock.
0385: * <p/>
0386: * A <code>NoSuchNodeTypeException</code> is thrown if the <code>save</code> would result in the
0387: * addition of a node with an unrecognized node type.
0388: * <p/>
0389: * A <code>RepositoryException</code> will be thrown if another error
0390: * occurs.
0391: *
0392: * @throws AccessDeniedException if any of the changes to be persisted would violate
0393: * the access privileges of the this <code>Session</code>. Also thrown if any of the
0394: * changes to be persisted would cause the removal of a node that is currently
0395: * referenced by a <code>REFERENCE</code> property that this Session
0396: * <i>does not</i> have read access to.
0397: * @throws ItemExistsException if any of the changes
0398: * to be persisted would be prevented by the presence of an already existing
0399: * item in the workspace.
0400: * @throws ConstraintViolationException if any of the changes to be persisted would
0401: * violate a node type or restriction. Additionally, a repository may use this
0402: * exception to enforce implementation- or configuration-dependent restrictions.
0403: * @throws InvalidItemStateException if any of the
0404: * changes to be persisted conflicts with a change already persisted
0405: * through another session and the implementation is such that this
0406: * conflict can only be detected at <code>save</code>-time and therefore was not
0407: * detected earlier, at change-time.
0408: * @throws ReferentialIntegrityException if any of the
0409: * changes to be persisted would cause the removal of a node that is currently
0410: * referenced by a <code>REFERENCE</code> property that this <code>Session</code>
0411: * has read access to.
0412: * @throws VersionException if the <code>save</code> would make a result in
0413: * a change to persistent storage that would violate the read-only status of a
0414: * checked-in node.
0415: * @throws LockException if the <code>save</code> would result in a
0416: * change to persistent storage that would violate a lock.
0417: * @throws NoSuchNodeTypeException if the <code>save</code> would result in the
0418: * addition of a node with an unrecognized node type.
0419: * @throws RepositoryException if another error occurs.
0420: */
0421: public void save() throws AccessDeniedException,
0422: ItemExistsException, ConstraintViolationException,
0423: InvalidItemStateException, VersionException, LockException,
0424: NoSuchNodeTypeException, RepositoryException;
0425:
0426: /**
0427: * If <code>keepChanges</code> is <code>false</code>, this method discards all pending changes
0428: * currently recorded in this <code>Session</code> and returns all items to reflect the current
0429: * saved state. Outside a transaction this state is simply the current state of persistent storage.
0430: * Within a transaction, this state will reflect persistent storage as modified by changes that have
0431: * been saved but not yet committed.
0432: * <p>
0433: * If <code>keepChanges</code> is true then pending change are not discarded but items that do not
0434: * have changes pending have their state refreshed to reflect the current saved state, thus revealing
0435: * changes made by other sessions.
0436: *
0437: * @param keepChanges a boolean
0438: * @throws RepositoryException if an error occurs.
0439: */
0440: public void refresh(boolean keepChanges) throws RepositoryException;
0441:
0442: /**
0443: * Returns <code>true</code> if this session holds pending (that is, unsaved) changes;
0444: * otherwise returns <code>false</code>.
0445: *
0446: * @return a boolean
0447: * @throws RepositoryException if an error occurs
0448: */
0449: public boolean hasPendingChanges() throws RepositoryException;
0450:
0451: /**
0452: * This method returns a <code>ValueFactory</code> that is used to create <code>Value</code> objects
0453: * for use when setting repository properties.
0454: * <p/>
0455: * If writing to the repository is not supported (because this is a level 1-only
0456: * implementation, for example) an <code>UnsupportedRepositoryOperationException</code>
0457: * will be thrown.
0458: *
0459: * @return a <code>ValueFactory</code>
0460: * @throws UnsupportedRepositoryOperationException if writing to the repository is not supported.
0461: * @throws RepositoryException if another error occurs.
0462: */
0463: public ValueFactory getValueFactory()
0464: throws UnsupportedRepositoryOperationException,
0465: RepositoryException;
0466:
0467: /**
0468: * Determines whether this <code>Session</code> has permission to perform the specified actions
0469: * at the specified <code>absPath</code>. This method quietly returns if the access request is
0470: * permitted, or throws a suitable <code>java.security.AccessControlException</code> otherwise.
0471: * <p/>
0472: * The <code>actions</code> parameter is a comma separated list of action strings. The following
0473: * action strings are defined:
0474: * <ul>
0475: * <li>
0476: * <code>add_node</code>: If <code>checkPermission(path, "add_node")</code> returns quietly, then
0477: * this <code>Session</code> has permission to add a node at <code>path</code>, otherwise permission
0478: * is denied.
0479: * </li>
0480: * <li>
0481: * <code>set_property</code>: If <code>checkPermission(path, "set_property")</code> returns quietly,
0482: * then this <code>Session</code> has permission to set (add or change) a property at <code>path</code>,
0483: * otherwise permission is denied.
0484: * </li>
0485: * <li>
0486: * <code>remove</code>: If <code>checkPermission(path, "remove")</code> returns quietly, then this
0487: * <code>Session</code> has permission to remove an item at <code>path</code>, otherwise permission is denied.
0488: * </li>
0489: * <li>
0490: * <code>read</code>: If <code>checkPermission(path, "read")</code> returns quietly, then this
0491: * <code>Session</code> has permission to retrieve (and read the value of, in the case of a property)
0492: * an item at <code>path</code>, otherwise permission is denied.
0493: * </li>
0494: * </ul>
0495: * When more than one action is specified in the <code>actions</code> parameter, this method will only
0496: * return quietly if this <code>Session</code> has permission to perform <i>all</i> of the listed
0497: * actions at the specified path.
0498: * <p/>
0499: * The information returned through this method will only reflect access control policies
0500: * and not other restrictions that may exist. For example, even though <code>checkPermission</code>
0501: * may indicate that a particular <code>Session</code> may add a property at <code>/A/B/C</code>,
0502: * the node type of the node at <code>/A/B</code> may prevent the addition of a property called
0503: * <code>C</code>.
0504: *
0505: * @param absPath an absolute path.
0506: * @param actions a comma separated list of action strings.
0507: * @throws java.security.AccessControlException If permission is denied.
0508: * @throws RepositoryException if another error occurs.
0509: */
0510: public void checkPermission(String absPath, String actions)
0511: throws java.security.AccessControlException,
0512: RepositoryException;
0513:
0514: /**
0515: * Returns an <code>org.xml.sax.ContentHandler</code> which can be used to
0516: * push SAX events into the repository. If the incoming XML stream (in the
0517: * form of SAX events) does not appear to be a JCR <i>system view</i> XML
0518: * document then it is interpreted as a JCR <i>document view</i> XML
0519: * document.
0520: * <p/>
0521: * The incoming XML is deserialized into a subtree of items immediately
0522: * below the node at <code>parentAbsPath</code>.
0523: * <p/>
0524: * This method simply returns the <code>ContentHandler</code> without
0525: * altering the state of the session; the actual deserialization to the
0526: * session transient space is done through the methods of the
0527: * <code>ContentHandler</code>. Invalid XML data
0528: * will cause the <code>ContentHandler</code> to throw a
0529: * <code>SAXException</code>.
0530: * <p/>
0531: * As SAX events are fed into the <code>ContentHandler</code>, the tree of
0532: * new items is built in the transient storage of the session. In order to
0533: * persist the new content, <code>save</code> must be called. The advantage
0534: * of this through-the-session method is that (depending on which constraint
0535: * checks the implementation leaves until <code>save</code>) structures that
0536: * violate node type constraints can be imported, fixed and then saved. The
0537: * disadvantage is that a large import will result in a large cache of
0538: * pending nodes in the session. See
0539: * {@link Workspace#getImportContentHandler} for a version of this
0540: * method that does not go through the session.
0541: * <p/>
0542: * The flag <code>uuidBehavior</code> governs how the identifiers of incoming
0543: * (deserialized) nodes are handled. There are four options:
0544: * <ul>
0545: * <li>
0546: * {@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming identifiers
0547: * nodes are added in the same way that new node is added with
0548: * <code>Node.addNode</code>. That is, they are either assigned newly
0549: * created identifiers upon addition or upon <code>save</code> (depending on the
0550: * implementation). In either case, identifier collisions will not occur.
0551: * </li>
0552: * <li>
0553: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an
0554: * incoming node has the same identifier as a node already existing
0555: * in the workspace then the already existing node (and its subtree) is
0556: * removed from wherever it may be in the workspace before the incoming node
0557: * is added. Note that this can result in nodes "disappearing" from
0558: * locations in the workspace that are remote from the location to which the
0559: * incoming subtree is being written. Both the removal and the new addition
0560: * will be persisted on <code>save</code>.
0561: * </li>
0562: * <li>
0563: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}: If an
0564: * incoming node has the same identifier as a node already existing
0565: * in the workspace, then the already-existing node is replaced by the
0566: * incoming node in the same position as the existing node. Note that this
0567: * may result in the incoming subtree being disaggregated and "spread
0568: * around" to different locations in the workspace. In the most extreme case
0569: * this behavior may result in no node at all being added as child of
0570: * <code>parentAbsPath</code>. This will occur if the topmost element of the
0571: * incoming XML has the same identifier as an existing node elsewhere in the
0572: * workspace. The change will be persisted on <code>save</code>.
0573: * </li>
0574: * <li>
0575: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If an incoming
0576: * node has the same identifier as a node already existing in the
0577: * workspace then a <code>SAXException</code> is thrown by the
0578: * <code>ContentHandler</code> during deserialization.
0579: * </li>
0580: * </ul>
0581: * Unlike <code>Workspace.getImportContentHandler</code>, this method does not necessarily
0582: * enforce all node type constraints during deserialization. Those that
0583: * would be immediately enforced in a normal write method (<code>Node.addNode</code>,
0584: * <code>Node.setProperty</code> etc.) of this implementation cause the returned
0585: * <code>ContentHandler</code> to throw an immediate <code>SAXException</code> during deserialization.
0586: * All other constraints are checked on save, just as they are in normal
0587: * write operations. However, which node type constraints are enforced depends upon whether node type
0588: * information in the imported data is respected, and this is an implementation-specific issue.
0589: * <p/>
0590: * A <code>SAXException</code> will also be thrown by the returned
0591: * <code>ContentHandler</code> during deserialization if <code>uuidBehavior</code> is set to
0592: * <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code> and an incoming node has the same
0593: * identifier as the node at <code>parentAbsPath</code> or one of its ancestors.
0594: * <p/>
0595: * A <code>PathNotFoundException</code> is thrown either immediately or on <code>save</code>
0596: * if no node exists at <code>parentAbsPath</code>. Implementations may differ on when this
0597: * validation is performed
0598: * <p/>
0599: * A <code>ConstraintViolationException</code> is thrown either immediately or on <code>save</code>
0600: * if the new subtree cannot be added to the node at parentAbsPath due to node-type or other
0601: * implementation-specific constraints, and this can be determined before the first SAX event is sent.
0602: * Implementations may differ on when this validation is performed.
0603: * <p/>
0604: * A <code>VersionException</code> is thrown either immediately or on <code>save</code> if the node at
0605: * <code>parentAbsPath</code> is versionable and checked-in, or is non-versionable but
0606: * its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.
0607: * <p/>
0608: * A <code>LockException</code> is thrown either immediately or on <code>save</code>
0609: * if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.
0610: *
0611: * @param parentAbsPath the absolute path of a node under which (as child) the imported subtree will be
0612: * built.
0613: * @param uuidBehavior a four-value flag that governs how incoming identifiers are handled.
0614: * @return an org.xml.sax.ContentHandler whose methods may be called to feed SAX events
0615: * into the deserializer.
0616: * @throws PathNotFoundException if no node exists at <code>parentAbsPath</code> and this
0617: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0618: * @throws ConstraintViolationException if the new subtree cannot be added to the node at
0619: * <code>parentAbsPath</code> due to node-type or other implementation-specific constraints,
0620: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0621: * @throws VersionException if the node at <code>parentAbsPath</code> is versionable
0622: * and checked-in, or is non-versionable but its nearest versionable ancestor is checked-in and this
0623: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0624: * @throws LockException if a lock prevents the addition of the subtree and this
0625: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0626: * @throws RepositoryException if another error occurs.
0627: */
0628: public ContentHandler getImportContentHandler(String parentAbsPath,
0629: int uuidBehavior) throws PathNotFoundException,
0630: ConstraintViolationException, VersionException,
0631: LockException, RepositoryException;
0632:
0633: /**
0634: * Deserializes an XML document and adds the resulting item subtree as a
0635: * child of the node at <code>parentAbsPath</code>.
0636: * <p/>
0637: * If the incoming XML stream does not appear to be a JCR <i>system view</i>
0638: * XML document then it is interpreted as a <i>document view</i> XML
0639: * document.
0640: * <p/>
0641: * The passed <code>InputStream</code> is closed before this method returns
0642: * either normally or because of an exception.
0643: * <p/>
0644: * The tree of new items is built in the transient storage of the <code>Session</code>.
0645: * In order to persist the new content, <code>save</code> must be called.
0646: * The advantage of this through-the-session method is that (depending on
0647: * what constraint checks the implementation leaves until <code>save</code>)
0648: * structures that violate node type constraints can be imported, fixed and
0649: * then saved. The disadvantage is that a large import will result in a
0650: * large cache of pending nodes in the session. See {@link
0651: * Workspace#importXML} for a version of this method that does not go
0652: * through the <code>Session</code>.
0653: * <p/>
0654: * The flag <code>uuidBehavior</code> governs how the identifiers of incoming
0655: * (deserialized) nodes are handled. There are four options:
0656: * <ul>
0657: * <li>
0658: * {@link ImportUUIDBehavior#IMPORT_UUID_CREATE_NEW}: Incoming nodes
0659: * are added in the same way that new node is added with
0660: * <code>Node.addNode</code>. That is, they are either assigned newly
0661: * created identifiers upon addition or upon <code>save</code> (depending on
0662: * the implementation, see <i>4.9.1.1 When Identifiers are Assigned</i> in
0663: * the specification). In either case, identifier collisions will not occur.
0664: * </li>
0665: * <li>
0666: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REMOVE_EXISTING}: If an incoming
0667: * node has the same identifier as a node already existing in
0668: * the workspace then the already existing node (and its subtree) is removed
0669: * from wherever it may be in the workspace before the incoming node is
0670: * added. Note that this can result in nodes "disappearing" from locations
0671: * in the workspace that are remote from the location to which the incoming
0672: * subtree is being written. Both the removal and the new addition will be
0673: * persisted on <code>save</code>.
0674: * </li>
0675: * <li>
0676: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_REPLACE_EXISTING}: If an incoming
0677: * node has the same identifier as a node already existing in the
0678: * workspace, then the already-existing node is replaced by the incoming
0679: * node in the same position as the existing node. Note that this may result
0680: * in the incoming subtree being disaggregated and "spread around" to
0681: * different locations in the workspace. In the most extreme case this
0682: * behavior may result in no node at all being added as child of
0683: * <code>parentAbsPath</code>. This will occur if the topmost element of the
0684: * incoming XML has the same identifier as an existing node elsewhere in the
0685: * workspace. The change will only be persisted on <code>save</code>.
0686: * </li>
0687: * <li>
0688: * {@link ImportUUIDBehavior#IMPORT_UUID_COLLISION_THROW}: If an incoming
0689: * node has the same identifier as a node already existing in the
0690: * workspace then an <code>ItemExistsException</code> is thrown.
0691: * </li>
0692: * </ul>
0693: * Unlike {@link Workspace#importXML}, this method does not necessarily
0694: * enforce all node type constraints during deserialization. Those that
0695: * would be immediately enforced in a normal write method
0696: * (<code>Node.addNode</code>, <code>Node.setProperty</code> etc.) of this
0697: * implementation cause an immediate
0698: * <code>ConstraintViolationException</code> during deserialization. All
0699: * other constraints are checked on <code>save</code>, just as they are in
0700: * normal write operations. However, which node type constraints are enforced
0701: * depends upon whether node type information in the imported data is respected,
0702: * and this is an implementation-specific issue ((see
0703: * <i>5.4.3 Respecting Property Semantics</i> in the specification).
0704: * <p/>
0705: * A <code>ConstraintViolationException</code> will also be thrown
0706: * immediately if <code>uuidBehavior</code> is set to
0707: * <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code> and an incoming node
0708: * has the same identifier as the node at <code>parentAbsPath</code> or one of its
0709: * ancestors.
0710: * <p/>
0711: * A <code>PathNotFoundException</code> is thrown either immediately or on <code>save</code>
0712: * if no node exists at <code>parentAbsPath</code>. Implementations may differ on when this
0713: * validation is performed
0714: * <p/>
0715: * A <code>ConstraintViolationException</code> is thrown either immediately or on <code>save</code>
0716: * if the new subtree cannot be added to the node at parentAbsPath due to node-type or other
0717: * implementation-specific constraints, and this can be determined before the first SAX event is sent.
0718: * Implementations may differ on when this validation is performed.
0719: * <p/>
0720: * A <code>VersionException</code> is thrown either immediately or on <code>save</code> if the node at
0721: * <code>parentAbsPath</code> is versionable and checked-in, or is non-versionable but
0722: * its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.
0723: * <p/>
0724: * A <code>LockException</code> is thrown either immediately or on <code>save</code>
0725: * if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.
0726: *
0727: * @param parentAbsPath the absolute path of the node below which the deserialized subtree is added.
0728: * @param in The <code>Inputstream</code> from which the XML to be deserilaized is read.
0729: * @param uuidBehavior a four-value flag that governs how incoming identifiers are handled.
0730: *
0731: * @throws java.io.IOException if an error during an I/O operation occurs.
0732: * @throws PathNotFoundException if no node exists at <code>parentAbsPath</code> and this
0733: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0734: * @throws ItemExistsException if deserialization would overwrite an existing item and this
0735: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0736: * @throws ConstraintViolationException if a node type or other implementation-specific
0737: * constraint is violated that would be checked on a normal write method or if
0738: * <code>uuidBehavior</code> is set to <code>IMPORT_UUID_COLLISION_REMOVE_EXISTING</code>
0739: * and an incoming node has the same UUID as the node at <code>parentAbsPath</code> or one
0740: * of its ancestors.
0741: * @throws VersionException if the node at <code>parentAbsPath</code> is versionable
0742: * and checked-in, or its nearest versionable ancestor is checked-in and this
0743: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0744: * @throws InvalidSerializedDataException if incoming stream is not a valid XML document.
0745: * @throws LockException if a lock prevents the addition of the subtree and this
0746: * implementation performs this validation immediately instead of waiting until <code>save</code>..
0747: * @throws RepositoryException is another error occurs.
0748: */
0749: public void importXML(String parentAbsPath, InputStream in,
0750: int uuidBehavior) throws IOException,
0751: PathNotFoundException, ItemExistsException,
0752: ConstraintViolationException, VersionException,
0753: InvalidSerializedDataException, LockException,
0754: RepositoryException;
0755:
0756: /**
0757: * Serializes the node (and if <code>noRecurse</code> is <code>false</code>,
0758: * the whole subtree) at <code>absPath</code> into a series of SAX events by
0759: * calling the methods of the supplied <code>org.xml.sax.ContentHandler</code>.
0760: * The resulting XML is in the system view form. Note that <code>absPath</code>
0761: * must be the path of a node, not a property.
0762: * <p>
0763: * If <code>skipBinary</code> is true then any properties of <code>PropertyType.BINARY</code> will be
0764: * serialized as if they are empty. That is, the existence of the property
0765: * will be serialized, but its content will not appear in the serialized
0766: * output (the <code><sv:value></code> element will have no content). Note that in the
0767: * case of multi-value <code>BINARY</code> properties, the number of values in the
0768: * property will be reflected in the serialized output, though they will all
0769: * be empty. If <code>skipBinary</code> is false then the actual value(s) of each <code>BINARY</code>
0770: * property is recorded using Base64 encoding.
0771: * <p>
0772: * If <code>noRecurse</code> is true then only the node at
0773: * <code>absPath</code> and its properties, but not its child nodes, are
0774: * serialized. If <code>noRecurse</code> is <code>false</code> then the entire subtree
0775: * rooted at <code>absPath</code> is serialized.
0776: * <p>
0777: * If the user lacks read access to some subsection of the specified tree,
0778: * that section simply does not get serialized, since, from the user's
0779: * point of view, it is not there.
0780: * <p>
0781: * The serialized output will reflect the state of the current workspace as
0782: * modified by the state of this <code>Session</code>. This means that
0783: * pending changes (regardless of whether they are valid according to
0784: * node type constraints) and all namespace mappings in the namespace registry,
0785: * as modified by the current session-mappings, are reflected in the output.
0786: * <p>
0787: * The output XML will be encoded in UTF-8.
0788: * <p>
0789: * A <code>PathNotFoundException</code> is thrown if no node exists at <code>absPath</code>.
0790: * <p>
0791: * A <code>SAXException</code> is thrown if an error occurs while feeding events to the
0792: * <code>ContentHandler</code>.
0793: *
0794: * @param absPath The path of the root of the subtree to be serialized.
0795: * This must be the path to a node, not a property
0796: * @param contentHandler The <code>org.xml.sax.ContentHandler</code> to
0797: * which the SAX events representing the XML serialization of the subtree
0798: * will be output.
0799: * @param skipBinary A <code>boolean</code> governing whether binary
0800: * properties are to be serialized.
0801: * @param noRecurse A <code>boolean</code> governing whether the subtree at
0802: * absPath is to be recursed.
0803: *
0804: * @throws PathNotFoundException if no node exists at <code>absPath</code>.
0805: * @throws org.xml.sax.SAXException if an error occurs while feeding events to the
0806: * <code>org.xml.sax.ContentHandler</code>.
0807: * @throws RepositoryException if another error occurs.
0808: */
0809: public void exportSystemView(String absPath,
0810: ContentHandler contentHandler, boolean skipBinary,
0811: boolean noRecurse) throws PathNotFoundException,
0812: SAXException, RepositoryException;
0813:
0814: /**
0815: * Serializes the node (and if <code>noRecurse</code> is <code>false</code>,
0816: * the whole subtree) at <code>absPath</code> as an XML stream and outputs it to
0817: * the supplied <code>OutputStream</code>. The resulting XML is in the system
0818: * view form. Note that <code>absPath</code> must be the path of a node, not a property.
0819: * <p>
0820: * If <code>skipBinary</code> is true then any properties of <code>PropertyType.BINARY</code> will be
0821: * serialized as if they are empty. That is, the existence of the property
0822: * will be serialized, but its content will not appear in the serialized
0823: * output (the <code><sv:value></code> element will have no content). Note that in the
0824: * case of multi-value <code>BINARY</code> properties, the number of values in the
0825: * property will be reflected in the serialized output, though they will all
0826: * be empty. If <code>skipBinary</code> is false then the actual value(s) of each <code>BINARY</code>
0827: * property is recorded using Base64 encoding.
0828: * <p>
0829: * If <code>noRecurse</code> is true then only the node at
0830: * <code>absPath</code> and its properties, but not its child nodes, are
0831: * serialized. If <code>noRecurse</code> is <code>false</code> then the entire subtree
0832: * rooted at <code>absPath</code> is serialized.
0833: * <p>
0834: * If the user lacks read access to some subsection of the specified tree,
0835: * that section simply does not get serialized, since, from the user's
0836: * point of view, it is not there.
0837: * <p>
0838: * The serialized output will reflect the state of the current workspace as
0839: * modified by the state of this <code>Session</code>. This means that
0840: * pending changes (regardless of whether they are valid according to
0841: * node type constraints) and all namespace mappings in the namespace
0842: * registry, as modified by the current session-mappings, are reflected in the output.
0843: * <p>
0844: * The output XML will be encoded in UTF-8.
0845: * <p>
0846: * It is the responsibility of the caller to close the passed <code>OutputStream</code>.
0847: * <p/>
0848: * An <code>IOException</code> is thrown if an I/O error occurs.
0849: * <p/>
0850: * A <code>PathNotFoundException</code> is thrown if no node exists at <code>absPath</code>.
0851: *
0852: * @param absPath The path of the root of the subtree to be serialized.
0853: * This must be the path to a node, not a property
0854: * @param out The <code>OutputStream</code> to which the XML
0855: * serialization of the subtree will be output.
0856: * @param skipBinary A <code>boolean</code> governing whether binary
0857: * properties are to be serialized.
0858: * @param noRecurse A <code>boolean</code> governing whether the subtree at
0859: * absPath is to be recursed.
0860: *
0861: * @throws PathNotFoundException if no node exists at <code>absPath</code>.
0862: * @throws IOException if an error during an I/O operation occurs.
0863: * @throws RepositoryException if another error occurs.
0864: */
0865: public void exportSystemView(String absPath, OutputStream out,
0866: boolean skipBinary, boolean noRecurse) throws IOException,
0867: PathNotFoundException, RepositoryException;
0868:
0869: /**
0870: * Serializes the node (and if <code>noRecurse</code> is <code>false</code>,
0871: * the whole subtree) at <code>absPath</code> into a series of SAX events by
0872: * calling the methods of the supplied <code>org.xml.sax.ContentHandler</code>.
0873: * The resulting XML is in the document view form. Note that <code>absPath</code>
0874: * must be the path of a node, not a property.
0875: * <p>
0876: * If <code>skipBinary</code> is true then any properties of <code>PropertyType.BINARY</code> will be
0877: * serialized as if they are empty. That is, the existence of the property
0878: * will be serialized, but its content will not appear in the serialized
0879: * output (the value of the attribute will be empty). If <code>skipBinary</code> is false
0880: * then the actual value(s) of each <code>BINARY</code> property is recorded using Base64
0881: * encoding.
0882: * <p>
0883: * If <code>noRecurse</code> is true then only the node at
0884: * <code>absPath</code> and its properties, but not its child nodes, are
0885: * serialized. If <code>noRecurse</code> is <code>false</code> then the entire subtree
0886: * rooted at <code>absPath</code> is serialized.
0887: * <p>
0888: * If the user lacks read access to some subsection of the specified tree,
0889: * that section simply does not get serialized, since, from the user's
0890: * point of view, it is not there.
0891: * <p>
0892: * The serialized output will reflect the state of the current workspace as
0893: * modified by the state of this <code>Session</code>. This means that
0894: * pending changes (regardless of whether they are valid according to
0895: * node type constraints) and all namespace mappings in the namespace registry,
0896: * as modified by the current session-mappings, are reflected in the output.
0897: * <p>
0898: * The output XML will be encoded in UTF-8.
0899: * <p>
0900: * A <code>PathNotFoundException</code> is thrown if no node exists at <code>absPath</code>.
0901: * <p>
0902: * A <code>SAXException</code> is thrown if an error occurs while feeding events to the
0903: * <code>ContentHandler</code>.
0904: *
0905: * @param absPath The path of the root of the subtree to be serialized.
0906: * This must be the path to a node, not a property
0907: * @param contentHandler The <code>org.xml.sax.ContentHandler</code> to
0908: * which the SAX events representing the XML serialization of the subtree
0909: * will be output.
0910: * @param skipBinary A <code>boolean</code> governing whether binary
0911: * properties are to be serialized.
0912: * @param noRecurse A <code>boolean</code> governing whether the subtree at
0913: * absPath is to be recursed.
0914: *
0915: * @throws PathNotFoundException if no node exists at <code>absPath</code>.
0916: * @throws org.xml.sax.SAXException if an error occurs while feeding events to the
0917: * <code>org.xml.sax.ContentHandler</code>.
0918: * @throws RepositoryException if another error occurs.
0919: */
0920: public void exportDocumentView(String absPath,
0921: ContentHandler contentHandler, boolean skipBinary,
0922: boolean noRecurse) throws PathNotFoundException,
0923: SAXException, RepositoryException;
0924:
0925: /**
0926: * Serializes the node (and if <code>noRecurse</code> is <code>false</code>,
0927: * the whole subtree) at <code>absPath</code> as an XML stream and outputs it to
0928: * the supplied <code>OutputStream</code>. The resulting XML is in the document
0929: * view form. Note that <code>absPath</code> must be the path of a node, not a property.
0930: * <p>
0931: * If <code>skipBinary</code> is true then any properties of <code>PropertyType.BINARY</code> will be
0932: * serialized as if they are empty. That is, the existence of the property
0933: * will be serialized, but its content will not appear in the serialized
0934: * output (the value of the attribute will be empty). If <code>skipBinary</code> is false
0935: * then the actual value(s) of each <code>BINARY</code> property is recorded using Base64
0936: * encoding.
0937: * <p>
0938: * If <code>noRecurse</code> is true then only the node at
0939: * <code>absPath</code> and its properties, but not its child nodes, are
0940: * serialized. If <code>noRecurse</code> is <code>false</code> then the entire subtree
0941: * rooted at <code>absPath</code> is serialized.
0942: * <p>
0943: * If the user lacks read access to some subsection of the specified tree,
0944: * that section simply does not get serialized, since, from the user's
0945: * point of view, it is not there.
0946: * <p>
0947: * The serialized output will reflect the state of the current workspace as
0948: * modified by the state of this <code>Session</code>. This means that
0949: * pending changes (regardless of whether they are valid according to
0950: * node type constraints) and all namespace mappings in the namespace registry,
0951: * as modified by the current session-mappings, are reflected in the output.
0952: * <p>
0953: * The output XML will be encoded in UTF-8.
0954: * <p/>
0955: * It is the responsibility of the caller to close the passed <code>OutputStream</code>.
0956: * <p/>
0957: * An IOException is thrown if an I/O error occurs.
0958: * <p>
0959: * A <code>PathNotFoundException</code> is thrown if no node exists at <code>absPath</code>.
0960: *
0961: * @param absPath The path of the root of the subtree to be serialized.
0962: * This must be the path to a node, not a property
0963: * @param out The <code>OutputStream</code> to which the XML
0964: * serialization of the subtree will be output.
0965: * @param skipBinary A <code>boolean</code> governing whether binary
0966: * properties are to be serialized.
0967: * @param noRecurse A <code>boolean</code> governing whether the subtree at
0968: * absPath is to be recursed.
0969: *
0970: * @throws PathNotFoundException if no node exists at <code>absPath</code>.
0971: * @throws IOException if an error during an I/O operation occurs.
0972: * @throws RepositoryException if another error occurs.
0973: */
0974: public void exportDocumentView(String absPath, OutputStream out,
0975: boolean skipBinary, boolean noRecurse) throws IOException,
0976: PathNotFoundException, RepositoryException;
0977:
0978: /**
0979: * Within the scope of this <code>Session</code>, this method maps
0980: * <code>uri</code> to <code>prefix</code>. The remapping only affects
0981: * operations done through this <code>Session</code>. To clear all
0982: * remappings, the client must acquire a new <code>Session</code>.
0983: * <p/>
0984: * All local mappings already present in the <code>Session</code> that
0985: * include either the specified <code>prefix</code> or the specified
0986: * <code>uri</code> are removed and the new mapping is added.
0987: * <p/>
0988: * A <code>NamespaceException</code> will be thrown if an attempt is made to
0989: * map a namespace URI to a prefix beginning with the characters
0990: * "<code>xml</code>" (in any combination of case).
0991: * <p/>
0992: * A <code>NamespaceException</code> will be thrown if an attempt is made to
0993: * map either the empty prefix or the empty namespace (i.e., if either
0994: * <code>prefix</code> or <code>uri</code> are the empty string).
0995: *
0996: * @param prefix a string
0997: * @param uri a string
0998: * @throws NamespaceException if the local mapping cannot be done.
0999: * @throws RepositoryException if another error occurs.
1000: */
1001: public void setNamespacePrefix(String prefix, String uri)
1002: throws NamespaceException, RepositoryException;
1003:
1004: /**
1005: * Returns all prefixes currently mapped to URIs in this <code>Session</code>.
1006: *
1007: * @return a string array
1008: * @throws RepositoryException if an error occurs
1009: */
1010: public String[] getNamespacePrefixes() throws RepositoryException;
1011:
1012: /**
1013: * Returns the URI to which the given <code>prefix</code> is mapped
1014: * as currently set in this <code>Session</code>.
1015: *
1016: * @param prefix a string
1017: * @return a string
1018: * @throws NamespaceException if the specified <code>prefix</code> is unknown.
1019: * @throws RepositoryException if another error occurs
1020: */
1021: public String getNamespaceURI(String prefix)
1022: throws NamespaceException, RepositoryException;
1023:
1024: /**
1025: * Returns the prefix to which the given <code>uri</code> is mapped as currently
1026: * set in this <code>Session</code>.
1027: *
1028: * @param uri a string
1029: * @return a string
1030: * @throws NamespaceException if the specified <code>uri</code> is unknown.
1031: * @throws RepositoryException if another error occurs
1032: */
1033: public String getNamespacePrefix(String uri)
1034: throws NamespaceException, RepositoryException;
1035:
1036: /**
1037: * Releases all resources associated with this <code>Session</code>. This method should be called when a
1038: * <code>Session</code> is no longer needed.
1039: */
1040: public void logout();
1041:
1042: /**
1043: * Returns <code>true</code> if this <code>Session</code> object is usable
1044: * by the client. Otherwise, returns <code>false</code>. A usable
1045: * <code>Session</code> is one that is neither logged-out, timed-out nor in
1046: * any other way disconnected from the repository.
1047: *
1048: * @return <code>true</code> if this <code>Session</code> is usable,
1049: * <code>false</code> otherwise.
1050: */
1051: public boolean isLive();
1052:
1053: /**
1054: * Adds the specified lock token to this <code>Session</code>. Holding a
1055: * lock token makes this <code>Session</code> the owner of the lock
1056: * specified by that particular lock token.
1057: * <p/>
1058: * A <code>LockException</code> is thrown if the specified lock token is
1059: * already held by another <code>Session</code> and the implementation does
1060: * not support simultaneous ownership of open-scoped locks..
1061: * <p/>
1062: * A <code>RepositoryException</code> is thrown if another error occurs.
1063: *
1064: * @param lt a lock token (a string)
1065: * @throws LockException if the specified lock token is already held by
1066: * another <code>Session</code> and the implementation
1067: * does not support simultaneous ownership of open-scoped
1068: * locks.
1069: * @throws RepositoryException if another error occurs.
1070: */
1071: public void addLockToken(String lt) throws LockException,
1072: RepositoryException;
1073:
1074: /**
1075: * Returns an array containing all lock tokens currently held by this
1076: * <code>Session</code>. Note that any such tokens will represent open-scoped
1077: * locks, since session-scoped locks do not have tokens.
1078: *
1079: * @return an array of lock tokens (strings)
1080: */
1081: public String[] getLockTokens();
1082:
1083: /**
1084: * Returns all locks owned by this session.
1085: *
1086: * @return an array of <code>Lock</code>s
1087: * @since JCR 2.0
1088: */
1089: public Lock[] getLocks();
1090:
1091: /**
1092: * Removes the specified lock token from this <code>Session</code>.
1093: * <p/>
1094: * A <code>LockException</code> is thrown if this <code>Session</code> does
1095: * not hold the specified lock token.
1096: * <p/>
1097: * A <code>RepositoryException</code> is thrown if another error occurs.
1098: *
1099: * @param lt a lock token (a string)
1100: * @throws LockException if this <code>Session</code> does not hold the
1101: * specified lock token.
1102: * @throws RepositoryException if another error occurs.
1103: */
1104: public void removeLockToken(String lt) throws LockException,
1105: RepositoryException;
1106:
1107: /**
1108: * This method is called by the client to set the current activity on the
1109: * session. Changing the current activity is done by calling <code>setActivity</code>
1110: * again. Cancelling the current activity (so that the session has no
1111: * current activity) is done by calling <code>setActivity(null)</code>.
1112: * The activity <code>Node</code> is returned.
1113: * <p/>
1114: * An <code>UnsupportedRepositoryOperationException</code> is thrown if the
1115: * repsoitory does not support activities or if <code>activity</code> is not
1116: * a <code>nt:activity</code> node.
1117: *
1118: * @param activity an activity node
1119: * @return the activity node
1120: * @throws UnsupportedRepositoryOperationException if the repository does
1121: * not support activities or if <code>activity</code> is not a
1122: * <code>nt:activity</code> node.
1123: * @throws RepositoryException if another error occurs.
1124: * @since JCR 2.0
1125: */
1126: public Node setActivity(Node activity)
1127: throws UnsupportedRepositoryOperationException,
1128: RepositoryException;
1129:
1130: /**
1131: * Returns the access control manager for this <code>Session</code>.
1132: * <p/>
1133: * An <code>UnsupportedRepositoryOperationException</code> is thrown if
1134: * access control discovery is not supported.
1135: * <p/>
1136: * A <code>RepositoryException</code> is thrown if another error occurs.
1137: *
1138: * @return the access control manager for this <code>Session</code>
1139: * @throws UnsupportedRepositoryOperationException if access control discovery
1140: * is not supported.
1141: * @throws RepositoryException if another error occurs.
1142: * @since JCR 2.0
1143: */
1144: public AccessControlManager getAccessControlManager()
1145: throws UnsupportedRepositoryOperationException,
1146: RepositoryException;
1147: }
|