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

void	addDocument(JiveContainer container, Document document, Map parameters) Add a document as a child of a container.
void	addDocument(JiveContainer container, Document document, com.jivesoftware.community.impl.PermissionsBundle permBundle, Map parameters) Add a document as a child of the container with permissions defined by the provided permission bundle.
void	addDocumentApprover(JiveContainer container, User user) Add the user as a document approver for this entire container.
Document	createDocument(User user, DocumentType documentType, String documentID, String title, Document body) Create a new document.
Document	createDocument(User user, DocumentType documentType, String documentID, String title, String body) Create a new document.
void	deleteDocument(Document document) Deletes a document.
void	deleteUserDocuments(User user) Deletes all user documents, including previous versions.
Document	getDocument(JiveContainer container, String subject) Returns a document from a container 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(String documentID) Returns a document from the container based on its document ID.
Document	getDocument(String documentID, int version) Returns the revision of the document with the specified docID and version number.
Collection<User>	getDocumentApprovers(JiveContainer container) Returns all of the users that must approve new documents before they reach a PUBLISHED state when it is in a PENDING_APPROVAL state.
int	getDocumentCount(JiveContainer container) Returns the number of published documents in the container.
int	getDocumentCount(JiveContainer container, DocumentResultFilter resultFilter) Returns the number of documents in the container {and possibly all child containers (if the container is a community)} based on the specified ResultFilter.
int	getDocumentCount(TagSet tagSet) Returns the number of published documents in the tag set.
int	getDocumentCount(TagSet tagSet, DocumentResultFilter filter) Returns the number of documents in the tag set based on the specified ResultFilter.
JiveIterator<Document>	getDocuments(JiveContainer container) Returns an Iterable for all the published documents in the container.
JiveIterator<Document>	getDocuments(JiveContainer container, DocumentResultFilter resultFilter) Returns an Iterable for all the documents in the container {and possibly all child containers (if the container is a community)} that match the criteria specified by the ResultFilter.
JiveIterator<Document>	getDocuments(TagSet tagSet) Returns an Iterable for all the published documents in the tag set.
JiveIterator<Document>	getDocuments(TagSet tagSet, DocumentResultFilter resultFilter) Returns an Iterable for all the documents in the tag set that match the criteria specified by the ResultFilter.
JiveIterator<Document>	getDocumentsUnderEdit() Returns an Iterable of documents currently being editted.
JiveIterator<Document>	getDocumentsUnderEdit(JiveContainer container) Returns the count of the number of documents currently being editted in the container.
int	getDocumentsUnderEditCount() Returns the count of the number of documents currently being editted.
int	getDocumentsUnderEditCount(JiveContainer container) Returns an Iterable of documents currently being editted in the container.
Document	getLatestDocument(JiveContainer container) Returns the most recently created or edited document in this container (including all sub-communities).
JiveIterator<Document>	getPopularDocuments() Returns the top x documents across all containers according to ratings, document views & time passed since the document was created.
JiveIterator<Document>	getPopularDocuments(JiveContainer c) Returns the top x documents across a given community & it's subcommunities according to ratings, document views & time passed since the document was created in the languages specified.
JiveIterator<Document>	getPopularDocuments(List<String> languages) Returns the top x documents across all containers 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, JiveContainer destinationContainer) Moves a document from it's current container to another.
void	removeDocumentApprover(JiveContainer container, User user) Remove this user as a document approver for this container.
void	setCommentsEnabled(boolean commentsEnabled) Enables or disables the comments feature system wide.
void	setTrackbacksEnabled(boolean trackbacksEnabled) Enables or disables the trackbacks feature system wide.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy

Method Detail

createDocument

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

Create a new document. Newly created documents have a state of DocumentState.INCOMPLETE and must be attached to a container using the addDocument(JiveContainer, Document,java.util.Map) 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

createDocument

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

Create a new document. Newly created documents have a state of DocumentState.INCOMPLETE and must be attached to a container using the addDocument(JiveContainer, Document,java.util.Map) 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.

Note that this method will return different versions of a document depending on the state(s) the document is in (and of course permissions). If the document has any deleted states this method will return that document version first. Otherwise if the document is published the published version will be returned. Finally, if neither of those are true the newest document version will be returned.

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(String documentID)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

Returns a document from the container 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(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(JiveContainer container,
                     String subject)
                     throws DocumentObjectNotFoundException,
                            UnauthorizedException

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

Parameters:

container - the container 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 containers 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(JiveContainer c)

Returns the top x documents across a given community & it's subcommunities 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:

c - container from which to fetch popular documents.

Returns:

an Iterable of the most popular documents in container c.

getPopularDocuments

JiveIterator<Document> getPopularDocuments(List<String> languages)

Returns the top x documents across all containers 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,
                  JiveContainer destinationContainer)
                  throws UnauthorizedException

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

Parameters:

document - the document to move.

destinationContainer - the container to move the document to.

Throws:

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

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

deleteUserDocuments

void deleteUserDocuments(User user)

Deletes all user documents, including previous versions. 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:

user - the author of the documents being deleted

Throws:

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

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

addDocument

void addDocument(JiveContainer container,
                 Document document,
                 Map parameters)
                 throws RejectedException,
                        DocumentAlreadyExistsException,
                        UnauthorizedException

Add a document as a child of a container. If the document already exists in this container, this method will do nothing. This method can possibly cause the documentID to change for the document - see Document.save() for more details.

Adding a document to a container may cause a DocumentAlreadyExistsException to be thrown if the subject of the document is not unique among the published documents in the container.

An UnauthorizedException will be thrown if the user is not a system administrator or does not have the proper permissions on either the document or the container.

Parameters:

container - The container to add a document.

document - the document to add into this container.

parameters -

Throws:

RejectedException - if one of the installed interceptors prevents the document from being added.

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

UnauthorizedException - if user does not have the proper permissions for the container.

addDocument

void addDocument(JiveContainer container,
                 Document document,
                 com.jivesoftware.community.impl.PermissionsBundle permBundle,
                 Map parameters)
                 throws RejectedException,
                        DocumentAlreadyExistsException,
                        UnauthorizedException

Add a document as a child of the container with permissions defined by the provided permission bundle. If the document already exists in this container, this method will do nothing. This method can possible cause the documentID to change for the document - see Document.save() for more details.

Adding a document to a container may cause a DocumentAlreadyExistsException to be thrown if the subject of the document is not unique among the published documents in the container.

An UnauthorizedException will be thrown if the user is not a system administrator or does not have the proper permissions on either the document or the container.

Parameters:

container - The container to add a document to.

document - the document to add into this container.

permBundle - the permissions to assign to the document

parameters -

Throws:

RejectedException - if one of the installed interceptors prevents the document from being added.

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

UnauthorizedException - if user does not have the proper permissions for the container.

getDocumentApprovers

Collection<User> getDocumentApprovers(JiveContainer container)

Returns all of the users that must approve new documents before they reach a PUBLISHED state when it is in a PENDING_APPROVAL state.

Parameters:

container - The container to get document approvers.

Returns:

All of the document approvers.

addDocumentApprover

void addDocumentApprover(JiveContainer container,
                         User user)
                         throws UnauthorizedException

Add the user as a document approver for this entire container.

This user will be required to approve all document edits for all documents in this container that have document approval enabled.

Parameters:

container - The container to a document approver for.

user - The user to add as a document approver.

Throws:

UnauthorizedException - if user does not have the proper permissions for the container.

removeDocumentApprover

void removeDocumentApprover(JiveContainer container,
                            User user)
                            throws UnauthorizedException

Remove this user as a document approver for this container.

Parameters:

container - The container to remove a document approver from.

user - The user to remove as a document approver.

Throws:

UnauthorizedException - if user does not have the proper permissions for the container.

getLatestDocument

Document getLatestDocument(JiveContainer container)

Returns the most recently created or edited document in this container (including all sub-communities). If there are no documents in the container , this method will return null. This information could also be determined using a DocumentResultFilter, but this method offers a simpler, more optimized way to access the data.

Parameters:

container - The container to get the last document for

Returns:

the most recently created or edited document in this container.

getDocumentCount

int getDocumentCount(JiveContainer container)

Returns the number of published documents in the container. To get the number of documents in this container and all child containers (if the container is a community), use the getDocumentCount(JiveContainer , DocumentResultFilter) with DocumentResultFilter}.setRecusive(true).

Parameters:

container - The container to find a document count for.

Returns:

the number of published documents in the container.

getDocumentCount

int getDocumentCount(TagSet tagSet)

Returns the number of published documents in the tag set.

Parameters:

tagSet - the TagSet to return the number of published documents for

Returns:

returns the number of published documents in the tag set.

getDocuments

JiveIterator<Document> getDocuments(JiveContainer container)

Returns an Iterable for all the published documents in the container. To get all the published documents in this container and all child containers (if the container is a community), use getDocuments(DocumentResultFilter resultFilter) with the DocumentResultFilter.setRecusive(true).

Parameters:

container - The documents for the container.

Returns:

an Iterable of published documents for all the documents in the container

getDocuments

JiveIterator<Document> getDocuments(TagSet tagSet)

Returns an Iterable for all the published documents in the tag set.

Parameters:

tagSet - The documents for the tag set.

Returns:

an Iterable of published documents for all the documents in the tag set

getDocumentCount

int getDocumentCount(JiveContainer container,
                     DocumentResultFilter resultFilter)

Returns the number of documents in the container {and possibly all child containers (if the container is a community)} based on the specified ResultFilter. This is useful for determining such things as the number of documents in a date range, etc.

Parameters:

container - The container find a document count for

resultFilter - a DocumentResultFilter to limit the query on.

Returns:

the number of Document objects in the container based on the filter.

getDocumentCount

int getDocumentCount(TagSet tagSet,
                     DocumentResultFilter filter)

Returns the number of documents in the tag set based on the specified ResultFilter. This is useful for determining such things as the number of documents in a date range, etc.

Parameters:

tagSet - the TagSet to return the document count for

filter - a DocumentResultFilter to limit the query on.

Returns:

the number of documents in the community based on the filter.

getDocuments

JiveIterator<Document> getDocuments(JiveContainer container,
                                    DocumentResultFilter resultFilter)

Returns an Iterable for all the documents in the container {and possibly all child containers (if the container is a community)} that match the criteria specified by the ResultFilter. Note that attempting to sort the documents on their container index will have strange results.

Parameters:

container - The container to retrieve documents from.

resultFilter - a DocumentResultFilter object to perform filtering and sorting with.

Returns:

an Iterable of Document objects for the documents in the container that match the ResultFilter.

getDocuments

JiveIterator<Document> getDocuments(TagSet tagSet,
                                    DocumentResultFilter resultFilter)

Returns an Iterable for all the documents in the tag set that match the criteria specified by the ResultFilter.

Parameters:

tagSet - the TagSet to retrieve documents for

resultFilter - a DocumentResultFilter object to perform filtering and sorting with.

Returns:

an Iterable of Document objects for the documents in the tag set that match the ResultFilter.

getDocumentsUnderEditCount

int getDocumentsUnderEditCount(JiveContainer container)

Returns an Iterable of documents currently being editted in the container.

Parameters:

container - The container to to get a count for.

Returns:

an Iterable of documents currently being editted in the container.

getDocumentsUnderEdit

JiveIterator<Document> getDocumentsUnderEdit(JiveContainer container)

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

Parameters:

container - The container to find the number of documents under edit for.

Returns:

the count of the number of documents currently being editted in the container.