org.ceryle.xnode
Class XNodeRevisionManagerImpl

java.lang.Object
  org.ceryle.xnode.XNodeRevisionManagerImpl

All Implemented Interfaces:

XNodeRevisionManager

public class XNodeRevisionManagerImpl
extends Object
implements XNodeRevisionManager

Provides an implementation of the XNodeStore API as a database manager for XNode (XML Node) content.

The XNode Implementation (the package org.ceryle.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.

An XNode's repository as a list of XNodeRevision objects is not generated automatically upon creation of the XNode, only upon demand. The only method that accesses information about the repository that does not generate the repository is the getRevisionCount(XNode) method, which uses the number of <Revision> DOM Elements as an alternative. The repository is also explicitly generated upon a call to the XNodeRevisionManager's getRepository(XNode) method.

Revision Limits

The XNodeRevisionManager is expected to maintain settings regarding repository limits, both of revision count and space used (in KB). These settings are to be set elsewhere (such as in a UI preferences dialog) and set as System properties whose names begin with xnode-revision-*, and which are processed into boolean, int, and enumerated values and available via get() methods from this class.

Miscellany

And in case there's any confusion, XNodeRevisions are objects (as <xnode:Revision> elements when serialized as XML) specified by a version number, the latter incremented as each revision is created.

Since:

XNode 1.2

Version:

$Id: XNodeRevisionManagerImpl.java,v 3.7 2007-06-15 15:48:03 altheim Exp $

Author:

Murray Altheim

Field Summary

static String	REV_COUNT_LIMIT The System property name for the Ceryle database revision count limit value.
static String	REV_COUNT_LIMIT_ACTION The System property name for the Ceryle database revision count limit action value.
static String	REV_SPACE_LIMIT The System property name for the Ceryle database revision space limit value.
static String	REV_SPACE_LIMIT_ACTION The System property name for the Ceryle database revision space limit action value.
static String	REV_USE_COUNT_LIMIT The System property name for the Ceryle database use revision count limit flag.
static String	REV_USE_SPACE_LIMIT The System property name for the Ceryle database use revision space limit flag.
static String	TS_FORMAT Timestamp format "yyyy-MM-dd'T'HH:mm:ss", eg., "2002-09-14T14:23:55".

Fields inherited from interface org.purl.xnode.XNodeRevisionManager

REV_LIMIT_ACTION_DELETE, REV_LIMIT_ACTION_WARN

Constructor Summary

XNodeRevisionManagerImpl(XNodeStore xnodestore)
Constructor with a parent XNodeStore.

Method Summary

Date	convertTimeStamp(String timestamp) Converts a String in timestamp format (such as the creation and modification date Strings, of the form "yyyy-MM-dd'T'HH:mm:ss") in UTC to a Date.
XNodeRevision	createRevision(String cid, String nid, boolean write) Generate a new XNodeRevision for the specified XNode, adding it to the XNode's repository.
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 a 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 XNodeRevisions of the provided XNode.
static int	getCurrentVersion(XNode xnode) A static utility method that returns the version number 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 the named property name of version version of XNode xnode as an Object, null if it has not been set.
List	getRepository(XNode xnode) Returns the List backing the XNode's repository (i.e., the List of individual XNodeRevision objects).
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 (units: revision).
static int	getRevisionCountLimitAction() Returns the revision count limit action, the action that occurs when an XNode's revision count limit is exceeded.
int[]	getRevisionIndex(XNode xnode) Return an ordered array of all revision numbers.
List	getRevisions(XNode xnode, int[] versions) Returns a List containing the XNodeRevisions (specified by version number) 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 (units: KB).
static int	getRevisionSpaceLimitAction() Returns the revision space limit action, the action that occurs when an XNode's revision space limit is exceeded.
XNode	getXNodeFromRevision(XNode xnode, int version) Recreates an XNode provided one of its version numbers.
XNodeRevision	importRevision(XNode xnode, XNode source) Imports XNode source (ignoring any of that XNode's revisions) as a new revision of XNode xnode by copying the current document and metadata content of the source XNode to xnode's repository.
XNodeRevision	recreateRevision(XNode xnode, Element revision) Recreate an XNodeRevision provided the parent XNode and the source <xnode:Revision> Element.
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.
static void	setProperties() Called upon instantiation of the class, this method establishes the XNodeRevisionManager properties, based on System properties.
void	setRevisionCountLimit(int limit) Sets the revision count limit (units: revision) to limit.
Date	setRevisionDateOf(XNodeRevision revision) Sets the revision date of the XNodeRevision based on the XNodeRevision's <xnode:Header> Element.
void	setRevisionSpaceLimit(int limit) Sets the revision space limit (units: KB) to limit.
static boolean	useRevisionCountLimits() Returns true if revision count limits are active.
static boolean	useRevisionSpaceLimits() Returns true if revision space limits are active.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TS_FORMAT

public static final String TS_FORMAT

Timestamp format "yyyy-MM-dd'T'HH:mm:ss", eg., "2002-09-14T14:23:55". This is identical to ClockImpl.TS_FORMAT.

See Also:

Constant Field Values

REV_USE_COUNT_LIMIT

public static final String REV_USE_COUNT_LIMIT

The System property name for the Ceryle database use revision count limit flag. The value is "xnode-revision-use-count-limit".

See Also:

Constant Field Values

REV_COUNT_LIMIT

public static final String REV_COUNT_LIMIT

The System property name for the Ceryle database revision count limit value. The value is "xnode-revision-count-limit".

See Also:

Constant Field Values

REV_COUNT_LIMIT_ACTION

public static final String REV_COUNT_LIMIT_ACTION

The System property name for the Ceryle database revision count limit action value. The value is "xnode-revision-count-limit-action".

See Also:

Constant Field Values

REV_USE_SPACE_LIMIT

public static final String REV_USE_SPACE_LIMIT

The System property name for the Ceryle database use revision space limit flag. The value is "xnode-revision-use-space-limit".

See Also:

Constant Field Values

REV_SPACE_LIMIT

public static final String REV_SPACE_LIMIT

The System property name for the Ceryle database revision space limit value. The value is "xnode-revision-space-limit".

See Also:

Constant Field Values

REV_SPACE_LIMIT_ACTION

public static final String REV_SPACE_LIMIT_ACTION

The System property name for the Ceryle database revision space limit action value. The value is "xnode-revision-space-limit-action".

See Also:

Constant Field Values

Constructor Detail

XNodeRevisionManagerImpl

public XNodeRevisionManagerImpl(XNodeStore xnodestore)
                         throws XNodeException

Constructor with a parent XNodeStore.

Parameters:

xnodestore - the parent XNodeStore.

Throws:

XNodeException - if unable to instantiate the manager for any reason.

Method Detail

getXNodeFromRevision

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

Currently unimplemented.

This is an XNodeRevisionManager API method.

Specified by:

getXNodeFromRevision in interface XNodeRevisionManager

Parameters:

xnode - the XNode to be queried.

version - the revision number.

createRevision

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

Generate a new XNodeRevision for the specified XNode, adding it to the XNode's repository. See createRevision(XNode) for more details.

This is an XNodeRevisionManager API method.

Specified by:

createRevision in interface XNodeRevisionManager

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

public 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 version number incremented), the XNodeRevision is added to the XNode's repository, but the changes are written back to the database only if write is true.

This is an XNodeRevisionManager API method.

Specified by:

createRevision in interface XNodeRevisionManager

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

public 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), the new XNodeRevision is added to the XNode's repository, but nothing is written to the backing Database (heck, we don't even know what collection it comes from, so we couldn't anyway). The new XNodeRevision is returned.

This is an XNodeRevisionManager API method.

Specified by:

createRevision in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process.

Returns:

the new XNodeRevision.

Throws:

XNodeException - if the process fails for any reason.

recreateRevision

public 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. Neither the parent XNode nor the database are modified.

This is an XNodeRevisionManager API method.

Specified by:

recreateRevision in interface XNodeRevisionManager

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

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

This is an XNodeRevisionManager API method.

Specified by:

restoreRevision in interface XNodeRevisionManager

Parameters:

revision - the XNodeRevision to restore.

Returns:

the version number of the new XNodeRevision

Throws:

XNodeException - if the restoration fails.

deleteRevision

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

This is an XNodeRevisionManager API method.

Specified by:

deleteRevision in interface XNodeRevisionManager

Parameters:

revision - the XNodeRevision to be deleted.

Returns:

true if the revision was removed.

Throws:

XNodeException - if the deletion fails for any reason.

deleteRevisions

public int deleteRevisions(List revisions)
                    throws XNodeException

Delete a 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.

This is an XNodeRevisionManager API method.

Specified by:

deleteRevisions in interface XNodeRevisionManager

Parameters:

revisions - the List of XNodeRevisions to be deleted.

Returns:

the count of successfully-deleted revisions

Throws:

XNodeException - if any of the deletions fail for any reason.

getRevisionCount

public int getRevisionCount(XNode xnode)
                     throws XNodeException

Return the count of available revisions for the provided XNode.

This is an XNodeRevisionManager API method.

Specified by:

getRevisionCount in interface XNodeRevisionManager

Parameters:

xnode - the parent XNode to process.

Throws:

XNodeException - if the process fails for any reason

getRevisionCountLimit

public int getRevisionCountLimit()

Returns the revision count limit (units: revision).

Specified by:

getRevisionCountLimit in interface XNodeRevisionManager

Returns:

the limit set, in count of revisions.

setRevisionCountLimit

public void setRevisionCountLimit(int limit)

Sets the revision count limit (units: revision) to limit. The value is ignored if less than zero.

Specified by:

setRevisionCountLimit in interface XNodeRevisionManager

Parameters:

limit - the limit set, in count of revisions.

exceedsRevisionCountLimit

public boolean exceedsRevisionCountLimit(XNode xnode)

Returns true if the provided XNode exceeds the set revision count limit. If an error occurs obtaining the total count of the XNode's revisions, sends an error to the message handler and returns false. This always returns false when count limits are inactive.

Specified by:

exceedsRevisionCountLimit in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process.

Returns:

true if the XNode exceeds the count limit.

useRevisionCountLimits

public static boolean useRevisionCountLimits()

Returns true if revision count limits are active.

Returns:

true if the revision count limits are active.

getRevisionCountLimitAction

public static int getRevisionCountLimitAction()

Returns the revision count limit action, the action that occurs when an XNode's revision count limit is exceeded. This will be one of the two permissable enumerated int values, XNodeRevisionManager.REV_LIMIT_ACTION_WARN or XNodeRevisionManager.REV_LIMIT_ACTION_DELETE

getRevisionSize

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

This is an XNodeRevisionManager API method.

Specified by:

getRevisionSize in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process.

version - the revision to process, or -1 to return a count of all revisions.

Returns:

the size of the specified revision, or 0 if it does not exist.

Throws:

XNodeException - if there is an error in processing.

getRevisionSpaceLimit

public int getRevisionSpaceLimit()

Returns the revision space limit (units: KB).

Specified by:

getRevisionSpaceLimit in interface XNodeRevisionManager

Returns:

the limit set, in KB.

setRevisionSpaceLimit

public void setRevisionSpaceLimit(int limit)

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

Specified by:

setRevisionSpaceLimit in interface XNodeRevisionManager

Parameters:

limit - the limit set, in KB.

exceedsRevisionSpaceLimit

public boolean exceedsRevisionSpaceLimit(XNode xnode)

Returns true if the provided XNode exceeds the set revision space limit. If an error occurs obtaining the total size of the XNode's revisions, sends an error to the message handler and returns false. This always returns false when space limits are inactive.

Specified by:

exceedsRevisionSpaceLimit in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process.

Returns:

true if the XNode exceeds the space limit.

useRevisionSpaceLimits

public static boolean useRevisionSpaceLimits()

Returns true if revision space limits are active.

Returns:

true if the revision space limits are active.

getRevisionSpaceLimitAction

public static int getRevisionSpaceLimitAction()

Returns the revision space limit action, the action that occurs when an XNode's revision space limit is exceeded. This will be one of the two permissable enumerated int values, XNodeRevisionManager.REV_LIMIT_ACTION_WARN or XNodeRevisionManager.REV_LIMIT_ACTION_DELETE

setProperties

public static void setProperties()
                          throws XNodeException

Called upon instantiation of the class, this method establishes the XNodeRevisionManager properties, based on System properties. Since all the properties are static, this method is static. And since there is no downside to it being public, it is public. It should be called when properties have been changed externally, such as by a preferences dialog.

Throws:

XNodeException

getRevisions

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

Returns a List containing the XNodeRevisions (specified by version number) of the provided XNode. This does not include the current document. Returns an empty List rather than a null if there are no matching revisions. If a specified revision is unavailable, no error * is generated.

Specified by:

getRevisions in interface XNodeRevisionManager

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

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

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

This is an XNodeRevisionManager API method.

Specified by:

getRevision in interface XNodeRevisionManager

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

public XNodeRevision getRevision(XNode xnode,
                                 int version)
                          throws XNodeException

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

Specified by:

getRevision in interface XNodeRevisionManager

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

public List getAllRevisions(XNode xnode)
                     throws XNodeException

Returns a List containing all XNodeRevisions of the provided XNode. This does not include the current document. Returns an empty List rather than a null if there are no revisions.

Specified by:

getAllRevisions in interface XNodeRevisionManager

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

public 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" if both fail.

Specified by:

getDisplayableRevisionDateOf in interface XNodeRevisionManager

Parameters:

revision - the XNodeRevision to be processed.

getRevisionsBefore

public 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, or if the supplied Date parameter is null (so that comparisons fail gracefully).

Specified by:

getRevisionsBefore in interface XNodeRevisionManager

Parameters:

xnode - the XNode to be processed.

date - the Date threshold.

Throws:

XNodeException

getProperty

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

Return the named property name of version version of XNode xnode as an Object, null if it has not been set. The returned value will be a String, a Date, or a DOM Node, depending on the property. If the version number supplied is -1, the current version will be used.

Specified by:

getProperty in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process

name - the name of the property

version - the revision number to process (use -1 for current)

Returns:

the value of the property (generally as a String or Date) or null if either the revision or the property does not exist.

Throws:

XNodeException - if there is a processing error.

getCurrentVersion

public static int getCurrentVersion(XNode xnode)

A static utility method that returns the version number of the provided XNode. This uses the DCMI DC.identifier.version property.

This is not an XNodeRevisionManager API method.

Returns:

the current version number, or "0" if unavailable.

getRepository

public List getRepository(XNode xnode)
                   throws XNodeException

Returns the List backing the XNode's repository (i.e., the List of individual XNodeRevision objects). This will return an empty List rather than null if there are no revisions. If the class being used for the list is a SetModel, this will also sort the list upon first instantiation.

This is not an XNodeRevisionManager API method.

Throws:

XNodeException

getRevisionIndex

public int[] getRevisionIndex(XNode xnode)
                       throws XNodeException

Return an ordered array of all revision numbers. The repository Element is optional; if not provided, it will be obtained from the XNode. Returns an empty array rather than null if no revisions are available.

This is not an XNodeRevisionManager API method.

Specified by:

getRevisionIndex in interface XNodeRevisionManager

Parameters:

xnode - the XNode to process.

Throws:

XNodeException

importRevision

public XNodeRevision importRevision(XNode xnode,
                                    XNode source)
                             throws XNodeException

Imports XNode source (ignoring any of that XNode's revisions) as a new revision of XNode xnode by copying the current document and metadata content of the source XNode to xnode's repository. Nothing is written to the backing Database.

This is not an XNodeRevisionManager API method.

Parameters:

xnode - the XNode to receive the new revision.

source - the XNode to import.

Returns:

the new XNodeRevision.

Throws:

XNodeException - if the process fails for any reason.

recreateRevision

public XNodeRevision recreateRevision(XNode xnode,
                                      Element revision)
                               throws XNodeException

Recreate an XNodeRevision provided the parent XNode and the source <xnode:Revision> Element. The recreated XNodeRevision is added to the parent XNode and its DOM is modified, but the backing Database is not modified.

This is not an XNodeRevisionManager API method.

Parameters:

xnode - the parent XNode to process.

revision - the source <xnode:Revision> Element.

Returns:

the recreated XNodeRevision.

Throws:

XNodeException - if the process fails for any reason.

setRevisionDateOf

public Date setRevisionDateOf(XNodeRevision revision)

Sets the revision date of the XNodeRevision based on the XNodeRevision's <xnode:Header> Element. This uses the creation date if the modified date is null. Returns null if unable to obtain a date from either created or modified dates (though that is theoretically impossible since XNodes always have their creation dates set).

This is not an XNodeRevisionManager API method.

convertTimeStamp

public Date convertTimeStamp(String timestamp)
                      throws XNodeException

Converts a String in timestamp format (such as the creation and modification date Strings, of the form "yyyy-MM-dd'T'HH:mm:ss") in UTC to a Date. A null or otherwise invalid timestamp will throw an XNodeException.

This is not an XNodeRevisionManager API method.

Parameters:

timestamp - the timestamp String to convert.

Throws:

XNodeException - if the timestamp is invalid.