org.apache.jackrabbit.api.jsr283.version
Interface VersionManager

All Known Implementing Classes:

JcrVersionManagerImpl

public interface VersionManager

The VersionManager object is accessed via 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

Method Summary

void	cancelMerge(String absPath, Version version) Cancels the merge process with respect to the node at absPath and the specified version.
Version	checkin(String absPath) 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).
void	checkout(String absPath) Sets the versionable node at absPath to checked-out status by setting its jcr:isCheckedOut property to true.
Version	checkpoint(String absPath) Performs a checkin() followed by a checkout() on the versionable node at absPath.
Node	createActivity(String title) This method creates a new nt:activity at an implementation-determined location in the /jcr:system/jcr:activities subtree.
Node	createConfiguration(String absPath, Version baseline) Calling createConfiguration on the node N at absPath creates, in the configuration storage, a new nt:configuration node whose root is N.
void	doneMerge(String absPath, Version version) Completes the merge process with respect to the node at absPath and the specified version.
Node	getActivity() Returns the node representing the current activity or null if there is no current activity.
Version	getBaseVersion(String absPath) Returns the current base version of the versionable node at absPath.
VersionHistory	getVersionHistory(String absPath) Returns the VersionHistory object of the node at absPath.
boolean	isCheckedOut(String absPath) 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.
NodeIterator	merge(Node activityNode) This method merges the changes that were made under the specified activity into the current workspace.
NodeIterator	merge(String absPath, String srcWorkspace, boolean bestEffort) This method can be thought of as a version-sensitive update.
NodeIterator	merge(String absPath, String srcWorkspace, boolean bestEffort, boolean isShallow) This method can be thought of as a version-sensitive update.
Node	removeActivity(String title) This method removes an nt:activity at an implementation-determined location in the /jcr:system/jcr:activities subtree.
void	restore(String absPath, String versionName, boolean removeExisting) Restores the node at absPath to the state defined by the version with the specified versionName.
void	restore(String absPath, Version version, boolean removeExisting) Restores the specified version to absPath.
void	restore(Version[] versions, boolean removeExisting) Restores a set of versions at once.
void	restore(Version version, boolean removeExisting) Restores the specified version and the changes the corresponding node to reflect the state defined by the specified version.
void	restoreByLabel(String absPath, String versionLabel, boolean removeExisting) Restores the version of the node at absPath with the specified version label.
Node	setActivity(Node activity) This method is called by the client to set the current activity on the session from which this version manager has been obtained.

Method Detail

checkin

Version checkin(String absPath)
                throws VersionException,
                       UnsupportedRepositoryOperationException,
                       InvalidItemStateException,
                       LockException,
                       RepositoryException

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 subtree become read-only. A node's connected non-versionable subtree 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 subtree will be equivalent to the whole subtree, 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 restore(org.apache.jackrabbit.api.jsr283.version.Version[], boolean) (all signatures), restoreByLabel(java.lang.String, java.lang.String, boolean), restore(org.apache.jackrabbit.api.jsr283.version.Version[], boolean), merge(java.lang.String, java.lang.String, boolean) and Node.update(java.lang.String) 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 the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

A VersionException is thrown or if a child item of this node has an OnParentVersion status of ABORT. This includes the case where an unresolved merge failure exists on this node, as indicated by the presence of the jcr:mergeFailed property.

If there are unsaved changes pending on the node at absPath, an InvalidItemStateException is thrown.

Throws a LockException if a lock prevents the operation.

If checkin succeeds, the change to the jcr:isCheckedOut property is automatically persisted (there is no need to do an additional save).

Parameters:

absPath - an absolute path.

Returns:

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.

UnsupportedRepositoryOperationException - If the node at absPath node is not versionable.

InvalidItemStateException - If unsaved changes exist on the node at absPath.

LockException - if a lock prevents the operation.

RepositoryException - If another error occurs.

checkout

void checkout(String absPath)
              throws UnsupportedRepositoryOperationException,
                     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 subtree no longer read-only (see checkin(String) for an explanation of the term "connected non-versionable subtree". Under simple versioning this will simply be the whole subtree).

If successful, these changes are persisted immediately, there is no need to call save.

If the node at absPath is already checked-out, this method has no effect.

If the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

Throws a LockException if a lock prevents the checkout.

Parameters:

absPath - an absolute path.

Throws:

UnsupportedRepositoryOperationException - If the node at absPath is not versionable.

LockException - if a lock prevents the checkout.

RepositoryException - If another error occurs.

checkpoint

Version checkpoint(String absPath)
                   throws VersionException,
                          UnsupportedRepositoryOperationException,
                          InvalidItemStateException,
                          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().

If the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

A VersionException is thrown 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 property.

If there are unsaved changes pending on the node at absPath, an InvalidItemStateException is thrown.

A LockException is thrown if a lock prevents the operation.

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - an absolute path.

Returns:

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.

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

InvalidItemStateException - if there are unsaved changes pending on the node at absPath.

LockException - if a lock prevents the operation.

RepositoryException - if another error occurs.

Since:

JCR 2.0

isCheckedOut

boolean isCheckedOut(String absPath)
                     throws 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.

Parameters:

absPath - an absolute path.

Returns:

a boolean

Throws:

RepositoryException - If another error occurs.

getVersionHistory

VersionHistory getVersionHistory(String absPath)
                                 throws UnsupportedRepositoryOperationException,
                                        RepositoryException

Returns the VersionHistory object of the node at absPath. This object provides access to the nt:versionHistory node holding the node's versions.

If the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

Parameters:

absPath - an absolute path.

Returns:

a VersionHistory object

Throws:

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

RepositoryException - If another error occurs.

getBaseVersion

Version getBaseVersion(String absPath)
                       throws UnsupportedRepositoryOperationException,
                              RepositoryException

Returns the current base version of the versionable node at absPath.

If the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

Parameters:

absPath - an absolute path.

Returns:

a Version object.

Throws:

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

RepositoryException - If another error occurs.

restore

void restore(Version[] versions,
             boolean removeExisting)
             throws ItemExistsException,
                    UnsupportedRepositoryOperationException,
                    VersionException,
                    LockException,
                    InvalidItemStateException,
                    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 to the corresponding node are persisted 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) subtrees. An identifier collision occurs when the current workspace contains a node outside these subtrees that has the same identifier as one of the nodes that would be introduced by the restore operation into one of these subtrees. 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 subtree) 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.

An UnsupportedRepositoryOperationException is thrown if one or more of the nodes to be restored is not versionable.

An InvalidItemStateException is thrown if this Session has pending unsaved changes.

A LockException is thrown if a lock prevents the restore.

Parameters:

versions - The set of versions to be restored.

removeExisting - governs what happens on identifier collision.

Throws:

ItemExistsException - if removeExisting is false and an identifier collision occurs with a node being restored.

UnsupportedRepositoryOperationException - if one or more of the nodes to be restored is not versionable.

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.

LockException - if a lock prevents the restore.

InvalidItemStateException - if this Session has pending unsaved changes.

RepositoryException - if another error occurs.

restore

void restore(String absPath,
             String versionName,
             boolean removeExisting)
             throws VersionException,
                    ItemExistsException,
                    UnsupportedRepositoryOperationException,
                    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 persisted immediately and there is no need to call save.

A VersionException is thrown if no version with the specified versionName exists in the node's version history or if an attempt is made to restore the root version (jcr:rootVersion).

An InvalidItemStateException is thrown if this Session (not necessarily this Node) has pending unsaved changes.

A LockException is thrown if a lock prevents the addition of the mixin.

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 subtree rooted at this node with the same identifier as a node that would be introduced by the restore operation into the subtree 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 subtree) 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.

Parameters:

absPath - an absolute path.

versionName - a Version object

removeExisting - a boolean flag that governs what happens in case of an identifier collision.

Throws:

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

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).

ItemExistsException - if removeExisting is false and an identifier collision occurs.

LockException - if a lock prevents the restore.

InvalidItemStateException - if this Session (not necessarily the Node at absPath) has pending unsaved changes.

RepositoryException - If another error occurs.

restore

void restore(Version version,
             boolean removeExisting)
             throws VersionException,
                    ItemExistsException,
                    UnsupportedRepositoryOperationException,
                    LockException,
                    RepositoryException

Restores the specified version and the changes the corresponding node to reflect the state defined by the specified version.

If the node at absPath is not versionable, an UnsupportedRepositoryOperationException is thrown.

If successful, the change is persisted immediately and there is no need to call save.

A VersionException is thrown 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).

An InvalidItemStateException is thrown if this Session (not necessarily the Node at absPath) has pending unsaved changes.

A LockException is thrown if a lock prevents the restore.

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 subtree rooted at this node with the same identifier as a node that would be introduced by the restore operation into the subtree 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 subtree) 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.

Parameters:

version - a Version object

removeExisting - a boolean flag that governs what happens in case of an identifier collision.

Throws:

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

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).

ItemExistsException - if removeExisting is false and an identifier collision occurs.

InvalidItemStateException - if this Session (not necessarily the Node at absPath) has pending unsaved changes.

LockException - if a lock prevents the restore.

RepositoryException - if another error occurs.

restore

void restore(String absPath,
             Version version,
             boolean removeExisting)
             throws PathNotFoundException,
                    ItemExistsException,
                    VersionException,
                    ConstraintViolationException,
                    UnsupportedRepositoryOperationException,
                    LockException,
                    InvalidItemStateException,
                    RepositoryException

Restores the specified version to absPath.

A node need not exist at absPath, though the parent of absPath must exist, otherwise a PathNotFoundException is thrown.

If a node does exist at absPath then it must correspond to the version being restored (the version must be a version of that node) and must not be a root version (jcr:rootVersion), otherwise a VersionException is thrown.

If no node exists at absPath then a VersionException is thrown if the parent node of absPath is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in.

If there is a node at absPath then the checked-in status of that node itself and the checked-in status of its parent are irrelevant. The restore will work even if one or both are checked-in.

An identifier collision occurs when a node exists outside the subtree rooted at absPath with the same identifier as a node that would be introduced by the restore operation into the subtree 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 subtree) 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 persisted immediately, there is no need to call save.

An InvalidItemStateException is thrown if this Session (not necessarily this Node) has pending unsaved changes.

An UnsupportedRepositoryOperationException is thrown if versioning is not supported.

A LockException is thrown if a lock prevents the restore.

Parameters:

absPath - an absolute the path to which the version is to be restored.

version - a version object

removeExisting - covers what happens on identifier collision.

Throws:

PathNotFoundException - if the parent of absPath does not exist.

ItemExistsException - if removeExisting is false and an identifier collision occurs

ConstraintViolationException - If the would-be parent of the location absPath is actually a property, or if a node type restriction would be violated

VersionException - if the parent node of absPath is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in or if a node exists at absPath that is not the node corresponding to the specified version or if an attempt is made to restore the root version (jcr:rootVersion).

UnsupportedRepositoryOperationException - if versioning is not supported.

LockException - if a lock prevents the restore.

InvalidItemStateException - if this Session (not necessarily the Node at absPath) has pending unsaved changes.

RepositoryException - if another error occurs

restoreByLabel

void restoreByLabel(String absPath,
                    String versionLabel,
                    boolean removeExisting)
                    throws VersionException,
                           ItemExistsException,
                           UnsupportedRepositoryOperationException,
                           LockException,
                           InvalidItemStateException,
                           RepositoryException

Restores the version of the node at absPath with the specified version label. If this node is not versionable, an UnsupportedRepositoryOperationException is thrown. If successful, the change is persisted immediately and there is no need to call save.

A VersionException is thrown if the specified versionLabel does not exist in this node's version history.

An InvalidItemStateException is thrown if this Session (not necessarily Node at absPath) has pending unsaved changes.

A LockException is thrown if a lock prevents the restore.

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 subtree rooted at this node with the same identifier as a node that would be introduced by the restoreByLabel operation into the subtree 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 subtree) 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.

Parameters:

absPath - an absolute path.

versionLabel - a String

removeExisting - a boolean flag that governs what happens in case of an identifier collision.

Throws:

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

VersionException - if the specified versionLabel does not exist in this node's version history.

ItemExistsException - if removeExisting is false and an identifier collision occurs.

LockException - if a lock prevents the restore.

InvalidItemStateException - if this Session (not necessarily the Node at absPath) has pending unsaved changes.

RepositoryException - If another error occurs.

merge

NodeIterator merge(String absPath,
                   String srcWorkspace,
                   boolean bestEffort)
                   throws NoSuchWorkspaceException,
                          AccessDeniedException,
                          MergeException,
                          LockException,
                          InvalidItemStateException,
                          RepositoryException

This method can be thought of as a version-sensitive update.

It recursively tests each versionable node in the subtree 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.

A MergeException is thrown if bestEffort is false and a versionable node is encountered whose corresponding node's base version is on a divergent branch from this node's base version.

If successful, the changes are persisted immediately, there is no need to call save.

This method returns a NodeIterator over all versionable nodes in the subtree 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.

If the specified srcWorkspace does not exist, a NoSuchWorkspaceException is thrown.

If the current session does not have sufficient permissions to perform the operation, then an AccessDeniedException is thrown.

An InvalidItemStateException is thrown if this session (not necessarily this Node) has pending unsaved changes.

A LockException is thrown if a lock prevents the merge.

Parameters:

absPath - an absolute path.

srcWorkspace - the name of the source workspace.

bestEffort - a boolean

Returns:

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.

InvalidItemStateException - if this session (not necessarily the node at absPath) has pending unsaved changes.

NoSuchWorkspaceException - if the specified srcWorkspace does not exist.

AccessDeniedException - if the current session does not have sufficient rights to perform the operation.

LockException - if a lock prevents the merge.

RepositoryException - if another error occurs.

merge

NodeIterator merge(String absPath,
                   String srcWorkspace,
                   boolean bestEffort,
                   boolean isShallow)
                   throws NoSuchWorkspaceException,
                          AccessDeniedException,
                          MergeException,
                          LockException,
                          InvalidItemStateException,
                          RepositoryException

This method can be thought of as a version-sensitive update.

If isShallow is true, it 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 subtree as mentioned above.

If isShallow is true and this node is not versionable, then this method returns and no changes are made.

A MergeException is thrown if bestEffort is false and a versionable node is encountered whose corresponding node's base version is on a divergent branch from the base version of the node at absPath.

If successful, the changes are persisted immediately, there is no need to call save.

This method returns a NodeIterator over all versionable nodes in the subtree 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.

If the specified srcWorkspace does not exist, a NoSuchWorkspaceException is thrown.

If the current session does not have sufficient permissions to perform the operation, then an AccessDeniedException is thrown.

An InvalidItemStateException is thrown if this session (not necessarily the node at absPath) has pending unsaved changes.

A LockException is thrown if a lock prevents the merge.

Parameters:

absPath - an absolute path.

srcWorkspace - the name of the source workspace.

bestEffort - a boolean

isShallow - a boolean

Returns:

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.

InvalidItemStateException - if this session (not necessarily this node) has pending unsaved changes.

NoSuchWorkspaceException - if srcWorkspace does not exist.

AccessDeniedException - if the current session does not have sufficient rights to perform the operation.

LockException - if a lock prevents the merge.

RepositoryException - if another error occurs.

Since:

JCR 2.0

doneMerge

void doneMerge(String absPath,
               Version version)
               throws VersionException,
                      InvalidItemStateException,
                      UnsupportedRepositoryOperationException,
                      RepositoryException

Completes the merge process with respect to the node at absPath and the specified version.

When the merge(java.lang.String, java.lang.String, boolean) method is called on a node, every versionable node in that subtree is compared with its corresponding node in the indicated other workspace and a "merge test result" is determined indicating one of the following:

1. 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)
2. This node will be left alone (if this node's base version is more recent in terms of version history).
3. 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 merge(java.lang.String, java.lang.String, boolean) for more details)

In the last case the merge of the non-versionable subtree (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 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 persisted immediately, there is no need to call save.

A VersionException is thrown if the version specified is not among those referenced in this node's jcr:mergeFailed property.

If there are unsaved changes pending on this node, an InvalidItemStateException is thrown.

An UnsupportedRepositoryOperationException is thrown if this node is not versionable.

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - an absolute path.

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.

InvalidItemStateException - if there are unsaved changes pending on the node at absPath.

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

RepositoryException - if another error occurs.

cancelMerge

void cancelMerge(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 doneMerge(java.lang.String, org.apache.jackrabbit.api.jsr283.version.Version) for a full explanation. Also see merge(java.lang.String, java.lang.String, boolean) for more details.

If successful, these changes are persisted immediately, there is no need to call save.

A VersionException is thrown 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.

An UnsupportedRepositoryOperationException is thrown if the node at absPath is not versionable.

If there are unsaved changes pending on the node at absPath, an InvalidItemStateException is thrown.

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - an absolute path.

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.

InvalidItemStateException - if there are unsaved changes pending on the node at absPath.

UnsupportedRepositoryOperationException - if the node at absPath is not versionable.

RepositoryException - if another error occurs.

createConfiguration

Node createConfiguration(String absPath,
                         Version baseline)
                         throws 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.

If the specified baseline is null, a new version history is created to store baselines of the new configuration, and the jcr:baseVersion of the new configuration references the root of the new version history. If the specified baseline is not null, the jcr:baseVersion of the new configuration references the specified baseline.

The changes are persisted immediately, a save is not required.

An UnsupportedRepositoryOperationException is thrown if N is not versionable.

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - an absolute path.

baseline - a Version

Returns:

a new nt:configuration node

Throws:

UnsupportedRepositoryOperationException - if N is not versionable.

RepositoryException - if another error occurs.

Since:

JCR 2.0

setActivity

Node setActivity(Node activity)
                 throws UnsupportedRepositoryOperationException,
                        RepositoryException

This method is called by the client to set the current activity on the session from which this version manager has been obtained. 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 activity Node is returned.

An UnsupportedRepositoryOperationException is thrown if the repository does not support activities or if activity is not a nt:activity node.

Parameters:

activity - an activity node

Returns:

the activity node

Throws:

UnsupportedRepositoryOperationException - if the repository does not support activities or if activity is not a nt:activity node.

RepositoryException - if another error occurs.

Since:

JCR 2.0

getActivity

Node getActivity()
                 throws UnsupportedRepositoryOperationException,
                        RepositoryException

Returns the node representing the current activity or null if there is no current activity.

Returns:

An nt:activity node or null.

Throws:

UnsupportedRepositoryOperationException - if the repository does not support activities.

RepositoryException - if another error occurs.

Since:

JCR 2.0

createActivity

Node createActivity(String title)
                    throws UnsupportedRepositoryOperationException,
                           RepositoryException

This method creates a new nt:activity at an implementation-determined location in the /jcr:system/jcr:activities subtree.

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 is persisted immediately and does not require a save.

An UnsupportedRepositoryOperationException is thrown if the repository does not support activities.

A RepositoryException is thrown if another error occurs.

Parameters:

title - a String

Returns:

the new activity Node.

Throws:

UnsupportedRepositoryOperationException - if the repository does not support activities.

RepositoryException - if another error occurs.

Since:

JCR 2.0

removeActivity

Node removeActivity(String title)
                    throws UnsupportedRepositoryOperationException,
                           RepositoryException

This method removes an nt:activity at an implementation-determined location in the /jcr:system/jcr:activities subtree.

The change is persisted immediately and does not require a save.

An UnsupportedRepositoryOperationException is thrown if the repository does not support activities.

A RepositoryException is thrown if another error occurs.

Parameters:

title - a String

Returns:

the new activity Node.

Throws:

UnsupportedRepositoryOperationException - if the repository does not support activities.

RepositoryException - if another error occurs.

Since:

JCR 2.0

merge

NodeIterator merge(Node activityNode)
                   throws VersionException,
                          AccessDeniedException,
                          MergeException,
                          LockException,
                          InvalidItemStateException,
                          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 subtree that received a merge result of fail.

A VersionException is thrown if the specified node is not an nt:activity node.

A MergeException is thrown in the same cases as in a regular shallow merge (see merge(String, String, boolean, boolean)).

If the current session does not have sufficient permissions to perform the operation, then an AccessDeniedException is thrown.

An InvalidItemStateException is thrown if this Session has pending unsaved changes.

A LockException is thrown if a lock prevents the merge.

An UnsupportedRepositoryOperationException is thrown if this operation is not supported by this implementation.

A RepositoryException is thrown if another error occurs.

Parameters:

activityNode - an nt:activity node

Returns:

a NodeIterator

Throws:

AccessDeniedException - if the current session does not have sufficient rights to perform the operation.

VersionException - if the specified node is not an nt:activity node.

MergeException - in the same cases as in a regular shallow merge (see merge(String, String, boolean, boolean).

LockException - if a lock prevents the merge.

InvalidItemStateException - if this Session has pending unsaved changes.

RepositoryException - if another error occurs.

Since:

JCR 2.0