javax.jcr.version
Interface VersionHistory

All Superinterfaces:

Item, Node

public interface VersionHistory
extends Node

A VersionHistory object wraps an nt:versionHistory node. It provides convenient access to version history information.

Field Summary

Fields inherited from interface javax.jcr.Node

JCR_CHILD_NODE_DEFINITION, JCR_CONTENT, JCR_FROZEN_NODE, JCR_PROPERTY_DEFINITION, JCR_ROOT_VERSION, JCR_VERSION_LABELS

Method Summary

void	addVersionLabel(java.lang.String versionName, java.lang.String label, boolean moveLabel) Adds the specified label to the specified version.
NodeIterator	getAllFrozenNodes() Returns an iterator over all the frozen nodes of all the versions of this version history.
NodeIterator	getAllLinearFrozenNodes() This method returns all the frozen nodes of all the versions in this version history in the same order as getAllLinearVersions().
VersionIterator	getAllLinearVersions() This method returns an iterator over all the versions in the line of descent from the root version to that base version within this history that is bound to the workspace through which this VersionHistory was accessed.
VersionIterator	getAllVersions() Returns an iterator over all the versions within this version history.
Version	getRootVersion() Returns the root version of this version history.
Version	getVersion(java.lang.String versionName) Retrieves a particular version from this version history by version name.
java.lang.String	getVersionableIdentifier() Returns the identifier of the versionable node for which this is the version history.
java.lang.String	getVersionableUUID() Deprecated. As of JCR 2.0, getVersionableIdentifier() should be used instead.
Version	getVersionByLabel(java.lang.String label) Retrieves a particular version from this version history by version label.
java.lang.String[]	getVersionLabels() Returns all version labels of the history or an empty array if there are none.
java.lang.String[]	getVersionLabels(Version version) Returns all version labels of the given version - empty array if none.
boolean	hasVersionLabel(java.lang.String label) Returns true if any version in the history has the given label.
boolean	hasVersionLabel(Version version, java.lang.String label) Returns true if the given version has the given label.
void	removeVersion(java.lang.String versionName) Removes the named version from this version history and automatically repairs the version graph.
void	removeVersionLabel(java.lang.String label) Removes the specified label from among the labels of this version history.

Methods inherited from interface javax.jcr.Node

addMixin, addNode, addNode, canAddMixin, cancelMerge, checkin, checkout, doneMerge, followLifecycleTransition, getAllowedLifecycleTransistions, getBaseVersion, getCorrespondingNodePath, getDefinition, getIdentifier, getIndex, getLock, getMixinNodeTypes, getNode, getNodes, getNodes, getNodes, getPrimaryItem, getPrimaryNodeType, getProperties, getProperties, getProperties, getProperty, getReferences, getReferences, getSharedSet, getUUID, getVersionHistory, getWeakReferences, getWeakReferences, hasNode, hasNodes, hasProperties, hasProperty, holdsLock, isCheckedOut, isLocked, isNodeType, lock, merge, orderBefore, removeMixin, removeShare, removeSharedSet, restore, restore, restore, restoreByLabel, setPrimaryType, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, unlock, update

Methods inherited from interface javax.jcr.Item

accept, getAncestor, getDepth, getName, getParent, getPath, getSession, isModified, isNew, isNode, isSame, refresh, remove, save

Method Detail

getVersionableUUID

java.lang.String getVersionableUUID()
                                    throws RepositoryException

Deprecated. As of JCR 2.0, getVersionableIdentifier() should be used instead.

Returns the identifier of the versionable node for which this is the version history.

Returns:

the identifier of the versionable node for which this is the version history.

Throws:

RepositoryException - if an error occurs.

getVersionableIdentifier

java.lang.String getVersionableIdentifier()
                                          throws RepositoryException

Returns the identifier of the versionable node for which this is the version history.

Returns:

the identifier of the versionable node for which this is the version history.

Throws:

RepositoryException - if an error occurs.

Since:

JCR 2.0

getRootVersion

Version getRootVersion()
                       throws RepositoryException

Returns the root version of this version history.

Returns:

a Version object.

Throws:

RepositoryException - if an error occurs.

getAllLinearVersions

VersionIterator getAllLinearVersions()
                                     throws RepositoryException

This method returns an iterator over all the versions in the line of descent from the root version to that base version within this history that is bound to the workspace through which this VersionHistory was accessed.

Within a version history H, B is the base version bound to workspace W if and only if there exists a versionable node N in W whose version history is H and B is the base version of N.

The line of descent from version V1 to V2, where V2 is a successor of V1, is the ordered list of versions starting with V1 and proceeding through each direct successor to V2.

The versions are returned in order of creation date, from oldest to newest.

Note that in a simple versioning repository the behavior of this method is equivalent to returning all versions in the version history in order from oldest to newest.

Returns:

a VersionIterator object.

Throws:

RepositoryException - if an error occurs.

getAllVersions

VersionIterator getAllVersions()
                               throws RepositoryException

Returns an iterator over all the versions within this version history. If the version graph of this history is linear then the versions are returned in order of creation date, from oldest to newest. Otherwise the order of the returned versions is implementation-dependent.

Returns:

a VersionIterator object.

Throws:

RepositoryException - if an error occurs.

getAllLinearFrozenNodes

NodeIterator getAllLinearFrozenNodes()
                                     throws RepositoryException

This method returns all the frozen nodes of all the versions in this version history in the same order as getAllLinearVersions().

Returns:

a NodeIterator object.

Throws:

RepositoryException - if an error occurs.

Since:

JCR 2.0

getAllFrozenNodes

NodeIterator getAllFrozenNodes()
                               throws RepositoryException

Returns an iterator over all the frozen nodes of all the versions of this version history. Under simple versioning the order of the returned nodes will be the order of their creation. Under full versioning the order is implementation-dependent.

Returns:

a NodeIterator object.

Throws:

RepositoryException - if an error occurs.

Since:

JCR 2.0

getVersion

Version getVersion(java.lang.String versionName)
                   throws VersionException,
                          RepositoryException

Retrieves a particular version from this version history by version name.

Parameters:

versionName - a version name

Returns:

a Version object.

Throws:

VersionException - if the specified version is not in this version history.

RepositoryException - if an error occurs.

getVersionByLabel

Version getVersionByLabel(java.lang.String label)
                          throws VersionException,
                                 RepositoryException

Retrieves a particular version from this version history by version label.

Parameters:

label - a version label

Returns:

a Version object.

Throws:

VersionException - if the specified label is not in this version history.

RepositoryException - if an error occurs.

addVersionLabel

void addVersionLabel(java.lang.String versionName,
                     java.lang.String label,
                     boolean moveLabel)
                     throws LabelExistsVersionException,
                            VersionException,
                            RepositoryException

Adds the specified label to the specified version.

The label must be a JCR name in either qualified or expanded form and therefore must conform to the syntax restriction that apply to such names. In particular a colon (":") should not be used unless it is intended as a prefix delimiter in a qualified name.

Adding a version label to a version corresponds to adding a reference property with a name specified by the label parameter to the jcr:versionLabels sub node of the nt:versionHistory node. The reference property points to the nt:version node that represents the specified version.

This is a workspace-write method and therefore the change is made immediately.

Within a particular version history, a given label may appear a maximum of once. If the specified label is already assigned to a version in this history and moveLabel is true then the label is removed from its current location and added to the version with the specified versionName. If moveLabel is false, then an attempt to add a label that already exists will fail.

Parameters:

versionName - the name of the version to which the label is to be added.

label - the label to be added, A JCR name in either expanded or qualified form.

moveLabel - if true, then if label is already assigned to a version in this version history, it is moved to the new version specified; if false, then attempting to assign an already used label will throw a LabelExistsVersionException.

Throws:

LabelExistsVersionException - if moveLabel is false, and an attempt is made to add a label that already exists in this version history.

VersionException - if the specified version does not exist in this version history or if the specified version is the root version (jcr:rootVersion).

RepositoryException - if another error occurs.

removeVersionLabel

void removeVersionLabel(java.lang.String label)
                        throws VersionException,
                               RepositoryException

Removes the specified label from among the labels of this version history. The label must be a JCR name in either qualified or expanded form. This corresponds to removing a property from the jcr:versionLabels child node of the nt:versionHistory node that represents this version history.

This is workspace-write method and therefore the change is made immediately.

Parameters:

label - a version label. A JCR name in either expanded or qualified form.

Throws:

VersionException - if the name label does not exist in this version history.

RepositoryException - if another error occurs.

hasVersionLabel

boolean hasVersionLabel(java.lang.String label)
                        throws RepositoryException

Returns true if any version in the history has the given label. The label must be a JCR name in either qualified or expanded form.

Parameters:

label - a version label. A JCR name in either expanded or qualified form.

Returns:

a boolean.

Throws:

RepositoryException - if an error occurs.

hasVersionLabel

boolean hasVersionLabel(Version version,
                        java.lang.String label)
                        throws VersionException,
                               RepositoryException

Returns true if the given version has the given label. The label must be a JCR name in either qualified or expanded form.

Parameters:

version - a Version object

label - a version label. A JCR name in either expanded or qualified form.

Returns:

a boolean.

Throws:

VersionException - if the specified version is not of this version history.

RepositoryException - if another error occurs.

getVersionLabels

java.lang.String[] getVersionLabels()
                                    throws RepositoryException

Returns all version labels of the history or an empty array if there are none.

Returns:

a String array containing all the labels of the version history.

Throws:

RepositoryException - if an error occurs.

getVersionLabels

java.lang.String[] getVersionLabels(Version version)
                                    throws VersionException,
                                           RepositoryException

Returns all version labels of the given version - empty array if none. Throws a VersionException if the specified version is not in this version history.

Parameters:

version - a Version object

Returns:

a String array containing all the labels of the given version

Throws:

VersionException - if the specified version is not in this version history.

RepositoryException - if another error occurs.

removeVersion

void removeVersion(java.lang.String versionName)
                   throws ReferentialIntegrityException,
                          AccessDeniedException,
                          UnsupportedRepositoryOperationException,
                          VersionException,
                          RepositoryException

Removes the named version from this version history and automatically repairs the version graph. If the version to be removed is V, V's predecessor set is P and V's successor set is S, then the version graph is repaired s follows:

• For each member of P, remove the reference to V from its successor list and add references to each member of S.
• For each member of S, remove the reference to V from its predecessor list and add references to each member of P.

Note that this change is made immediately; there is no need to call save. In fact, since the the version storage is read-only with respect to normal repository methods, save does not even function in this context.

Parameters:

versionName - the name of a version in this version history.

Throws:

ReferentialIntegrityException - if the specified version is currently the target of a REFERENCE property elsewhere in the repository (not necessarily in this workspace) and the current Session has read access to that REFERENCE property.

AccessDeniedException - if the current Session does not have permission to remove the specified version or if the specified version is currently the target of a REFERENCE property elsewhere in the repository (not just in this workspace) and the current Session does not have read access to that REFERENCE property.

UnsupportedRepositoryOperationException - if this operation is not supported by the implementation.

VersionException - if the named version is not in this version history.

RepositoryException - if another error occurs.