javax.jcr.version.VersionManager Maven / Gradle / Ivy
Show all versions of aem-sdk-api Show documentation
/*
* Copyright 2008 Day Management AG, Switzerland. All rights reserved.
*/
package javax.jcr.version;
import javax.jcr.RepositoryException;
import javax.jcr.UnsupportedRepositoryOperationException;
import javax.jcr.ItemExistsException;
import javax.jcr.InvalidItemStateException;
import javax.jcr.PathNotFoundException;
import javax.jcr.MergeException;
import javax.jcr.NoSuchWorkspaceException;
import javax.jcr.AccessDeniedException;
import javax.jcr.NodeIterator;
import javax.jcr.Node;
import javax.jcr.nodetype.ConstraintViolationException;
import javax.jcr.lock.LockException;
/**
* The VersionManager object is accessed via {@link
* javax.jcr.Workspace#getVersionManager()}. It provides methods for:
* - Version graph functionality (version history, base version, successors
* predecessors)
- Basic version operations (checkin, checkout,
* checkpoint)
- Restore feature
- Label feature
- Merge
* feature
- Configuration feature
- Activity feature
*
* @since JCR 2.0
*/
public interface VersionManager {
/**
* Creates for the versionable node at absPath a new version
* with a system generated version name and returns that version (which will
* be the new base version of this node). Sets the jcr:checkedOut
* property to false thus putting the node into the checked-in state.
* This means that the node and its connected non-versionable
* subgraph become read-only. A node's connected non-versionable
* subgraph is the set of non-versionable descendant nodes reachable from
* that node through child links without encountering any versionable nodes.
* In other words, the read-only status flows down from the checked-in node
* along every child link until either a versionable node is encountered or
* an item with no children is encountered. In a system that supports only
* simple versioning the connected non-versionable subgraph will be
* equivalent to the whole subgraph, since simple-versionable nodes cannot
* have simple-versionable descendants.
*
* Read-only status means that an item cannot be altered by the client using
* standard API methods (addNode, setProperty,
* etc.). The only exceptions to this rule are the {@link #restore} (all
* signatures), {@link #restoreByLabel}, {@link #restore}, {@link #merge}
* and {@link Node#update} operations; these do not respect read-only status
* due to check-in. Note that remove of a read-only node is
* possible, as long as its parent is not read-only (since removal is an
* alteration of the parent node).
*
* If the node is already checked-in, this method has no effect but returns
* the current base version of the node at absPath.
*
* If a repository supports configurations and baselines and the node at
* absPath is a configuration proxy node in configuration storage
* then checkin of that node has the additional side effect of storing in the
* created version, the state of the configuration that this proxy node represents.
* In particular, the current bs version of each versionable node within the
* configuration is recorded in some implementation-specific way within the
* version created by the checkin. For checkin to succeed on a configuration
* proxy node, every versionable node within the configuration in question must
* have been checked-in at least once (i.e., each must have a current base version
* which is not the root version of its version history).
*
* If checkin succeeds, the change to the
* jcr:isCheckedOut property is dispatched immediately;
* there is no need to call save.
*
* @param absPath an absolute path.
* @return the created version.
* @throws VersionException if jcr:predecessors does not
* contain at least one value or if a child item of the node at
* absPath has an OnParentVersion status of
* ABORT. This includes the case where an unresolved merge
* failure exists on the node, as indicated by the presence of a
* jcr:mergeFailed property.
* @throws UnsupportedRepositoryOperationException
* If the node at
* absPath node is not versionable.
* @throws InvalidItemStateException If unsaved changes exist on the node at
* absPath or the node at absPath is
* a configuration proxy node and the configuration it represents
* includes a versionabe node that has never been checked-in.
* @throws LockException if a lock prevents the operation.
* @throws RepositoryException If another error occurs.
*/
public Version checkin(String absPath) throws VersionException, UnsupportedRepositoryOperationException, InvalidItemStateException, LockException, RepositoryException;
/**
* Sets the versionable node at absPath to checked-out status
* by setting its jcr:isCheckedOut property to
* true. Under full versioning it also sets the
* jcr:predecessors property to be a reference to the current
* base version (the same value as held in jcr:baseVersion).
*
This method puts the node into the checked-out state, making
* it and its connected non-versionable subgraph no longer read-only (see
* {@link #checkin(String)} for an explanation of the term "connected
* non-versionable subgraph". Under simple versioning this will simply be
* the whole subgraph).
If successful, these changes are dispatched
* immediately; there is no need to call save.
If the node
* at absPath is already checked-out, this method has no
* effect.
*
* @param absPath an absolute path.
* @throws UnsupportedRepositoryOperationException
* If the node at
* absPath is not versionable.
* @throws LockException if a lock prevents the checkout.
* @throws RepositoryException If another error occurs.
*/
public void checkout(String absPath) throws UnsupportedRepositoryOperationException, LockException, RepositoryException;
/**
* Performs a checkin() followed by a checkout()
* on the versionable node at absPath.
*
* If the node is already checked-in, this method is equivalent to
* checkout().
*
* @param absPath an absolute path.
* @return the created version.
* @throws VersionException if a child item of the node at
* absPath has an OnParentVersion of
* ABORT. This includes the case where an unresolved merge
* failure exists on the node, as indicated by the presence of the
* jcr:mergeFailed.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws InvalidItemStateException if there are unsaved changes pending on
* the node at absPath.
* @throws LockException if a lock prevents the operation.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public Version checkpoint(String absPath) throws VersionException, UnsupportedRepositoryOperationException, InvalidItemStateException, LockException, RepositoryException;
/**
* Returns true if the node at absPath is either
*
- versionable (full or simple) and currently checked-out,
* - non-versionable and its nearest versionable ancestor is checked-out
* or
- non-versionable and it has no versionable ancestor.
*
*
* Returns false if the node at absPath is either
*
- versionable (full or simple) and currently checked-in or
* - non-versionable and its nearest versionable ancestor is
* checked-in.
*
* @param absPath an absolute path.
* @return a boolean
* @throws RepositoryException If another error occurs.
*/
public boolean isCheckedOut(String absPath) throws RepositoryException;
/**
* Returns the VersionHistory object of the node at
* absPath. This object provides access to the
* nt:versionHistory node holding the node's versions.
*
* @param absPath an absolute path.
* @return a VersionHistory object
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws RepositoryException If another error occurs.
*/
public VersionHistory getVersionHistory(String absPath) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns the current base version of the versionable node at
* absPath.
*
* @param absPath an absolute path.
* @return a Version object.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws RepositoryException If another error occurs.
*/
public Version getBaseVersion(String absPath) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Restores a set of versions at once. Used in cases where a "chicken and
* egg" problem of mutually referring REFERENCE properties
* would prevent the restore in any serial order.
*
* If the restore succeeds the changes made are
* dispatched immediately; there is no need to call save.
*
* The following restrictions apply to the set of versions specified:
*
* If S is the set of versions being restored simultaneously,
*
- For every version
V in S that
* corresponds to a missing node, there must also be a parent of V in
* S. S must contain at least one version that
* corresponds to an existing node in the workspace.- No
*
V in S can be a root version
* (jcr:rootVersion).
*
* If any of these restrictions does not hold, the restore will fail because
* the system will be unable to determine the path locations to which one or
* more versions are to be restored. In this case a VersionException
* is thrown.
*
* The versionable nodes in the current workspace that correspond to the
* versions being restored define a set of (one or more) subgraphs. An
* identifier collision occurs when the current workspace contains a node
* outside these subgraphs that has the same identifier as one of the
* nodes that would be introduced by the restore operation
* into one of these subgraphs. The result in such a case is governed
* by the removeExisting flag. If removeExisting
* is true then the incoming node takes precedence, and the
* existing node (and its subgraph) is removed. If removeExisting
* is false then a ItemExistsException is thrown
* and no changes are made. Note that this applies not only to cases where
* the restored node itself conflicts with an existing node but also to
* cases where a conflict occurs with any node that would be introduced into
* the workspace by the restore operation. In particular, conflicts
* involving subnodes of the restored node that have
* OnParentVersion settings of COPY or
* VERSION are also governed by the removeExisting
* flag.
*
* @param versions The set of versions to be restored.
* @param removeExisting governs what happens on identifier collision.
* @throws ItemExistsException if removeExisting is
* false and an identifier collision occurs with a node being
* restored.
* @throws UnsupportedRepositoryOperationException
* if one or more of the
* nodes to be restored is not versionable.
* @throws VersionException if the set of versions to be restored is such
* that the original path location of one or more of the versions cannot be
* determined or if the restore would change the state of a
* existing versionable node that is currently checked-in or if a root
* version (jcr:rootVersion) is among those being restored.
* @throws LockException if a lock prevents the restore.
* @throws InvalidItemStateException if this Session has
* pending unsaved changes.
* @throws RepositoryException if another error occurs.
*/
public void restore(Version[] versions, boolean removeExisting) throws ItemExistsException, UnsupportedRepositoryOperationException, VersionException, LockException, InvalidItemStateException, RepositoryException;
/**
* Restores the node at absPath to the state defined by the
* version with the specified versionName.
*
* If the node at absPath is not versionable, an
* UnsupportedRepositoryOperationException is thrown.
*
* If successful, the change is dispatched immediately; there is no need
* to call save. This method will work regardless of whether
* the node at absPath is checked-in or not.
*
* An identifier collision occurs when a node exists outside the subgraph
* rooted at this node with the same identifier as a node that would be
* introduced by the restore operation into the subgraph at
* this node. The result in such a case is governed by the
* removeExisting flag. If removeExisting is
* true, then the incoming node takes precedence, and the
* existing node (and its subgraph) is removed (if possible; otherwise a
* RepositoryException is thrown). If removeExisting
* is false, then a ItemExistsException is thrown
* and no changes are made. Note that this applies not only to cases where
* the restored node itself conflicts with an existing node but also to
* cases where a conflict occurs with any node that would be introduced into
* the workspace by the restore operation. In particular, conflicts
* involving subnodes of the restored node that have
* OnParentVersion settings of COPY or
* VERSION are also governed by the removeExisting
* flag.
*
* @param absPath an absolute path.
* @param versionName a Version object
* @param removeExisting a boolean flag that governs what happens in case of
* an identifier collision.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws VersionException if the specified version is not
* part of this node's version history or if an attempt is made to restore
* the root version (jcr:rootVersion) or if no node exists
* at absPath.
* @throws ItemExistsException if removeExisting is
* false and an identifier collision occurs.
* @throws LockException if a lock prevents the restore.
* @throws InvalidItemStateException if this Session (not
* necessarily the Node at absPath) has pending
* unsaved changes.
* @throws RepositoryException If another error occurs.
*/
public void restore(String absPath, String versionName, boolean removeExisting) throws VersionException, ItemExistsException, UnsupportedRepositoryOperationException, LockException, InvalidItemStateException, RepositoryException;
/**
* Restores the node in the current workspace that is the versionable node of the
* specified version to the state reflected in that version.
*
* If successful, the change is dispatched immediately; there is no need to call save.
* This method ignores checked-in status.
*
* An identifier collision occurs when a node exists outside the subgraph
* rooted at this node with the same identifier as a node that would be
* introduced by the restore operation into the subgraph at
* this node. The result in such a case is governed by the
* removeExisting flag. If removeExisting is
* true, then the incoming node takes precedence, and the
* existing node (and its subgraph) is removed (if possible; otherwise a
* RepositoryException is thrown). If removeExisting
* is false, then a ItemExistsException is thrown
* and no changes are made. Note that this applies not only to cases where
* the restored node itself conflicts with an existing node but also to
* cases where a conflict occurs with any node that would be introduced into
* the workspace by the restore operation. In particular, conflicts
* involving subnodes of the restored node that have
* OnParentVersion settings of COPY or
* VERSION are also governed by the removeExisting
* flag.
*
* @param version a Version object
* @param removeExisting a boolean flag that governs what happens in case of
* an identifier collision.
* @throws UnsupportedRepositoryOperationException
* if versioning is not
* supported.
* @throws VersionException if the specified version does not
* have a corresponding node in the workspace this
* VersionManager has been created for or if an attempt is made to restore
* the root version (jcr:rootVersion).
* @throws ItemExistsException if removeExisting is
* false and an identifier collision occurs.
* @throws InvalidItemStateException if this Session (not
* necessarily the Node at absPath) has pending
* unsaved changes.
* @throws LockException if a lock prevents the restore.
* @throws RepositoryException if another error occurs.
*/
public void restore(Version version, boolean removeExisting) throws VersionException, ItemExistsException, InvalidItemStateException, UnsupportedRepositoryOperationException, LockException, RepositoryException;
/**
* Restores the specified version to absPath.
*
* There must be no existing node at absPath. If one exists,
* a VersionException is thrown.
*
* There must be a parent node to the location at
* absPath, otherwise a PathNotFoundException
* is thrown.
*
* An identifier collision occurs when a node exists outside the subgraph
* rooted at absPath with the same identifier as a node
* that would be introduced by the restore operation into
* the subgraph at absPath. The result in such a case is
* governed by the removeExisting flag. If
* removeExisting is true, then the incoming node
* takes precedence, and the existing node (and its subgraph) is removed (if
* possible; otherwise a RepositoryException is thrown). If
* removeExisting is false, then a
* ItemExistsException is thrown and no changes are made. Note
* that this applies not only to cases where the restored node itself
* conflicts with an existing node but also to cases where a conflict occurs
* with any node that would be introduced into the workspace by the restore
* operation. In particular, conflicts involving subnodes of the restored
* node that have OnParentVersion settings of COPY
* or VERSION are also governed by the removeExisting
* flag.
*
* If the would-be parent of the location absPath is actually a
* property, or if a node type restriction would be violated, then a
* ConstraintViolationException is thrown.
*
* If the restore succeeds, the changes made to this node are
* dispatched immediately; there is no need to call save.
*
* @param absPath an absolute the path to which the version is to be
* restored.
* @param version a version object
* @param removeExisting covers what happens on identifier collision.
* @throws PathNotFoundException if the parent of absPath does
* not exist.
* @throws ItemExistsException if removeExisting is false and an identifier
* collision occurs
* @throws ConstraintViolationException If the would-be parent of the
* location absPath is actually a property, or if a node type
* restriction would be violated
* @throws VersionException if the parent node of absPath is
* read-only due to a checked-in node or if a node exists at
* absPath or if an attempt is made to restore
* the root version.
* @throws UnsupportedRepositoryOperationException
* if versioning is not
* supported.
* @throws LockException if a lock prevents the restore.
* @throws InvalidItemStateException if this Session (not
* necessarily the Node at absPath) has pending
* unsaved changes.
* @throws RepositoryException if another error occurs
*/
public void restore(String absPath, Version version, boolean removeExisting) throws PathNotFoundException, ItemExistsException, VersionException, ConstraintViolationException, UnsupportedRepositoryOperationException, LockException, InvalidItemStateException, RepositoryException;
/**
* Restores the version of the node at absPath with the
* specified version label. If successful, the change is dispatched
* immediately; there is no need to call save.
*
* This method will work regardless of whether the node at
* absPath is checked-in or not.
*
* An identifier collision occurs when a node exists outside the subgraph
* rooted at this node with the same identifier as a node that would be
* introduced by the restoreByLabel operation into the
* subgraph at this node. The result in such a case is governed by the
* removeExisting flag. If removeExisting is
* true, then the incoming node takes precedence, and the
* existing node (and its subgraph) is removed (if possible; otherwise a
* RepositoryException is thrown). If removeExisting
* is false, then a ItemExistsException is thrown
* and no changes are made. Note that this applies not only to cases where
* the restored node itself conflicts with an existing node but also to
* cases where a conflict occurs with any node that would be introduced into
* the workspace by the restore operation. In particular, conflicts
* involving subnodes of the restored node that have
* OnParentVersion settings of COPY or
* VERSION are also governed by the removeExisting
* flag.
*
* @param absPath an absolute path.
* @param versionLabel a String
* @param removeExisting a boolean flag that governs what happens in case of
* an identifier collision.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws VersionException if the specified versionLabel does
* not exist in this node's version history or if no node exists
* at absPath.
* @throws ItemExistsException if removeExisting is
* false and an identifier collision occurs.
* @throws LockException if a lock prevents the restore.
* @throws InvalidItemStateException if this Session (not
* necessarily the Node at absPath) has pending
* unsaved changes.
* @throws RepositoryException If another error occurs.
*/
public void restoreByLabel(String absPath, String versionLabel, boolean removeExisting) throws VersionException, ItemExistsException, UnsupportedRepositoryOperationException, LockException, InvalidItemStateException, RepositoryException;
/**
* This method recursively tests each versionable node in the subgraph of
* the node at absPath against its corresponding node in
* srcWorkspace with respect to the relation between their
* respective base versions and either updates the node in question or not,
* depending on the outcome of the test.
*
* When a versionable node V with base version B is encountered whose
* corresponding node V' has a base version B':
- If B' is an
* eventual predecessor of B then V is left unchanged.
- If B' is an
* eventual successor of B then V is updated to the state of V'.
- If
* B' and B are ob divergent branches of the version history then V
* fails the merge.
If bestEffort is
* true then each failed node is marked and traversal
* continues. If bestEffort is false then the
* first failed node results in a MergeException.
*
* This is a workspace-write method and therefore any changes are dispatched
* immediately; there is no need to call save.
*
* This method returns a NodeIterator over all versionable
* nodes in the subgraph that received a merge result of fail. If
* bestEffort is false, this iterator will be
* empty (since if merge returns successfully, instead of
* throwing an exception, it will be because no failures were encountered).
* If bestEffort is true, this iterator will
* contain all nodes that received a fail during the course of this
* merge operation.
*
* See the JCR specifications for more details on the behavior of this
* method.
*
* @param absPath an absolute path.
* @param srcWorkspace the name of the source workspace.
* @param bestEffort a boolean
* @return iterator over all nodes that received a merge result of "fail" in
* the course of this operation.
* @throws MergeException if bestEffort is false
* and a failed merge result is encountered.
* @throws InvalidItemStateException if this session (not necessarily the
* node at absPath) has pending unsaved changes.
* @throws NoSuchWorkspaceException if the specified
* srcWorkspace does not exist.
* @throws AccessDeniedException if the current session does not have
* sufficient rights to perform the operation.
* @throws LockException if a lock prevents the merge.
* @throws RepositoryException if another error occurs.
*/
public NodeIterator merge(String absPath, String srcWorkspace, boolean bestEffort) throws NoSuchWorkspaceException, AccessDeniedException, MergeException, LockException, InvalidItemStateException, RepositoryException;
/**
* Same as {@link #merge(String absPath, String srcWorkspace, boolean
* bestEffort)} except that an option exists to make the merge
* shallow.
*
* If isShallow is true, this method tests this
* versionable node against its corresponding node in
* srcWorkspace with respect to the relation between their
* respective base versions and either updates the node in question or not,
* depending on the outcome of the test.
*
* If isShallow is false, it recursively tests
* each versionable node in the subgraph as mentioned above. See {@link
* #merge(String absPath, String srcWorkspace, boolean bestEffort)}.
*
* If isShallow is true and this node is not
* versionable, then this method returns and no changes are made.
*
* If successful, the changes are dispatched immediately; there is no need to
* call save.
*
* This method returns a NodeIterator over all versionable
* nodes in the subgraph that received a merge result of fail. If
* bestEffort is false, this iterator will be
* empty (since if merge returns successfully, instead of
* throwing an exception, it will be because no failures were encountered).
* If bestEffort is true, this iterator will
* contain all nodes that received a fail during the course of this
* merge operation.
*
* @param absPath an absolute path.
* @param srcWorkspace the name of the source workspace.
* @param bestEffort a boolean
* @param isShallow a boolean
* @return iterator over all nodes that received a merge result of "fail" in
* the course of this operation.
* @throws MergeException if bestEffort is false
* and a failed merge result is encountered.
* @throws InvalidItemStateException if this session (not necessarily this
* node) has pending unsaved changes.
* @throws NoSuchWorkspaceException if srcWorkspace does not
* exist.
* @throws AccessDeniedException if the current session does not have
* sufficient rights to perform the operation.
* @throws LockException if a lock prevents the merge.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public NodeIterator merge(String absPath, String srcWorkspace, boolean bestEffort, boolean isShallow) throws NoSuchWorkspaceException, AccessDeniedException, MergeException, LockException, InvalidItemStateException, RepositoryException;
/**
* Completes the merge process with respect to the node at
* absPath and the specified version.
*
* When the {@link #merge} method is called on a node, every versionable
* node in that subgraph is compared with its corresponding node in the
* indicated other workspace and a "merge test result" is determined
* indicating one of the following:
*
*
- This node will be updated to the state of its correspondee (if
* the base version of the correspondee is more recent in terms of version
* history)
- This node will be left alone (if this node's base
* version is more recent in terms of version history).
- This node
* will be marked as having failed the merge test (if this node's base
* version is on a different branch of the version history from the base
* version of its corresponding node in the other workspace, thus preventing
* an automatic determination of which is more recent).
*
* (See {@link #merge} for more details)
*
* In the last case the merge of the non-versionable subgraph (the
* "content") of this node must be done by the application (for example, by
* providing a merge tool for the user).
*
* Additionally, once the content of the nodes has been merged, their
* version graph branches must also be merged. The JCR versioning system
* provides for this by keeping a record, for each versionable node that
* fails the merge test, of the base version of the corresponding node that
* caused the merge failure. This record is kept in the
* jcr:mergeFailed property of this node. After a
* merge, this property will contain one or more (if multiple
* merges have been performed) REFERENCEs that point to the
* "offending versions".
*
* To complete the merge process, the client calls doneMerge(Version
* v) passing the version object referred to be the
* jcr:mergeFailed property that the client wishes to connect
* to this node in the version graph. This has the effect of
* moving the reference to the indicated version from the
* jcr:mergeFailed property of this node to the
* jcr:predecessors.
*
* If the client chooses not to connect this node to a particular version
* referenced in the jcr:mergeFailed property, he calls {@link
* #cancelMerge(String, Version)}. This has the effect of removing the
* reference to the specified version from
* jcr:mergeFailed without adding it to
* jcr:predecessors.
*
* Once the last reference in jcr:mergeFailed has been either
* moved to jcr:predecessors (with doneMerge) or
* just removed from jcr:mergeFailed (with
* cancelMerge) the jcr:mergeFailed property is
* automatically removed, thus enabling this node to be
* checked-in, creating a new version (note that before the
* jcr:mergeFailed is removed, its OnParentVersion
* setting of ABORT prevents checkin). This new version will
* have a predecessor connection to each version for which
* doneMerge was called, thus joining those branches of the
* version graph.
*
* If successful, these changes are dispatched immediately; there is no need
* to call save.
*
* @param absPath an absolute path.
* @param version a version referred to by the jcr:mergeFailed
* property of the node at absPath.
* @throws VersionException if the version specified is not among those
* referenced in this node's jcr:mergeFailed or if the node is
* currently checked-in.
* @throws InvalidItemStateException if there are unsaved changes pending on
* the node at absPath.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws RepositoryException if another error occurs.
*/
public void doneMerge(String absPath, Version version) throws VersionException, InvalidItemStateException, UnsupportedRepositoryOperationException, RepositoryException;
/**
* Cancels the merge process with respect to the node at
* absPath and the specified version.
*
* See {@link #doneMerge} for a full explanation. Also see {@link #merge}
* for more details.
*
* If successful, these changes are dispatched immediately; there is no need
* to call save.
*
* @param absPath an absolute path.
* @param version a version referred to by the jcr:mergeFailed
* property of the node at absPath.
* @throws VersionException if the version specified is not among those
* referenced in the jcr:mergeFailed property of the node at
* absPath or if the node is currently checked-in.
* @throws InvalidItemStateException if there are unsaved changes pending on
* the node at absPath.
* @throws UnsupportedRepositoryOperationException
* if the node at
* absPath is not versionable.
* @throws RepositoryException if another error occurs.
*/
public void cancelMerge(String absPath, Version version) throws VersionException, InvalidItemStateException, UnsupportedRepositoryOperationException, RepositoryException;
/**
* Calling createConfiguration on the node N at
* absPath creates, in the configuration storage, a new
* nt:configuration node whose root is N. A reference to
* N is recorded in the jcr:root property of the new
* configuration, and a reference to the new configuration is recorded in
* the jcr:configuration property of N.
*
* A new version history is created to store baselines of the new configuration,
* and the jcr:baseVersion of the new configuration references
* the root version of the new version history.
*
* The changes are dispatched immediately; a save is not
* required.
*
* @param absPath an absolute path.
* @return a new nt:configuration node
* @throws UnsupportedRepositoryOperationException
* if N is not
* versionable.
* @throws RepositoryException if no node exists at absPath or another error occurs .
* @since JCR 2.0
*/
public Node createConfiguration(String absPath) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* This method is called by the client to set the current activity on the
* current session by specifying a previously created nt:activity
* node (see {@link #createActivity}). Changing the
* current activity is done by calling setActivity again.
* Cancelling the current activity (so that the session has no current
* activity) is done by calling setActivity(null). The previously
* set nt:activity node is returned, or null if no activity
* was previously set.
*
* @param activity an activity node
* @return The previously set nt:activity node is returned,
* or null if no activity was previously set.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support activities or if activity is not a
* nt:activity node.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public Node setActivity(Node activity) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* Returns the node representing the current activity or null
* if there is no current activity.
*
* @return An nt:activity node or null.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support activities.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public Node getActivity() throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* This method creates a new nt:activity at an
* implementation-determined location in the /jcr:system/jcr:activities
* subgraph.
*
* The repository may, but is not required to, use the title as
* a hint for what to name the new activity node. The new activity
* Node is returned.
*
* The new node addition is dispatched immediately and does not require a
* save.
*
*
* @param title a String
* @return the new activity Node.
* @throws UnsupportedRepositoryOperationException
* if the repository does
* not support activities.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public Node createActivity(String title) throws UnsupportedRepositoryOperationException, RepositoryException;
/**
* This method removes the given activityNode and all REFERENCE properties
* within all workspaces that refer to the activityNode.
* However, the existence of a REFERENCE to the activityNode
* from within version storage will cause a VersionException to be thrown.
*
* The change is dispatched immediately and does not require a save.
*
* @param activityNode an activity Node.
* @throws UnsupportedRepositoryOperationException if the repository does not support activities.
* @throws VersionException if a REFERENCE to the activityNode exists in
* version storage.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public void removeActivity(Node activityNode) throws UnsupportedRepositoryOperationException, VersionException, RepositoryException;
/**
* This method merges the changes that were made under the specified
* activity into the current workspace.
*
* An activity A will be associated with a set of versions through
* the jcr:activity reference of each version node in the set.
* We call each such associated version a member of A.
*
* For each version history H that contains one or more members of
* A, one such member will be the latest member of A in
* H. The latest member of A in H is the version in
* H that is a member of A and that has no successor versions
* (to any degree) that are also members of A.
*
* The set of versions that are the latest members of A in their
* respective version histories is called the change set of A. It
* fully describes the changes made under the activity A.
*
* This method performs a shallow merge into the current workspace of each
* version in the change set of the activity specified by
* activityNode. If there is no corresponding node in this
* workspace for a given member of the change set, that member is ignored.
*
* This method returns a NodeIterator over all versionable
* nodes in the subgraph that received a merge result of fail.
*
* The changes are dispatched immediately and do not require a save.
*
* @param activityNode an nt:activity node
* @return a NodeIterator
* @throws AccessDeniedException if the current session does not have
* sufficient rights to perform the operation.
* @throws VersionException if the specified node is not an
* nt:activity node.
* @throws MergeException in the same cases as in a regular shallow merge
* (see {@link #merge(String, String, boolean, boolean)}.
* @throws LockException if a lock prevents the merge.
* @throws InvalidItemStateException if this Session has
* pending unsaved changes.
* @throws RepositoryException if another error occurs.
* @since JCR 2.0
*/
public NodeIterator merge(Node activityNode) throws VersionException, AccessDeniedException, MergeException, LockException, InvalidItemStateException, RepositoryException;
}