com.jivesoftware.community
Interface DocumentManager

All Superinterfaces:

JiveManager

public interface DocumentManager
extends JiveManager

This manager provides methods to load documents and to retrieve popular documents. Once a handle on a document is obtained one can use the methods in the Document interface to retrieve document versions, comments, images and attachments.

See Also:

JiveContext, Document

Method Summary

Document	createDocument(User user, DocumentType documentType, java.lang.String documentID, java.lang.String title, java.lang.String body) Create a new document.
void	deleteDocument(Document document) Deletes a document.
Document	getDocument(Community community, java.lang.String subject) Returns a document from a community based on its subject.
Document	getDocument(long docID) Returns the document with the specified docID.
Document	getDocument(long docID, int version) Returns the revision of document with the specified docID and version number.
Document	getDocument(java.lang.String documentID) Returns a document from the community based on its document ID.
Document	getDocument(java.lang.String documentID, int version) Returns the revision of the document with the specified docID and version number.
JiveIterator<Document>	getDocumentsUnderEdit() Returns an Iterable of documents currently being editted.
int	getDocumentsUnderEditCount() Returns the count of the number of documents currently being editted.
int	getEditAutoExpireTimeout() Returns the number of minutes that a document will be marked as being editted without any updates before the document will be remarked as not being editted.
JiveIterator<Document>	getPopularDocuments() Returns the top x documents across all communities according to ratings, document views & time passed since the document was created.
JiveIterator<Document>	getPopularDocuments(java.util.List<java.lang.String> languages) Returns the top x documents across all communities according to ratings, document views & time passed since the document was created in the languages specified.
int	getUserApprovalDocumentCount(User user) Returns a count of all documents that a user needs to approve.
JiveIterator<Document>	getUserApprovalDocuments(User user) Returns all documents that a user needs to approve.
int	getUserDocumentCount(User user, DocumentState[] states) Returns a count of all documents in the supplied DocumentStates a user is an author of.
JiveIterator<Document>	getUserDocuments(User user, DocumentState[] states) Returns all documents in the supplied DocumentStates for the supplied user.
boolean	isCommentsEnabled() Returns true if the comments feature is turned on.
boolean	isTrackbacksEnabled() Returns true if the trackbacks feature is turned on.
void	moveDocument(Document document, Community destinationCommunity) Moves a document from it's current community to another.
void	setCommentsEnabled(boolean commentsEnabled) Enables or disables the comments feature system wide.
void	setEditAutoExpireTimeout(int minutes) Sets the number of minutes that a document will be marked as being editted without any updates before the document will be remarked as not being editted.
void	setTrackbacksEnabled(boolean trackbacksEnabled) Enables or disables the trackbacks feature system wide.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy, initialize

Method Detail

createDocument

Document createDocument(User user,
                        DocumentType documentType,
                        java.lang.String documentID,
                        java.lang.String title,
                        java.lang.String body)
                        throws DuplicateIDException

Create a new document. Newly created documents have a state of DocumentState.INCOMPLETE and must be attached to a community using the Community.addDocument(Document) method.

If a documentID is not provided (i.e. it's null) one will be automatically created. By default the autogenerated ID will be 'tempDOC-#' however the 'tempDOC-#' prefix can be controlled by changing the 'jive.temporaryDocPrefix' jive property.

Parameters:

user - the author of the new document

documentType - the document type of the new document

documentID - the document ID of the new document

title - the title of the new document

body - the body of the new document

Returns:

the new document

Throws:

DuplicateIDException - if the documentID provided is the same as an already existing document

getDocument

Document getDocument(long docID)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns the document with the specified docID. It's a good idea to only display the string version of ID's to users so most often this method will be used only internally to the API.

Parameters:

docID - the long doc ID of the document

Returns:

the document with the specified ID

Throws:

DocumentObjectNotFoundException - if no document with the specified ID can be found

UnauthorizedException - if the user doesn't have permissions to view the document.

getDocument

Document getDocument(long docID,
                     int version)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns the revision of document with the specified docID and version number. It's a good idea to only display the string version of ID's to users so most often this method will be used only internally to the API.

Parameters:

docID - the long doc ID of the document

version - the version number of the document

Returns:

the document with the specified ID

Throws:

DocumentObjectNotFoundException - if no document with the specified ID can be found

UnauthorizedException - if the user doesn't have permissions to view the document.

getDocument

Document getDocument(java.lang.String documentID)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns a document from the community based on its document ID.

Parameters:

documentID - the document ID of the document to retrieve.

Returns:

a Document object based on its document ID.

Throws:

DocumentObjectNotFoundException - if no document with the specified ID can be found

UnauthorizedException - if the user doesn't have permissions to view the document.

getDocument

Document getDocument(java.lang.String documentID,
                     int version)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns the revision of the document with the specified docID and version number.

Parameters:

documentID - the document ID of the document to retrieve.

version - the version number of the document.

Returns:

a Document object based on its document ID.

Throws:

DocumentObjectNotFoundException - if no document with the specified ID can be found

UnauthorizedException - if the user doesn't have permissions to view the document.

getDocument

Document getDocument(Community community,
                     java.lang.String subject)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns a document from a community based on its subject. Documents must have unique subjects within the published documents in a community.

Parameters:

community - the community to retrieve the document from.

subject - the subject of the document to retrieve.

Returns:

a Document object

Throws:

DocumentObjectNotFoundException - if no document matching the given criteria can be found

UnauthorizedException - if the user doesn't have permissions to view the document.

getPopularDocuments

JiveIterator<Document> getPopularDocuments()

Returns the top x documents across all communities according to ratings, document views & time passed since the document was created. The algorithm is as follows:

Top x of ((document views) * (document mean rating+2)) * 1/(1 + number of days since creation date)

The number of documents to return is determined by the property "popularDocuments.number", defaulting to 5 if the property is not specified. Popular documents are only calculated once every 15 minutes.

Returns:

an Iterable of the most popular documents.

getPopularDocuments

JiveIterator<Document> getPopularDocuments(java.util.List<java.lang.String> languages)

Returns the top x documents across all communities according to ratings, document views & time passed since the document was created in the languages specified. The algorithm is as follows:

Top x of ((document views) * (document mean rating+2)) * 1/(1 + number of days since creation date)

The number of documents to return is determined by the property "popularDocuments.number", defaulting to 5 if the property is not specified. Popular documents are only calculated once every 15 minutes.

Parameters:

languages - a list of ISO-639 language codes to restrict returned documents to.

Returns:

an Iterable of the most popular documents.

getUserApprovalDocuments

JiveIterator<Document> getUserApprovalDocuments(User user)

Returns all documents that a user needs to approve.

Parameters:

user - The user to acquire the documents for.

Returns:

The collection of documents the user needs to approve.

getUserApprovalDocumentCount

int getUserApprovalDocumentCount(User user)

Returns a count of all documents that a user needs to approve.

Parameters:

user - the user to return a count for

Returns:

a count of all documents that a user needs to approve.

getUserDocuments

JiveIterator<Document> getUserDocuments(User user,
                                        DocumentState[] states)

Returns all documents in the supplied DocumentStates for the supplied user.

Parameters:

user - the user to return documents for

states - the document states to filter on

Returns:

all documents in the supplied DocumentStates for the supplied user.

getUserDocumentCount

int getUserDocumentCount(User user,
                         DocumentState[] states)

Returns a count of all documents in the supplied DocumentStates a user is an author of.

Parameters:

user - the user to return a count for.

states - the document states to filter on

Returns:

a count of all documents in the supplied DocumentStates a user is an author of.

getDocumentsUnderEditCount

int getDocumentsUnderEditCount()

Returns the count of the number of documents currently being editted.

Returns:

the count of the number of documents currently being editted.

getDocumentsUnderEdit

JiveIterator<Document> getDocumentsUnderEdit()

Returns an Iterable of documents currently being editted.

Returns:

an Iterable of documents currently being editted.

moveDocument

void moveDocument(Document document,
                  Community destinationCommunity)
                  throws UnauthorizedException

Moves a document from it's current community to another.

Parameters:

document - the document to move.

destinationCommunity - the community to move the document to.

Throws:

UnauthorizedException - if user does not have administrator permissions for the document's current community.

deleteDocument

void deleteDocument(Document document)
                    throws UnauthorizedException

Deletes a document. Once a document is deleted, the document object should no longer be used. The search index and other resources that referenced the document and its comments will also be updated appropriately.

Note that since documents are versioned you may want to just delete or archive the specific version of the document instead of deleting the document which will delete all versions of the document. If this is the case see Document.getVersionManager()

Parameters:

document - the document to delete.

Throws:

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

isCommentsEnabled

boolean isCommentsEnabled()

Returns true if the comments feature is turned on. When comments are disabled on the system, all individual document comment settings are disabled as well.

Returns:

true if the comments are enabled

setCommentsEnabled

void setCommentsEnabled(boolean commentsEnabled)
                        throws UnauthorizedException

Enables or disables the comments feature system wide.

Parameters:

commentsEnabled - true to enable the comments feature, false to disable

Throws:

UnauthorizedException - if not a system administrator

isTrackbacksEnabled

boolean isTrackbacksEnabled()

Returns true if the trackbacks feature is turned on. When trackbacks are disabled on the system, all individual document trackback settings are disabled as well.

Returns:

true if the comments are enabled

setTrackbacksEnabled

void setTrackbacksEnabled(boolean trackbacksEnabled)
                          throws UnauthorizedException

Enables or disables the trackbacks feature system wide.

Parameters:

trackbacksEnabled - true to enable the trackback feature, false to disable

Throws:

UnauthorizedException - if not a system administrator

getEditAutoExpireTimeout

int getEditAutoExpireTimeout()

Returns the number of minutes that a document will be marked as being editted without any updates before the document will be remarked as not being editted. The default is 10 minutes.

Returns:

the edit autoexpire timeout in minutes

setEditAutoExpireTimeout

void setEditAutoExpireTimeout(int minutes)
                              throws UnauthorizedException

Sets the number of minutes that a document will be marked as being editted without any updates before the document will be remarked as not being editted.

Parameters:

minutes - the edit autoexpire timeout in minutes

Throws:

UnauthorizedException - if not authorized