The Node interface has the following version-related methods.
|
javax.jcr. |
|
|
Version |
checkin() Creates a new version with a system generated name and returns that version. The jcr:isCheckedOut property of this node is set to false thus putting the node into the checked-in state. This means that this 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. 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 restore11, Node.merge and 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). See 8.2.5 Check In for more details. If this node is already checked-in, this method has no effect but returns the current base version of this node. If this node 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 checkin succeeds, the change to the jcr:checkedOut property is automatically saved (there is no need to do an additional save). If there are unsaved changes pending on this node, an InvalidItemStateException is thrown. A LockException is thrown if a lock prevents the checkin. A RepositoryException is thrown if an error occurs. |
|
void |
checkout() Sets this versionable node to checked-out status by setting its jcr:isCheckedOut property to true, 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, above, for an explanation of the term “connected non-versionable subtree”). If successful, these changes are persisted immediately, there is no need to call save. See 8.2.6 Check Out for more details. If this node is not versionable, an UnsupportedRepositoryOperationException is thrown. A LockException is thrown if a lock prevents the checkout. A RepositoryException is thrown if an error occurs. |
|
NodeIterator |
merge(String srcWorkspace, boolean bestEffort) This method can be thought of as a version-sensitive update (see 7.1.8 Updating and Cloning Nodes across Workspaces). It recursively tests each versionable node in the subtree of this 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. For details see 8.2.10 Merge. 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 it 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. A RepositoryException is thrown if another error occurs. |
|
void |
doneMerge(Version version) Completes the merge process with respect to this node and the specified version. See 8.2.10 Merge for more details. If successful, the 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 or if this node is currently checked-in. An UnsupportedRepositoryOperationException is thrown if this node is not versionable. If there are unsaved changes pending on this node, an InvalidItemStateException is thrown. A LockException is thrown if a lock prevents the operation. A RepositoryException is thrown if another error occurs. |
|
void |
cancelMerge(Version version) Cancels the merge process with respect to this node and the specified version. See 8.2.10 Merge for more details. If successful, the 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 or if this node is currently checked-in. An UnsupportedRepositoryOperationException is thrown if this node is not versionable. If there are unsaved changes pending on this node, an InvalidItemStateException is thrown. A LockException is thrown if a lock prevents the operation. A RepositoryException is thrown if another error occurs. |
|
boolean |
isCheckedOut() Returns true if this node is either
Returns false if this node is either
A RepositoryException is thrown if an error occurs. |
|
void |
restore(String versionName, Restores this node to the state defined by the version with the specified versionName. 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 no version with the specified versionName exists in 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 this Node) has pending unsaved changes. This method will work regardless of whether this node is checked-in or not. A UUID collision occurs when a node exists outside the subtree rooted at this node with the same UUID 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 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 (see 8.2.11 OnParentVersion Attribute) are also governed by the removeExisting flag. A LockException is thrown if a lock prevents the restore. A RepositoryException is thrown if another error occurs. |
|
void |
restore(Version version, Restores this node to the state defined by the specified version. 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 version is not part of this node's version history. An InvalidItemStateException is thrown if this Session (not necessarily this Node) has pending unsaved changes. This method will work regardless of whether this node is checked-in or not. A UUID collision occurs when a node exists outside the subtree rooted at this node with the same UUID 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 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 (see 8.2.11 OnParentVersion Attribute) are also governed by the removeExisting flag. A LockException is thrown if a lock prevents the restore. A RepositoryException is thrown if another error occurs. |
|
void |
restore(Version version, Restores the specified version to relPath, relative to this node. A node need not exist at relPath, though the parent of relPath must exist, otherwise a PathNotFoundException is thrown. If a node does exist at relPath then it must correspond to the version being restored (the version must be a version of that node), otherwise a VersionException is thrown. If no node exists at relPath then a VersionException is thrown if the parent node of relPath is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. If there is a node at relPath 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. A UUID collision occurs when a node exists outside the subtree rooted at relPath with the same UUID as a node that would be introduced by the restore operation into the subtree at relPath (note that in cases where there is no node at relPath, this amounts to saying that a UUID collision occurs if there exists a node anywhere in this workspace with the same UUID as a node that would be introduced by the restore). 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 (see 8.2.11 OnParentVersion Attribute) are also governed by the removeExisting flag. If the would-be parent of the location relPath 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. A RepositoryException is thrown if another error occurs. |
|
void |
restoreByLabel(String versionLabel, Restores this node to the state defined by the version with the specified versionLabel. 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 no version with the specified versionLabel exists in this node's version history. This method will work regardless of whether this node is checked-in or not. A UUID collision occurs when a node exists outside the subtree rooted at this node with the same UUID 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 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 (see 8.2.11 OnParentVersion Attribute) are also governed by the removeExisting flag. An InvalidItemStateException is thrown if this Session (not necessarily this Node) has pending unsaved changes. A LockException is thrown if a lock prevents the restore. A RepositoryException is thrown if another error occurs. |
|
VersionHistory |
getVersionHistory() Returns the VersionHistory object of this node. This object provides access to the nt:versionHistory node holding this node's versions. If this node is not versionable, an UnsupportedRepositoryOperationException is thrown. A RepositoryException is thrown if another error occurs. |
|
Version |
getBaseVersion() Returns the current base version of this versionable node. If this node is not versionable, an UnsupportedRepositoryOperationException is thrown. A RepositoryException is thrown if another error occurs. |