org.purl.xnode
Interface XNodeRevisionManager

All Known Implementing Classes:

XNodeRevisionManagerImpl

public interface XNodeRevisionManager

XNodeRevisionManager is an interface providing revision control manager features for XNode 1.2.

The XNode API (the package org.purl.xnode.*, both its source code and documentation), are released under the Apache 2.0 License. For more details, check the LICENSE file contained with the distribution, or see The Ceryle Project for more information. It is distributed with no warranty.

This adds a new, optional element <xnode:Repository> to the document, which contains zero or more <xnode:Revision> elements, each containing the metadata and document content of a single revision.

Given that the revision control features are optional, apart from bug fixes XNode 1.1 documents are nominally valid in XNode 1.2.

Since:

XNode 1.2

Version:

$Id: XNodeRevisionManager.java,v 3.6 2007-06-15 12:10:37 altheim Exp $

Author:

Murray Altheim

Field Summary

static int	REV_LIMIT_ACTION_DELETE The enumerated constant used to indicate that upon exceeding a revision limit, the revision manager should delete the revisions exceeding the limit according to an acceptable metric, usually age.
static int	REV_LIMIT_ACTION_WARN The enumerated constant used to indicate that upon exceeding a revision limit, the revision manager should emit a warning.

Method Summary

XNodeRevision	createRevision(String cid, String nid, boolean write) Generate a new revision by creating a new XNodeRevision using the current document and metadata content of the specified XNode.
XNodeRevision	createRevision(XNode xnode) Create a new revision by copying the current document and metadata content of the specified XNode to its repository.
XNodeRevision	createRevision(XNodeID xid, boolean write) Generate a new revision by creating a new XNodeRevision using the current document and metadata content of the specified XNode.
boolean	deleteRevision(XNodeRevision revision) Delete the provided revision from its parent XNode.
int	deleteRevisions(List revisions) Delete the List of revisions from their parent XNode(s).
boolean	exceedsRevisionCountLimit(XNode xnode) Returns true if the provided XNode exceeds the set revision count limit.
boolean	exceedsRevisionSpaceLimit(XNode xnode) Returns true if the provided XNode exceeds the set revision space limit.
List	getAllRevisions(XNode xnode) Returns a List containing all revisions of the provided XNode.
String	getDisplayableRevisionDateOf(XNodeRevision revision) Returns a display version of the revision date of the XNodeRevision.
Object	getProperty(XNode xnode, String name, int version) Return a metadata property by name for a specified revision.
XNodeRevision	getRevision(String cid, String nid, int version) Return a specific revision version of the specified XNode, document nid of Collection cid.
XNodeRevision	getRevision(XNode xnode, int version) Return a specific revision version of the specified XNode, document nid of Collection cid.
int	getRevisionCount(XNode xnode) Return the count of available revisions for the provided XNode.
int	getRevisionCountLimit() Returns the revision count limit, i.e., the maximum number of revisions.
int[]	getRevisionIndex(XNode xnode) Return an ordered array of all revision numbers.
List	getRevisions(XNode xnode, int[] versions) Returns a List containing the specified revisions of the provided XNode.
List	getRevisionsBefore(XNode xnode, Date date) Returns a List containing the revisions prior to the provided Date.
int	getRevisionSize(XNode xnode, int version) Return the stored size in characters of the specified revision of the provided XNode.
int	getRevisionSpaceLimit() Returns the revision space limit (in KB), i.e., the maximum space used by stored revisions.
XNode	getXNodeFromRevision(XNode xnode, int version) Recreates an XNode provided one of its version numbers.
XNodeRevision	recreateRevision(XNode xnode, int version) Recreate an existing revision from the specified XNode's repository.
int	restoreRevision(XNodeRevision revision) Restore the provided XNodeRevision as a replacement for its parent XNode.
void	setRevisionCountLimit(int limit) Sets the revision count limit (units: revision) to limit.
void	setRevisionSpaceLimit(int limit) Sets the revision space limit (units: KB) to limit.

Field Detail

REV_LIMIT_ACTION_WARN

static final int REV_LIMIT_ACTION_WARN

The enumerated constant used to indicate that upon exceeding a revision limit, the revision manager should emit a warning.

See Also:

Constant Field Values

REV_LIMIT_ACTION_DELETE

static final int REV_LIMIT_ACTION_DELETE

The enumerated constant used to indicate that upon exceeding a revision limit, the revision manager should delete the revisions exceeding the limit according to an acceptable metric, usually age.

See Also:

Constant Field Values

Method Detail

getXNodeFromRevision

XNode getXNodeFromRevision(XNode xnode,
                           int version)

Recreates an XNode provided one of its version numbers. This does not alter the original XNode, and nothing is written to the database.

Parameters:

xnode - the XNode to be queried.

version - the revision number.

createRevision

XNodeRevision createRevision(String cid,
                             String nid,
                             boolean write)
                             throws XNodeException

Generate a new revision by creating a new XNodeRevision using the current document and metadata content of the specified XNode. The XNode is itself modified (and its modified date updated), but is only written back to the database if write is true. The new XNodeRevision is returned.

Parameters:

cid - the Collection ID String.

nid - the Node ID String.

write - if true, writes the updated XNode to the database.

Returns:

the new XNodeRevision.

Throws:

XNodeException - if the XNode does not exist, or the process fails for any reason

createRevision

XNodeRevision createRevision(XNodeID xid,
                             boolean write)
                             throws XNodeException

Generate a new revision by creating a new XNodeRevision using the current document and metadata content of the specified XNode. The XNode is itself modified (and its modified date updated), but is only written back to the database if write is true. The new XNodeRevision is returned.

Parameters:

xid - the XNodeID specifying an XNode.

write - if true, writes the updated XNode to the database.

Returns:

the new XNodeRevision.

Throws:

XNodeException - if the XNode does not exist, or the process fails for any reason

createRevision

XNodeRevision createRevision(XNode xnode)
                             throws XNodeException

Create a new revision by copying the current document and metadata content of the specified XNode to its repository. The XNode is itself modified (and its modified date updated), but is not written back to the database. The new XNodeRevision is returned.

Parameters:

xnode - the XNode to process.

Returns:

the new XNodeRevision.

Throws:

XNodeException - if the process fails for any reason.

recreateRevision

XNodeRevision recreateRevision(XNode xnode,
                               int version)
                               throws XNodeException

Recreate an existing revision from the specified XNode's repository. If the specific version is not available, an XNodeException is thrown.

Parameters:

xnode - the parent XNode to process.

version - the XNodeRevision to recreate.

Returns:

the recreated XNodeRevision.

Throws:

XNodeException - if the process fails for any reason.

restoreRevision

int restoreRevision(XNodeRevision revision)
                    throws XNodeException

Restore the provided XNodeRevision as a replacement for its parent XNode. This creates a new revision from the current content (so that it is not lost), then clones the revision's content to replace the current document content, returning the version number of the new revision. This modifies but does not store the resulting XNode to the database, returning true if successful.

Parameters:

revision - the XNodeRevision to restore.

Returns:

the version number of the new XNodeRevision

Throws:

XNodeException - if the restoration fails.

deleteRevision

boolean deleteRevision(XNodeRevision revision)
                       throws XNodeException

Delete the provided revision from its parent XNode. The XNode is itself modified (and its modified date updated), but is not written back to the database.

Parameters:

revision - the XNodeRevision to be deleted.

Returns:

true if the revision was removed.

Throws:

XNodeException - if the deletion fails for any reason.

deleteRevisions

int deleteRevisions(List revisions)
                    throws XNodeException

Delete the List of revisions from their parent XNode(s). There is no requirement that the revisions all come from the same XNode. Note that while the XNode(s) are modified, nothing is written back to the database.

Parameters:

revisions - the List of XNodeRevisions to be deleted.

Returns:

the count of successfully-deleted revisions

Throws:

XNodeException - if the process fails for any reason.

getRevisionCount

int getRevisionCount(XNode xnode)
                     throws XNodeException

Return the count of available revisions for the provided XNode.

Parameters:

xnode - the parent XNode to process.

Throws:

XNodeException - if the process fails for any reason

getRevisionCountLimit

int getRevisionCountLimit()

Returns the revision count limit, i.e., the maximum number of revisions.

Returns:

the limit set, in count of revisions.

setRevisionCountLimit

void setRevisionCountLimit(int limit)

Sets the revision count limit (units: revision) to limit.

Parameters:

limit - the limit set, in count of revisions.

exceedsRevisionCountLimit

boolean exceedsRevisionCountLimit(XNode xnode)

Returns true if the provided XNode exceeds the set revision count limit. If an implementation provides a option to activate and inactivate such limits, this should always return false when count limits are inactive.

Parameters:

xnode - the XNode to process.

Returns:

true if the XNode exceeds the count limit.

getRevisionSize

int getRevisionSize(XNode xnode,
                    int version)
                    throws XNodeException

Return the stored size in characters of the specified revision of the provided XNode. If version is -1, the size of the entire repository is returned.

Parameters:

xnode - the XNode to process.

version - the XNodeRevision to recreate.

Throws:

XNodeException

getRevisionSpaceLimit

int getRevisionSpaceLimit()

Returns the revision space limit (in KB), i.e., the maximum space used by stored revisions. Due to storage considerations this is not required to be a strictly interpretable number, but should be used as a rough guide.

Returns:

the limit set, in KB.

setRevisionSpaceLimit

void setRevisionSpaceLimit(int limit)

Sets the revision space limit (units: KB) to limit.

Parameters:

limit - the limit set, in KB.

exceedsRevisionSpaceLimit

boolean exceedsRevisionSpaceLimit(XNode xnode)

Returns true if the provided XNode exceeds the set revision space limit. If an implementation provides a option to activate and inactivate such limits, this should always return false when space limits are inactive.

Parameters:

xnode - the XNode to process.

Returns:

true if the XNode exceeds the space limit.

getRevisionIndex

int[] getRevisionIndex(XNode xnode)
                       throws XNodeException

Return an ordered array of all revision numbers. Returns an empty array if no revisions are available.

Parameters:

xnode - the XNode to process.

Throws:

XNodeException

getRevisions

List getRevisions(XNode xnode,
                  int[] versions)
                  throws XNodeException

Returns a List containing the specified revisions of the provided XNode.

Parameters:

xnode - the XNode to process.

versions - the array of requested version numbers.

Returns:

an empty List rather than a null if there are no matching revisions.

Throws:

XNodeException - if there is a processing error.

getRevision

XNodeRevision getRevision(String cid,
                          String nid,
                          int version)
                          throws XNodeException

Return a specific revision version of the specified XNode, document nid of Collection cid.

Parameters:

cid - the Collection ID String.

nid - the XNode ID String.

Returns:

the retrieved <xnode:Revision> Element.

Throws:

XNodeException - if the XNode does not exist, or the process fails for any reason

getRevision

XNodeRevision getRevision(XNode xnode,
                          int version)
                          throws XNodeException

Return a specific revision version of the specified XNode, document nid of Collection cid.

Parameters:

xnode - the XNode to be processed.

version - the version number of the requested revision.

Returns:

the retrieved XNodeRevision, or null if the specified revision does not exist.

Throws:

XNodeException - if the process fails for any reason.

getAllRevisions

List getAllRevisions(XNode xnode)
                     throws XNodeException

Returns a List containing all revisions of the provided XNode.

Parameters:

xnode - the XNode to process.

Returns:

an empty List rather than a null if there are no matching revisions.

Throws:

XNodeException - if there is a processing error.

getDisplayableRevisionDateOf

String getDisplayableRevisionDateOf(XNodeRevision revision)

Returns a display version of the revision date of the XNodeRevision. This uses the creation date if the modified date is null, returning "n/a" (or something suitable) if both fail.

Parameters:

revision - the XNodeRevision to be processed.

getRevisionsBefore

List getRevisionsBefore(XNode xnode,
                        Date date)
                        throws XNodeException

Returns a List containing the revisions prior to the provided Date. Returns an empty List rather than a null if there are no matches.

Parameters:

xnode - the XNode to be processed.

date - the Date threshold.

Throws:

XNodeException

getProperty

Object getProperty(XNode xnode,
                   String name,
                   int version)
                   throws XNodeException

Return a metadata property by name for a specified revision. Returns null if the property does not exist or is not set for the specified revision.

Parameters:

xnode - the XNode to be processed.

name - the property name.

version - the revision number.

Returns:

the Object representing the property value.

Throws:

XNodeException