VersionHistory object wraps an nt:versionHistory
* node. It provides convenient access to version history information.
*
* @author Markus Nix
* @package phpcr
* @subpackage version
*/
interface VersionHistory
{
/**
* Returns the UUID of the versionable node for which this is the version history.
*
* @return the UUID of the versionable node for which this is the version history.
* @throws RepositoryException if an error occurs.
*/
public function getVersionableUUID();
/**
* Returns the root version of this version history.
*
* @return a Version object.
* @throws RepositoryException if an error occurs.
*/
public function getRootVersion();
/**
* Returns an iterator over all the versions within this version history
* The order of the returned objects will not necessarily correspond to the
* order of versions in terms of the successor relation. To traverse the
* version graph one must traverse the jcr:successor REFERENCE
* properties starting with the root version. A version history will always
* have at least one version, the root version. Therefore, this method will
* always return an iterator of at least size 1.
*
* @return a VersionIterator object.
* @throws RepositoryException if an error occurs.
*/
public function getAllVersions();
/**
* Retrieves a particular version from this version history by version name.
*
* Throws a VersionException if the specified version is not in
* this version history.
*
* @param versionName a version name
* @return a Version object.
* @throws VersionException if the specified version is not in this version history.
* @throws RepositoryException if an error occurs.
*/
public function getVersion( $versionName );
/**
* Retrieves a particular version from this version history by version label.
*
* Throws a VersionException if the specified label is not in
* this version history.
*
* @param label a version label
* @return a Version object.
* @throws VersionException if the specified label is not in this version history.
* @throws RepositoryException if an error occurs.
*/
public function getVersionByLabel( $label );
/**
* Adds the specified label to the specified version. This corresponds to adding a
* value to the jcr:versionLabels multi-value property of the
* nt:version node that represents the specified version.
*
* 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.
*
* 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 in this version history will throw a VersionException.
*
* @param versionName the name of the version to which the label is to be added.
* @param label the label to be added.
* @param 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 VersionException.
*
* @throws VersionException if an attempt is made to add an existing label to a version history
* and moveLabel is false or if the specifed version does not exisit in
* this version history.
* @throws RepositoryException if another error occurs.
*/
public function addVersionLabel( $versionName, $label, $moveLabel );
/**
* Removes the specified label from among the labels of this version history.
* This corresponds to removing a property from the jcr:versionLabels
* child node of the nt:versionHistory node that represents this version
* history.
*
* 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.
*
* If a label is specified that does not exist in this version history,
* a VersionException is thrown.
*
* @param label a version label
* @throws VersionException if the name labvel does not exist in this version history.
* @throws RepositoryException if another error occurs.
*/
public function removeVersionLabel( $label );
/**
* Returns true if the given version has the given label.
* @param version a Version object
* @param label a version label
* @return a boolean.
* @throws VersionException if the specified version is not of this version history.
* @throws RepositoryException if another error occurs.
*
*/
public function hasVersionLabel( Version $version, $label );
/**
* 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.
* @param version
* @return a String array containing all the labels of the given version
* @throws VersionException if the specified version is not in this version history.
* @throws RepositoryException if another error occurs.
*/
public function getVersionLabels( Version $version );
/**
* 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.
*
* A ReferentialIntegrityException will be thrown 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 has read access to
* that REFERENCE property.
*
* An AccessDeniedException will be thrown 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.
*
* Throws an UnsupportedRepositoryOperationException if this operation is
* not supported by the implementation.
*
* Throws a VersionException if the named version is not in this VersionHistory.
*
* @param 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.
* @throws 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.
* @throws UnsupportedRepositoryOperationException if this operation is not supported by the implementation.
* @throws VersionException if the named version is not in this version history.
* @throws RepositoryException if another error occurs.
*/
public function removeVersion( $versionName );
}
?>