com.jivesoftware.community
Interface VersionManager

public interface VersionManager

Manages document versions.

Method Summary

DocumentVersion	cloneDocumentVersion(int versionID) Creates a new document version based on an existing document version.
void	deleteDocumentVersion(int versionID) Delete a document version.
DocumentVersion	getDeletedDocumentVersion() Convenience method which returns the deleted document version.
DocumentVersion	getDocumentVersion(int versionID) Returns a specific document version for the document.
int	getDocumentVersionCount() Returns the count of versions the document has.
List<DocumentVersion>	getDocumentVersions() Returns a list of DocumentVersion objects for the document.
DocumentVersion	getNewestDocumentVersion() Convenience method which returns the newest document version as determined by version number.
DocumentVersion	getPublishedDocumentVersion() Convenience method which returns the published document version.
boolean	isVersionViewable(int versionID, User viewer) Returns true if the supplied User can view the version indicated by the supplied version number.
DocumentVersion	restoreDocumentVersion(int versionID, long versionAuthor) Restores a document version by creating a copy of the version to restore as the newest document version and returning that document version.

Method Detail

getDocumentVersionCount

int getDocumentVersionCount()

Returns the count of versions the document has.

Returns:

the count of versions the document has.

getDocumentVersions

List<DocumentVersion> getDocumentVersions()

Returns a list of DocumentVersion objects for the document. Versions will be returned from highest version to lowest version which normally will correspond to newest version to oldest version.

Returns:

a list of DocumentVersion objects for the document.

getDocumentVersion

DocumentVersion getDocumentVersion(int versionID)
                                   throws DocumentObjectNotFoundException

Returns a specific document version for the document. If the versionID passed in does not currespond to any version of the document a DocumentObjectNotFoundException will be thrown.

Parameters:

versionID - the version ID to return the document version for

Returns:

the document version for the provided ID

Throws:

DocumentObjectNotFoundException - if no version corresponding to the provided ID can be found

getNewestDocumentVersion

DocumentVersion getNewestDocumentVersion()

Convenience method which returns the newest document version as determined by version number.

Returns:

the newest document version as determined by version number.

getPublishedDocumentVersion

DocumentVersion getPublishedDocumentVersion()

Convenience method which returns the published document version. This method will return null if the document has not yet been published.

Returns:

the published document version or null if the document has not yet been published.

getDeletedDocumentVersion

DocumentVersion getDeletedDocumentVersion()

Convenience method which returns the deleted document version. This method will return null if the document has not yet been deleted.

Returns:

the deleted document version or null if the document has not yet been deleted.

restoreDocumentVersion

DocumentVersion restoreDocumentVersion(int versionID,
                                       long versionAuthor)
                                       throws DocumentObjectNotFoundException,
                                              DocumentAlreadyExistsException,
                                              UnauthorizedException

Restores a document version by creating a copy of the version to restore as the newest document version and returning that document version. Note that the versionID of the returned document version will not be the same as the versionID provided as a parameter to this method under the following circumstances:

• the versionID is not the newest version of the document
• the document version denoted by the versionID is not the current published version

Restoring a document version may cause a DocumentAlreadyExistsException to be thrown if the subject of the document is not unique among the published documents in the community the document is contained within.

Parameters:

versionID - the versionID of the document to restore

versionAuthor - the user id of the author of the newly created version.

Returns:

the newly restored document version.

Throws:

DocumentObjectNotFoundException - if no version corresponding to the provided ID can be found

DocumentAlreadyExistsException - if the subject of the document is not unique in the community

UnauthorizedException - if the user does not have permission to modify the document.

cloneDocumentVersion

DocumentVersion cloneDocumentVersion(int versionID)
                                     throws DocumentObjectNotFoundException,
                                            UnauthorizedException

Creates a new document version based on an existing document version. The new version's state will be DocumentState.INCOMPLETE.

Parameters:

versionID - the versionID of the document version to clone

Returns:

the newly cloned document version.

Throws:

DocumentObjectNotFoundException - if no version corresponding to the provided ID can be found

UnauthorizedException - if the user does not have permission to modify the document.

deleteDocumentVersion

void deleteDocumentVersion(int versionID)
                           throws DocumentObjectNotFoundException,
                                  UnauthorizedException

Delete a document version. Note that this method will fail with an IllegalArguementException if there is only a single version for a document.

Parameters:

versionID - the versionID of the document version to delete

Throws:

DocumentObjectNotFoundException - if no version corresponding to the provided ID can be found

UnauthorizedException - if the user does not have permission to modify the document.

isVersionViewable

boolean isVersionViewable(int versionID,
                          User viewer)
                          throws DocumentObjectNotFoundException

Returns true if the supplied User can view the version indicated by the supplied version number. This method takes into account document state and collaboration settings in determining whether or not a version is viewable. It does not take permissions into account.

Parameters:

versionID - the versionId to test.

viewer - the potential version viewer.

Returns:

true if the supplied User can view the version indicated by the supplied version number

Throws:

DocumentObjectNotFoundException - if no version corresponding to the provided ID can be found