com.jivesoftware.community
Interface Document

All Superinterfaces:

AttachmentContentResource, ImageContentResource, JiveContentObject, JiveObject

public interface Document
extends JiveContentObject, AttachmentContentResource, ImageContentResource

A Document object encapsulates a document in Clearspace. Each document can belong to one community and consists of document fields, attachments, images, comments, ratings, relationships and properties. The main content of a document is held within the document body(text or binary) and document fields.

The body of a Document object can either be textual or binary but not both. Having the body of a document be a binary object such as a pdf can be useful in a lot of situations especially if the document was created as part of an import process.

Not all aspects of a document is versioned. The only changes that will trigger a new version of a document to be created are changes to the follow: author, language, title, body (text or binary), document fields, attachments or images.

Changes to a Document object are not persisted to storage until save() is called.

To get an instance of this class use the DocumentManager.getDocument(String) method.

Field Summary

static int	AUTHORSHIP_MULTIPLE Constant defining authorship policy for this document.
static int	AUTHORSHIP_OPEN Constant defining authorship policy for this document.
static int	AUTHORSHIP_SINGLE Constant defining authorship policy for this document.
static boolean	TRACKBACKS_DEFAULT The default trackback status for a document.

Fields inherited from interface com.jivesoftware.community.JiveContentObject

BODY_FIELD, SUBJECT_FIELD

Method Summary

void	addApprover(User user) Adds a user as a document approver for this document.
void	addAuthor(User author) Adds the supplied User as an author of this document.
void	addReviewer(User reviewer) Adds the supplied User as a reviewer of this document.
void	approve(User user) Marks this document as being approved by the specified user.
java.io.InputStream	asPDF() Returns the contents of this document as a pdf.
void	deleteAllRatings() Deletes all ratings associated with this document.
java.util.Collection<ApprovalStatus>	getApprovalStatus() Returns a collection of ApprovalStatus objects.
int	getApproverCount() Returns a count of all of the users that must approve this document before it reaches a PUBLISHED state when it is in a PENDING_APPROVAL state.
JiveIterator<User>	getApprovers() Returns all of the users that must approve this document before it reaches a PUBLISHED state when it is in a PENDING_APPROVAL state.
com.jivesoftware.community.CommentDelegator	getAuthorCommentDelegator() Retrieve a comment manager to manage document author comments.
int	getAuthorCount() Returns the count of authors.
JiveIterator<User>	getAuthors() Returns the Users who are allowed to edit the document.
int	getAuthorshipPolicy() Returns the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.
BinaryBody	getBinaryBody() Returns the binary body of the document.
java.lang.String	getBody() Returns the textual body of the document.
com.jivesoftware.community.CommentDelegator	getCommentDelegator() Retrieve a comment manager to manage document comments.
int	getCommentStatus() Returns the comment status of this document which may be any one of the following: NONE -- no comments allowed OPEN -- comments are permitted CLOSED -- comments were permitted but are not allowed now Defaults to OPEN.
Community	getCommunity() Returns the community of the document.
java.util.Date	getCreationDate() A convenience method which returns the date the document was originally created.
DocumentAttributes	getDocumentAttributes() Return the attributes of the document.
DocumentFieldValue	getDocumentFieldValue(DocumentField field) Returns the value of the document field as a DocumentFieldValue object.
java.util.Map<java.lang.String,DocumentFieldValue>	getDocumentFieldValues() Returns a map of DocumentField -> DocumentFieldValue for the document.
java.lang.String	getDocumentID() Returns the document ID corresponding to the document.
DocumentState	getDocumentState() Return the state of the document.
DocumentType	getDocumentType() Return the type of the document.
DocumentVersion	getDocumentVersion() Returns a DocumentVersion object corresponding to the current instance.
java.lang.String	getEditGuest() Returns the sessionID for the guest user editing the document, or null if the document is not currently being edited by a guest user.
User	getEditUser() Returns the user editing the document, or null if the document is not currently being edited
java.util.Date	getExpirationDate() Returns the date that the document is set to expire on.
java.lang.String	getLanguage() Return the ISO-639 code of the language associated with the document, or null if the document has no language specified (thus implying that it uses the global default language).
java.util.Date	getModificationDate() A convenience method which returns the date the document was last modified as determined by the version with a DocumentState.PUBLISHED state, or if no version has that state the modification date of the current instance of the document.
Permissions	getPermissions(AuthToken auth) Returns the permissions for the document that correspond to the passed-in AuthToken.
PermissionsManager	getPermissionsManager() Returns a permissions manager that can be used to set permissions for the document.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Retrieve a map of all the extended properties for the document.
com.jivesoftware.community.RatingDelegator	getRatingDelegator() Retrieve a rating delegator to manage document ratings.
int	getReviewerCount() Returns the count of reviewers which have been added to this document.
JiveIterator<User>	getReviewers() Returns the Users who are intended to review the document.
java.lang.String	getSubject() Returns the subject of the document.
java.lang.String	getSummary() Returns the summary of the document.
com.jivesoftware.community.TagDelegator	getTagDelegator() Retrieve a tag delegator to manage document tags.
TrackbackManager	getTrackbackManager() Retrieve a trackback manager to manage document trackbacks.
DocumentFieldValue	getUnfilteredDocumentFieldValue(DocumentField field) Returns the value of the document field bypassing any active filters.
java.lang.String	getUnfilteredProperty(java.lang.String name) Returns an extended property of the document, bypassing any filters.
java.lang.String	getUnfilteredSummary() Returns the document summary, bypassing any active filters.
User	getUser() Returns the user that authored the document.
VersionManager	getVersionManager() Returns the version manager for the document.
int	getViewCount() Returns the number of times this document has been viewed.
boolean	hasApprovers() Returns true if this document or its parent community has approvers.
boolean	isAnonymous() Returns true if the document was created anonymously.
boolean	isAuthorized(long permissionType) Returns true if the handle on the document has the permission specified.
boolean	isDocumentBeingEdited() Returns true if the document is currently being editted by a user, false otherwise.
boolean	isInApproval() Returns true if the document currently is in approval.
boolean	isMinorEdit() If true, the next call to save() will result in a minor document version.
boolean	isTextBody() Returns true if the body of the document is text, false if it's binary.
boolean	isTrackbacksEnabled() Returns true if trackbacks are accepted on this blog post, false if not.
void	reject(User user) Marks this document as being rejected by the specified user.
void	removeApprover(User user) Removes the user as a document approver on this document.
void	removeAuthor(User author) Removes the supplied User as an author of this document.
void	removeReviewer(User reviewer) Removes the supplied User as a reviewer of this document.
void	save() Changes to a document are not persisted until this method is called.
void	setAuthorshipPolicy(int policy) Sets the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.
BinaryBody	setBinaryBody(java.lang.String name, java.lang.String contentType, java.io.InputStream data) Creates a new body object for the document.
void	setBody(java.lang.String body) Sets the textual body of the document.
void	setCommentStatus(int status) Sets the comment status of this document which may be any one of the following: NONE -- no comments allowed OPEN -- comments are permitted CLOSED -- comments were permitted but are not allowed now
void	setDocumentFieldValue(DocumentField field, DocumentFieldValue value) Sets the value of the document field.
void	setDocumentID(java.lang.String documentID) Sets the document ID corresponding to the document.
void	setDocumentState(DocumentState state) Sets the state of the document.
void	setExpirationDate(java.util.Date expirationDate) Sets the date the document should expire on.
void	setLanguage(java.lang.String language) Sets the language of the document.
void	setMinorEdit(boolean minorEdit) Set to true to cause the next call to save() to result in a minor document version.
void	setSubject(java.lang.String subject) Sets the subject of the document.
void	setSummary(java.lang.String summary) Sets the summary of the document.
void	setTrackbacksEnabled(boolean enable) Enables and disables trackbacks for this blog post.
void	setUser(User user) Returns the user that authored the document.
void	startEdit(java.lang.String sessionID) Sets the sessionID of the editing guest user for the document.
void	startEdit(User user) Sets the editing user for the document.
void	stopEdit(java.lang.String sessionID) Set the guest user with the given sessionID as no longer editing the document.
void	stopEdit(User user) Set the user as no longer editing the document.

Methods inherited from interface com.jivesoftware.community.JiveContentObject

getIndexContent, getPlainBody, getPlainSubject, getUnfilteredBody, getUnfilteredSubject

Methods inherited from interface com.jivesoftware.community.JiveObject

getID, getObjectType

Methods inherited from interface com.jivesoftware.community.AttachmentContentResource

createAttachment, deleteAttachment, getAttachment, getAttachmentCount, getAttachments

Methods inherited from interface com.jivesoftware.community.ImageContentResource

addImage, createImage, deleteImage, getImage, getImageCount, getImages

Field Detail

AUTHORSHIP_OPEN

static final int AUTHORSHIP_OPEN

Constant defining authorship policy for this document. AUTHORSHIP_OPEN indicates anyone with appropriate permissions can edit the document.

See Also:

Constant Field Values

AUTHORSHIP_SINGLE

static final int AUTHORSHIP_SINGLE

Constant defining authorship policy for this document. AUTHORSHIP_SINGLE indicates only the user returned by #getUser can edit the document.

See Also:

Constant Field Values

AUTHORSHIP_MULTIPLE

static final int AUTHORSHIP_MULTIPLE

Constant defining authorship policy for this document. AUTHORSHIP_MULTIPLE indicates only those users returned by #getAuthors can edit the document.

See Also:

Constant Field Values

TRACKBACKS_DEFAULT

static final boolean TRACKBACKS_DEFAULT

The default trackback status for a document.

See Also:

Constant Field Values

Method Detail

getDocumentID

java.lang.String getDocumentID()

Returns the document ID corresponding to the document.

A document ID is a way to reference a document using a company specific naming scheme such as ASE-2004-CE. Document ID's must be unique within the system.

Returns:

the document ID corresponding to the document, or null if the document hasn't been added to a community yet and no document ID has been specified.

setDocumentID

void setDocumentID(java.lang.String documentID)
                   throws UnauthorizedException,
                          DuplicateIDException

Sets the document ID corresponding to the document.

A document ID is a way to reference a document using a company specific naming scheme such as ASE-2004-CE. Document ID's must be unique within the system and are required - if no document ID is provided the system will generate one.

NOTE: It is not recommended to change the document ID for a document since this will likely break bookmarked URL's

Parameters:

documentID - the document ID to associate with the document.

Throws:

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

DuplicateIDException - if the documentID already exists in the system.

getDocumentType

DocumentType getDocumentType()

Return the type of the document. If no document type was specified when the document was created the default document type will be assigned.

Returns:

the document type associated with the document.

See Also:

DocumentType

getDocumentState

DocumentState getDocumentState()

Return the state of the document.

Returns:

the document state associated with the document.

See Also:

DocumentState

setDocumentState

void setDocumentState(DocumentState state)
                      throws UnauthorizedException,
                             DocumentAlreadyExistsException

Sets the state of the document. If no document state was specified when the document was created the default document state of DocumentState.PENDING_APPROVAL will be assigned. Setting a state of DocumentState.PUBLISHED and calling save() will cause any other version of the document in that state to be altered to have a state of DocumentState.ARCHIVED.

Setting a document state of DocumentState.PUBLISHED 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:

state - the new state of the document.

Throws:

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

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

getDocumentAttributes

DocumentAttributes getDocumentAttributes()

Return the attributes of the document.

Returns:

the attributes associated with the document.

See Also:

DocumentAttributes

getDocumentVersion

DocumentVersion getDocumentVersion()

Returns a DocumentVersion object corresponding to the current instance.

Returns:

a DocumentVersion object corresponding to the current instance.

getAuthorshipPolicy

int getAuthorshipPolicy()

Returns the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.

Returns:

the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.

setAuthorshipPolicy

void setAuthorshipPolicy(int policy)
                         throws UnauthorizedException

Sets the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.

Parameters:

policy - the authorship policy of this document, one of AUTHORSHIP_OPEN, AUTHORSHIP_SINGLE, or AUTHORSHIP_MULTIPLE.

Throws:

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

save

void save()
          throws UnauthorizedException

Changes to a document are not persisted until this method is called. If the save triggers a new version of the document to be created a call to getDocumentVersion() will return a different version object than one obtained prior to calling this method. Users of this api should call getDocumentVersion() after calling this method to determine if a new version of the document was created or not. In addition, if no documentID was specified when the document was created a new documentID will be assigned to the document replacing the temporary ID that was assigned when the document was created.

Note that calling save on a document will not automatically mark the document as no longer being editted by the user.

Throws:

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

java.lang.IllegalStateException - if the document state is DocumentState.PUBLISHED and not all of the required document fields have been set.

getLanguage

java.lang.String getLanguage()

Return the ISO-639 code of the language associated with the document, or null if the document has no language specified (thus implying that it uses the global default language).

Returns:

the ISO-639 code of the language associated with the document.

setLanguage

void setLanguage(java.lang.String language)
                 throws UnauthorizedException,
                        InvalidLanguageException

Sets the language of the document. If no language was specified when the document was created the global default language will be used.

Parameters:

language - the IS0-639 language code

Throws:

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

InvalidLanguageException - if the language code specified is not one of the language codes allowed by the system configuration.

isAnonymous

boolean isAnonymous()

Returns true if the document was created anonymously. This is a convenience method for: document.getUser() != null.

Returns:

true if the document was created anonymously.

getUser

User getUser()

Returns the user that authored the document. If the document was created anonymously, this method will return null.

Specified by:

getUser in interface JiveContentObject

Returns:

the author of the document.

setUser

void setUser(User user)
             throws UnauthorizedException

Returns the user that authored the document. If the document was created anonymously, this method will return null.

Parameters:

user - the user to change the ownership of the document to.

Throws:

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

getAuthorCount

int getAuthorCount()

Returns the count of authors. Returns zero if the AuthorshipPolicy is set to AUTHORSHIP_OPEN.

Returns:

the count of authors. Returns zero if the AuthorshipPolicy is set to AUTHORSHIP_OPEN.

getAuthors

JiveIterator<User> getAuthors()

Returns the Users who are allowed to edit the document. If the AuthorshipPolicy is set to AUTHORSHIP_OPEN, this method returns an empty iterator. If the AuthorshipPolicy is set to AUTHORSHIP_SINGLE, this method returns an iterator containing only the result of getUser(). If the AuthorshipPolicy is set to AUTHORSHIP_MULTIPLE, this method returns an iterator containing any users who have been added by addAuthor(com.jivesoftware.base.User), as well as the user returned by getUser().

Returns:

the Users who are allowed to edit the document.

addAuthor

void addAuthor(User author)
               throws UnauthorizedException

Adds the supplied User as an author of this document.

Parameters:

author - the User to add as an author.

Throws:

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

removeAuthor

void removeAuthor(User author)
                  throws UnauthorizedException

Removes the supplied User as an author of this document.

Parameters:

author - the User to remove as an author.

Throws:

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

getCreationDate

java.util.Date getCreationDate()

A convenience method which returns the date the document was originally created. To obtain the creation date of a particular version of a document use the DocumentVersion.getCreationDate() instead.

Specified by:

getCreationDate in interface JiveContentObject

Returns:

the date the document was originally created.

getModificationDate

java.util.Date getModificationDate()

A convenience method which returns the date the document was last modified as determined by the version with a DocumentState.PUBLISHED state, or if no version has that state the modification date of the current instance of the document.

When a document is first created, the date returned by this method is identical to the creation date.

Specified by:

getModificationDate in interface JiveContentObject

Returns:

the date the document was last modified.

getExpirationDate

java.util.Date getExpirationDate()

Returns the date that the document is set to expire on. This method will return null if the expiry date is not set.

Returns:

the date the document is set to expire.

setExpirationDate

void setExpirationDate(java.util.Date expirationDate)
                       throws UnauthorizedException

Sets the date the document should expire on. By default the date is not set.

Parameters:

expirationDate - the date the document should expire on.

Throws:

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

getSubject

java.lang.String getSubject()

Returns the subject of the document.

Specified by:

getSubject in interface JiveContentObject

Returns:

the subject of the document.

setSubject

void setSubject(java.lang.String subject)
                throws UnauthorizedException,
                       DocumentAlreadyExistsException

Sets the subject of the document. The subject of a document must be unique within the community the document is in. This requirement applies to both draft and published documents such that draft documents that have the subject set to be the same as an existing published document will have a DocumentAlreadyExistsException thrown however a published document that has the subject changed to be the same as a draft document will not have a DocumentAlreadyExistsException thrown.

Parameters:

subject - the subject of the document.

Throws:

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

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

getSummary

java.lang.String getSummary()

Returns the summary of the document.

Returns:

the summary of the document.

getUnfilteredSummary

java.lang.String getUnfilteredSummary()

Returns the document summary, bypassing any active filters. Because filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving document content to another persistence mechanism such as an XML format.

Returns:

the unfiltered summary of the document.

setSummary

void setSummary(java.lang.String summary)
                throws UnauthorizedException

Sets the summary of the document.

Parameters:

summary - the summary of the document.

Throws:

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

isTextBody

boolean isTextBody()

Returns true if the body of the document is text, false if it's binary.

Returns:

true if the body of the document is text, false if it's binary.

getBody

java.lang.String getBody()

Returns the textual body of the document. If the document has a binary body this method will return null.

Specified by:

getBody in interface JiveContentObject

Returns:

the textual body of the document if it exists, or null otherwise.

setBody

void setBody(java.lang.String body)
             throws UnauthorizedException

Sets the textual body of the document. If a binary body had previously been set it will be deleted.

Parameters:

body - the textual body of the document.

Throws:

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

getBinaryBody

BinaryBody getBinaryBody()

Returns the binary body of the document. If the document has a textual body this method will return null.

Returns:

the binary body of the document if it exists, or null otherwise.

setBinaryBody

BinaryBody setBinaryBody(java.lang.String name,
                         java.lang.String contentType,
                         java.io.InputStream data)
                         throws java.lang.IllegalStateException,
                                BinaryBodyException,
                                UnauthorizedException

Creates a new body object for the document. The body object has a name, content type and binary data. Rules about what kind of body objects are allowed is controlled via a BinaryBodyManager.

Parameters:

name - the name of the new body object, usually the file name.

contentType - the content type of the body object.

data - an InputStream that contains the binary data of the body object. The stream will never be closed so you must close it manually after calling this method.

Returns:

a BinaryBody object representing the new body object created.

Throws:

BinaryBodyException - if an error occurred while creating the body object.

UnauthorizedException - if not allowed to modify the document.

java.lang.IllegalStateException - if the document hasn't yet been added to a community.

See Also:

BinaryBody, BinaryBodyManager

getDocumentFieldValues

java.util.Map<java.lang.String,DocumentFieldValue> getDocumentFieldValues()

Returns a map of DocumentField -> DocumentFieldValue for the document.

Returns:

a map of DocumentField -> DocumentFieldValue for the document.

getDocumentFieldValue

DocumentFieldValue getDocumentFieldValue(DocumentField field)

Returns the value of the document field as a DocumentFieldValue object.

Parameters:

field - the document field to return the value for

Returns:

a DocumentFieldValue object corresponding to the value of the passed in field.

Throws:

java.lang.IllegalArgumentException - if the field doesn't exist in the document type associated with the document.

getUnfilteredDocumentFieldValue

DocumentFieldValue getUnfilteredDocumentFieldValue(DocumentField field)

Returns the value of the document field bypassing any active filters.

Since filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving document content to another persistence mechanism such as an XML format.

Parameters:

field - the document field to return the unfiltered value for

Returns:

a unfiltered DocumentFieldValue object corresponding to the value of the passed in field

Throws:

java.lang.IllegalArgumentException - if the field doesn't exist in the document type associated with the document.

setDocumentFieldValue

void setDocumentFieldValue(DocumentField field,
                           DocumentFieldValue value)
                           throws UnauthorizedException

Sets the value of the document field. If the document field has a type of DocumentFieldType.DataType.LIST_MULTI there may be more than one option in the value parameter, otherwise only a single option or text value may be provided.

Parameters:

field - the document field to set the value for.

value - a DocumentFieldValue object corresponding to the value of the field

Throws:

UnauthorizedException - if the user does not have create permissions.

java.lang.IllegalArgumentException - if the field doesn't exist in the document type associated with the document.

getCommunity

Community getCommunity()

Returns the community of the document.

Returns:

the community of the document.

getCommentStatus

int getCommentStatus()

Returns the comment status of this document which may be any one of the following:

• NONE -- no comments allowed
• OPEN -- comments are permitted
• CLOSED -- comments were permitted but are not allowed now

Defaults to OPEN.

Returns:

status the comment status of this document

setCommentStatus

void setCommentStatus(int status)
                      throws UnauthorizedException

Sets the comment status of this document which may be any one of the following:

• NONE -- no comments allowed
• OPEN -- comments are permitted
• CLOSED -- comments were permitted but are not allowed now

Parameters:

status - the comment status of this document

Throws:

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

getCommentDelegator

com.jivesoftware.community.CommentDelegator getCommentDelegator()

Retrieve a comment manager to manage document comments. Attempting to retrieve a comment manager prior to the document being saved will result in an IllegalStateArgument being thrown.

Returns:

a comment delegator to manage document comments.

getAuthorCommentDelegator

com.jivesoftware.community.CommentDelegator getAuthorCommentDelegator()
                                                                      throws UnauthorizedException

Retrieve a comment manager to manage document author comments. This is a separate tree of comments intended to allow threaded discussion between authors of a document. Attempting to retrieve a comment manager prior to the document being saved will result in an IllegalStateArgument being thrown.

Returns:

a comment delegator to manage document author comments.

Throws:

UnauthorizedException - if the user isn't allowed to edit the document and the user ins't an approver

isTrackbacksEnabled

boolean isTrackbacksEnabled()

Returns true if trackbacks are accepted on this blog post, false if not. Default is true.

Returns:

true if trackbacks are accepted on this blog post, false if not.

setTrackbacksEnabled

void setTrackbacksEnabled(boolean enable)
                          throws UnauthorizedException

Enables and disables trackbacks for this blog post. Default is true.

Parameters:

enable - true to enable trackbacks, false to disable trackbacks

Throws:

UnauthorizedException - if the user isn't allwed to edit the document

getTrackbackManager

TrackbackManager getTrackbackManager()

Retrieve a trackback manager to manage document trackbacks. Attempting to retrieve a trackback manager prior to the document being saved will result in an IllegalStateException being thrown.

Returns:

a trackback manager to manage document trackbacks.

getTagDelegator

com.jivesoftware.community.TagDelegator getTagDelegator()

Retrieve a tag delegator to manage document tags. Attempting to retrieve a tag delegator prior to the document being saved will result in an IllegalStateArgument being thrown.

Returns:

a tag delegator to manage document tags.

getRatingDelegator

com.jivesoftware.community.RatingDelegator getRatingDelegator()

Retrieve a rating delegator to manage document ratings. Attempting to retrieve a rating delegator prior to the document being saved will result in an IllegalStateArgument being thrown.

Returns:

a rating delegator to manage document ratings.

getViewCount

int getViewCount()

Returns the number of times this document has been viewed. A return value of -1 indicates the number of views is unknown or that the feature is disabled.

Returns:

the number of times this document has been viewed or -1 if the value is not known.

getPermissionsManager

PermissionsManager getPermissionsManager()
                                         throws UnauthorizedException

Returns a permissions manager that can be used to set permissions for the document. Only admins can perform this function.

Returns:

a PermissionsManager to manage the permissions on the document.

Throws:

UnauthorizedException - if user does not have administrator permissions for the document.

getVersionManager

VersionManager getVersionManager()

Returns the version manager for the document.

Returns:

the version manager for the document.

getPermissions

Permissions getPermissions(AuthToken auth)

Returns the permissions for the document that correspond to the passed-in AuthToken. This method is not generally useful to skin writers. Instead, the isAuthorized(int) method should be used for permission checking.

Parameters:

auth - the auth token to lookup permissions for.

Returns:

the permissions for the document that correspond to the passed-in AuthToken.

isAuthorized

boolean isAuthorized(long permissionType)

Returns true if the handle on the document has the permission specified. For example, if a community administrator has a handle on the document, then calling isAuthorized(Permissions.COMMUNITY_ADMIN) would return true.

A list of possible permissions can be found in the Permissions and the Permissions classes. Certain methods of this class are restricted to certain permissions as specified in the method comments.

Parameters:

permissionType - a permission type from the Permissions class.

Returns:

true if the handle on the object has the specified permission.

See Also:

Permissions, Permissions

getProperties

java.util.Map<java.lang.String,java.lang.String> getProperties()

Retrieve a map of all the extended properties for the document. Each document can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface. The map is alterable if the user is authorized to modify the document. Null keys and values are not allowed.

Values returned from the map are filtered through the filter system. To retrieve unfiltered property values use the getUnfilteredProperty(String) method.

If the user is not authorized to modify the document any method which modifies the map will fail with a UnsupportedOperationException;

Returns:

a map of document extended properties.

getUnfilteredProperty

java.lang.String getUnfilteredProperty(java.lang.String name)

Returns an extended property of the document, bypassing any filters. Each document can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface.

Because properties are not filtered before being returned, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Parameters:

name - the name of the property to get.

Returns:

the value of the property.

deleteAllRatings

void deleteAllRatings()
                      throws UnauthorizedException

Deletes all ratings associated with this document.

Throws:

UnauthorizedException - if the user isn't an admin

getReviewerCount

int getReviewerCount()

Returns the count of reviewers which have been added to this document.

Returns:

the count of authors which have been added to this document.

getReviewers

JiveIterator<User> getReviewers()

Returns the Users who are intended to review the document.

Returns:

the Users who are intended to review the document.

addReviewer

void addReviewer(User reviewer)
                 throws UnauthorizedException

Adds the supplied User as a reviewer of this document.

Parameters:

reviewer - the User to add as a reviewer.

Throws:

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

removeReviewer

void removeReviewer(User reviewer)
                    throws UnauthorizedException

Removes the supplied User as a reviewer of this document.

Parameters:

reviewer - the User to remove as a reviewer.

Throws:

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

getApproverCount

int getApproverCount()

Returns a count of all of the users that must approve this document before it reaches a PUBLISHED state when it is in a PENDING_APPROVAL state. Does not include approvers set at the community level.

Returns:

All of the document approvers.

getApprovers

JiveIterator<User> getApprovers()

Returns all of the users that must approve this document before it reaches a PUBLISHED state when it is in a PENDING_APPROVAL state. Does not include approvers set at the community level.

Returns:

All of the document approvers.

addApprover

void addApprover(User user)
                 throws UnauthorizedException

Adds a user as a document approver for this document. If document approval is enabled for this document this user will have to approve(com.jivesoftware.base.User) this document to before it will be changed to a PUBLISHED status when it is edited.

Parameters:

user - The user to add as a document approver

Throws:

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

removeApprover

void removeApprover(User user)
                    throws UnauthorizedException

Removes the user as a document approver on this document.

Parameters:

user - The user to remove as a document approver.

Throws:

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

approve

void approve(User user)
             throws UnauthorizedException

Marks this document as being approved by the specified user.

If this document is not under document approval or this user is not a document approver, this method call will be ignored.

Parameters:

user - User to approve the document.

Throws:

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

reject

void reject(User user)
            throws UnauthorizedException

Marks this document as being rejected by the specified user.

If this document is not under document approval or this user is not a document approver, this method call will be ignored.

Parameters:

user - User to reject the document.

Throws:

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

getApprovalStatus

java.util.Collection<ApprovalStatus> getApprovalStatus()

Returns a collection of ApprovalStatus objects. The ApprovalStatus objects show which user has approved the Document and which hasn't.

Returns:

A collection of ApprovalStatus documents.

See Also:

ApprovalStatus

hasApprovers

boolean hasApprovers()

Returns true if this document or its parent community has approvers.

Returns:

true if this document or its parent community has approvers.

isInApproval

boolean isInApproval()

Returns true if the document currently is in approval.

Returns:

true if the document currently is in approval

isDocumentBeingEdited

boolean isDocumentBeingEdited()

Returns true if the document is currently being editted by a user, false otherwise.

Returns:

true if the document is currently being editted, false otherwise.

getEditUser

User getEditUser()

Returns the user editing the document, or null if the document is not currently being edited

Returns:

the user editing the document, or null if the document is not currently being edited or the document is being editted by a guest.

getEditGuest

java.lang.String getEditGuest()

Returns the sessionID for the guest user editing the document, or null if the document is not currently being edited by a guest user.

Returns:

the sessionID for the guest user editing the document, or null if the document is not currently being edited or the document is being edited by a guest user

startEdit

void startEdit(User user)
               throws UnauthorizedException,
                      java.lang.IllegalStateException

Sets the editing user for the document. This method should be called repeatedly on a timer every minute or so while the user is editing the document so that the editing user doesn't autoexpire.

Parameters:

user - the editing user

Throws:

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

java.lang.IllegalStateException - if another user (guest or otherwise) is currently editing the document

See Also:

DocumentManager.getEditAutoExpireTimeout()

startEdit

void startEdit(java.lang.String sessionID)
               throws UnauthorizedException,
                      java.lang.IllegalStateException

Sets the sessionID of the editing guest user for the document. This method should be called repeatedly on a timer every minute or so while the guest is editing the document so that the editing guest user doesn't autoexpire.

The sessionID can be any unique string for a guest user. From a web application using this api the sessionID can be easily retrieved from the request.getSession().getId() method call.

Parameters:

sessionID - the sessionID of the editing guest user

Throws:

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

java.lang.IllegalStateException - if another user (guest or otherwise) is currently editing the document

See Also:

DocumentManager.getEditAutoExpireTimeout()

stopEdit

void stopEdit(User user)
              throws UnauthorizedException

Set the user as no longer editing the document.

Parameters:

user - the editing user

Throws:

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

stopEdit

void stopEdit(java.lang.String sessionID)
              throws UnauthorizedException

Set the guest user with the given sessionID as no longer editing the document.

Parameters:

sessionID - the sessionID of the editing guest user

Throws:

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

setMinorEdit

void setMinorEdit(boolean minorEdit)

Set to true to cause the next call to save() to result in a minor document version. No notifications will be sent to users watching the document.

Parameters:

minorEdit - true to cause the next call to save() to result in a minor document version.

isMinorEdit

boolean isMinorEdit()

If true, the next call to save() will result in a minor document version. No notifications will be sent to users watching the document.

Returns:

whether the current unsaved changes constitute a minor edit.

asPDF

java.io.InputStream asPDF()
                          throws javax.xml.transform.TransformerException,
                                 org.xml.sax.SAXException

Returns the contents of this document as a pdf.

Returns:

the contents of this document as a pdf.

Throws:

javax.xml.transform.TransformerException - if an error occurs transforming the document

org.xml.sax.SAXException - if an error occurs parsing the document