com.plumtree.remote.prc.collaboration.document
Interface IDocumentManager

public interface IDocumentManager

Interface for managing IDocument and IDocumentFolder functionality. It handles creation, copying, removal and querying for documents and document folders.

See Document Examples.

Method Summary

void	checkInDocument(IDocument document, java.lang.String checkInComment, java.io.InputStream inStream, java.lang.String language, boolean keepCheckedOut) Checks in a new version of a document that is currently in the checked-out state.
void	checkOutDocument(IDocument document) Puts the document into the checked-out state.
void	copyToFolder(IDocumentFolder sourceParentFolder, IDocumentFolder targetFolder, IDocument[] documentsToCopy, IDocumentFolder[] foldersToCopy, boolean inheritSecurity, java.lang.String documentHistoryComment) Copies documents and folders from a source parent folder to a target folder.
IDocumentFilter	createDocumentFilter() Creates an IDocumentFilter for querying documents.
IDocumentFolderFilter	createDocumentFolderFilter() Creates an IDocumentFolderfilter for querying documents.
IDocument	createNewDocument(java.lang.String name, java.lang.String description) Returns a new IDocument instance.
IDocumentFolder	createNewFolder(java.lang.String name, java.lang.String description) Creates and returns a new IDocumentFolder instance.
IDocument	getDocument(int documentID) Returns an IDocument with the specified ID, or null if there is no document with the given ID.
IDocumentFolder	getDocumentFolder(int folderID) Returns an IDocumentFolder for the specified ID, or null if there is no document folder with the given ID.
int[]	getSubscribedUserIDs(IDocument document) Returns the IDs of the users who are subscribed to the given document.
int[]	getSubscribedUserIDs(IDocumentFolder documentFolder) Returns the IDs of the users who are subscribed to the given document folder.
IDocumentFolder	getTopLevelFolder(IProject project) Returns the top level folder for the given project.
IDocument	insertNewDocument(IDocumentFolder parentFolder, IDocument documentProperties, java.lang.String checkInComment, java.io.InputStream inStream, java.lang.String language, boolean inheritSecurity) Inserts a new document into the given parent document folder.
IDocumentFolder	insertNewFolder(IDocumentFolder parentFolder, IDocumentFolder newFolder, boolean inheritSecurity) Inserts a new document folder into the given document folder.
IDocument[]	queryDocuments(IDocumentFolder documentFolder, IDocumentFilter documentFilter) Queries for documents contained in the specified document folder, and returns an array of IDocuments that satisfies the query filter.
IDocument[]	queryDocuments(IProject project, IDocumentFilter documentFilter) Queries for documents contained in the specified project, and returns an array of IDocuments that satisfies the query filter.
IDocumentFolder[]	queryFolders(IDocumentFolder folder, IDocumentFolderFilter queryfilter) Queries for document folders contained in the specified document folder, and returns an array of IDocumentFolders that satisfies the query filter.
void	removeDocument(IDocument document) Deletes the document.
void	removeDocumentFolder(IDocumentFolder folder) Deletes the folder.
void	subscribeUsers(IDocumentFolder documentFolder, int[] userIDs) Subscribe users of the given IDs to the given document folder and all documents in that folder.
void	subscribeUsers(IDocument document, int[] userIDs) Subscribe users of the given IDs to the given document.
void	undoDocumentCheckout(IDocument document) Puts a document that is currently in the checked-out state into the non-checked-out state.
void	unsubscribeUsers(IDocumentFolder documentFolder, int[] userIDs) Unsubscribe users of the given IDs from a document folder, including all documents in the folder.
void	unsubscribeUsers(IDocument document, int[] userIDs) Unsubscribe users of the given IDs from a document.

Method Detail

checkInDocument

public void checkInDocument(IDocument document,
                            java.lang.String checkInComment,
                            java.io.InputStream inStream,
                            java.lang.String language,
                            boolean keepCheckedOut)
                     throws PermissionDeniedException,
                            CollaborationException,
                            java.rmi.RemoteException

Checks in a new version of a document that is currently in the checked-out state. This includes saving a new version of the document, incrementing the current version number and making a new entry in the document's history.

 //The following sample code demonstrates how to check in a new document version.
 //Open an inputstream for the document contents - this can be any InputStream
 InputStream fileInputStream = new FileInputStream("c:\\myNewDocument.doc");
 //Check in the new version
 documentManager.checkInDocument(checkedOutDocument, "this is an updated version of the document", fileInputStream, "en", false);
 

Parameters:

document - the document that is being checked in. Cannot be null.

checkInComment - a string containing a comment that will be inserted into the document history as a check-in comment of the new version. Cannot be null.

inStream - an InputStream from which the contents of the new version of the document will be read. Cannot be null.

language - the document content language. This is the ISO 639-1 language code, i.e. en for english. Specifying a null language will set the language to that of the current user.

keepCheckedOut - if set to true then this operation will check-in and (atomically) subsequently check-out the document. The document will finish in the checked-out state.

Throws:

PermissionDeniedException - if the user does not have permission to check-in the document, or the user does not currently have the document checked-out.

CollaborationException - if the method call resulted in an error or the the user does not have access to the document.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the document is not checked-out, has not yet been inserted or has already been removed.

checkOutDocument

public void checkOutDocument(IDocument document)
                      throws PermissionDeniedException,
                             CollaborationException,
                             java.rmi.RemoteException

Puts the document into the checked-out state. Only one user can check out a document at a time.

Parameters:

document - the document to be checked out. Cannot be null.

Throws:

PermissionDeniedException - if the user does not have permission to check-out the document, or the document is already checked out by another user.

CollaborationException - if the method call resulted in an error or the user does not have access to the document.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the document has not yet been inserted or has already been removed.

copyToFolder

public void copyToFolder(IDocumentFolder sourceParentFolder,
                         IDocumentFolder targetFolder,
                         IDocument[] documentsToCopy,
                         IDocumentFolder[] foldersToCopy,
                         boolean inheritSecurity,
                         java.lang.String documentHistoryComment)
                  throws CollaborationException,
                         java.rmi.RemoteException,
                         MultipleObjectException

Copies documents and folders from a source parent folder to a target folder. The operation is recursive in that the entire document tree below each of the given folders to be copied will also be copied. If any name collisions occur, the name of the copied object will be modified to make it unique. This method will make a best-attempt to finish the copy operation. If an error occurs while copying one of the documents or folders, the copying will continue, and a MultipleException will be thrown specifying the objects which caused failures.

Parameters:

sourceParentFolder - the source parent document folder to copy from. Each of the source objects must be from this parent folder. Cannot be null.

targetFolder - the target folder. This folder may be in a different project from the source objects. Cannot be null.

documentsToCopy - the documents to copy. Each of the documents must be from the sourceParentFolder and the user must have permission to copy each document. Cannot be null.

foldersToCopy - the document folders to copy. Each of the folders must be from the sourceParentFolder and the user must have permission to copy each folder. All objects in these folders will be copied recursively. Cannot be null.

inheritSecurity - a boolean value indicating how the access level of each objects should be set. If this parameter is true the copied objects will inherit security from the targetFolder. If this parameter is false the copied objects will be given the same access level as the source objects. If the target folder is in a different project from the source objects, then security is mapped isomorphically from the source project to the target project. Thus if the ProjectMember role in the source project has access level i on object O and object O is copied to object O', then the ProjectMember role in the target project will have access level i on object O'. Similarly with the ProjectGuest role.

documentHistoryComment - a string that will be used as the initial comment in the document history of each of the copied documents. Cannot be null.

Throws:

CollaborationException - if the method call resulted in an error or the user does not have access to the folder.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if any of the objects have not yet been stored or have already been removed.

MultipleObjectException - if errors occurred while copying. Each source exception can be retrieved from this exception.

createDocumentFilter

public IDocumentFilter createDocumentFilter()

Creates an IDocumentFilter for querying documents. The filter will initially be set to return all documents, unordered.

Returns:

the document filter.

createDocumentFolderFilter

public IDocumentFolderFilter createDocumentFolderFilter()

Creates an IDocumentFolderfilter for querying documents. The filter will initially be set to return all document folders, unordered.

Returns:

the document folder filter.

createNewDocument

public IDocument createNewDocument(java.lang.String name,
                                   java.lang.String description)

Returns a new IDocument instance. After setting some of the fields on the newly created object, the method insertNewDocument needs to be called to persist the newly created document.

 //The following sample code demonstrates how to create and store a new document.
 //Create the document
 IDocument newDocument = documentManager.createNewDocument("my new document", "this is a test document");
 //Set optional properties
 newDocument.setAuthor("joe bloggs");
 //Set content-type
 newDocument.setContentType("text/vnd.ms-word");
 //Open an inputstream for the document contents
 InputStream fileInputStream = new FileInputStream("c:\\report.doc");
 //Insert the document, inheriting the containing folder's security
 documentManager.insertNewDocument(containingFolder, newDocument, "initial check-in", fileInputStream, "en", true);
 

Parameters:

name - the name of the document. Cannot be null.

description - the description of the document. Cannot be null.

Returns:

a new IDocument instance.

createNewFolder

public IDocumentFolder createNewFolder(java.lang.String name,
                                       java.lang.String description)

Creates and returns a new IDocumentFolder instance. After setting some of the fields on the newly created object, the method insertNewFolder needs to be called to persist the newly created document folder.

 //The following sample code demonstrates how to create and store a new document folder.
 //Create the folder
 IDocumentFolder newFolder = documentManager.createNewFolder("my new folder", "this is a test folder");
 //Could now set optional properties such as security on newFolder before store...
 //Get the top level folder of the project to insert the document into
 IDocumentFolder topLevelFolder = documentManager.getTopLevelFolder(containingProject);
 //Insert the folder, inheriting the top level folder's security
 IDocumentFolder storedFolder = documentManager.insertNewFolder(topLevelFolder, newFolder, true);
 

Parameters:

name - the name of the document folder.

description - the description of the document folder.

Returns:

a new IDocumentFolder instance.

getDocument

public IDocument getDocument(int documentID)
                      throws CollaborationException,
                             java.rmi.RemoteException

Returns an IDocument with the specified ID, or null if there is no document with the given ID.

Parameters:

documentID - the document ID. The ID of a document can be obtained using the getID method on the IDocument interface. Must be positive.

Returns:

an IDocument with the specified ID or null if the document does not exist or the user does not have access to it.

Throws:

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

getDocumentFolder

public IDocumentFolder getDocumentFolder(int folderID)
                                  throws CollaborationException,
                                         java.rmi.RemoteException

Returns an IDocumentFolder for the specified ID, or null if there is no document folder with the given ID.

Parameters:

folderID - the document folder ID. The ID of a document folder can be obtained using the getID method on the IDocumentFolder interface. Must be positive.

Returns:

an IDocumentFolder with the specified ID or null if the document folder does not exist or the user does not have access to it.

Throws:

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

getSubscribedUserIDs

public int[] getSubscribedUserIDs(IDocumentFolder documentFolder)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns the IDs of the users who are subscribed to the given document folder.

Parameters:

documentFolder - the document folder. Cannot be null.

Returns:

the IDs of the users who are subscribed to the document folder.

Throws:

java.lang.IllegalStateException - if the folder has not yet been inserted or has already been removed.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

CollaborationException - if any of the users specified cannot be subscribed.

getSubscribedUserIDs

public int[] getSubscribedUserIDs(IDocument document)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns the IDs of the users who are subscribed to the given document.

Parameters:

document - the document. Cannot be null.

Returns:

the IDs of the users who are subscribed to the document.

Throws:

java.lang.IllegalStateException - if the document has not yet been inserted or has already been removed.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

CollaborationException - if any of the users specified cannot be subscribed.

getTopLevelFolder

public IDocumentFolder getTopLevelFolder(IProject project)
                                  throws CollaborationException,
                                         java.rmi.RemoteException

Returns the top level folder for the given project.

Parameters:

project - the project whose top-level folder is being requested. Cannot be null.

Returns:

an IDocumentFolder for the top-level folder in the given project or null if the user does not have access to the folder.

Throws:

java.lang.IllegalStateException - if the project has not yet been stored or has already been removed.

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

insertNewDocument

public IDocument insertNewDocument(IDocumentFolder parentFolder,
                                   IDocument documentProperties,
                                   java.lang.String checkInComment,
                                   java.io.InputStream inStream,
                                   java.lang.String language,
                                   boolean inheritSecurity)
                            throws PermissionDeniedException,
                                   CollaborationException,
                                   java.rmi.RemoteException

Inserts a new document into the given parent document folder. This method will need to be called to store a newly created document permanently.

If there is already a document or subfolder in the parent folder with the same name as the supplied document, then the name of the newly inserted document will be changed. For example, if a document is submitted with a name of report.doc and this name already exists it will be changed to report_1.doc (or report_2.doc if report_1.doc also already exists). The name of the returned IDocument can be checked to see if it differs from the name requested in the document parameter.

Parameters:

parentFolder - the folder into which to insert the new document. Cannot be null.

documentProperties - an IDocument instance containing meta-data properties for the new document. This object may be obtained by calling createNewDocument. Cannot be null.

checkInComment - a string containing a comment that will be inserted into the document history as the initial check-in comment for the document. Cannot be null.

inStream - an InputStream from which the contents of the new document will be read. Cannot be null.

language - the document content language. This is the ISO 639-1 language code, i.e. en for english. Specifying a null language will set the language to that of the current user.

inheritSecurity - if set to true this will override the security set on the IDocument object, and will instead use the same security as the parent folder.

Returns:

The newly created IDocument instance.

Note: The returned document will be a newly instantiated document and will not be equal to the documentProperties parameter.

Throws:

PermissionDeniedException - if the user does not have permission to insert a document into the given folder.

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the parent folder has not yet been inserted, has already been removed, or the new document is not new.

insertNewFolder

public IDocumentFolder insertNewFolder(IDocumentFolder parentFolder,
                                       IDocumentFolder newFolder,
                                       boolean inheritSecurity)
                                throws PermissionDeniedException,
                                       NameAlreadyInUseException,
                                       CollaborationException,
                                       java.rmi.RemoteException

Inserts a new document folder into the given document folder. This method will need to be called to persist any newly created document folder. The returned IDocumentFolder is the persisted document folder.

Parameters:

parentFolder - the parent document folder to insert into. Cannot be null.

newFolder - the new folder to be inserted. This object may be obtained by calling createNewDocumentFolder. Cannot be null.

inheritSecurity - if set to true this will override the security set on the IDocumentFolder object, and will instead use the same security as the parent folder.

Returns:

A persisted IDocumentFolder. Note: the returned object will be a newly instantiated object and will not be equal to the folder parameter.

Throws:

PermissionDeniedException - if the user does not have permission to insert a document folder into the given parent folder.

NameAlreadyInUseException - if there is already a document or document folder existed in the parent folder with the same name.

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the parent folder has not yet been inserted, has already been removed, or the new folder is not new.

queryDocuments

public IDocument[] queryDocuments(IProject project,
                                  IDocumentFilter documentFilter)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Queries for documents contained in the specified project, and returns an array of IDocuments that satisfies the query filter.

 //The following sample code demonstrates how to query a project for documents checked out by the current user.
 //Create the new query filter
 IDocumentFilter filter = documentManager.createDocumentFilter();
 //Set it to only search for checked-out documents
 filter.setFilterType(DocumentFilterType.CHECKED_OUT_BY_CURRENT_USER);
 //Set to order by size, then last modified date
 DocumentQueryOrder sizeOrder = new DocumentQueryOrder(DocumentAttribute.NUM_BYTES, true);
 DocumentQueryOrder lastModifiedOrder = new DocumentQueryOrder(DocumentAttribute.LAST_MODIFIED, true);
 DocumentQueryOrder[] orders = new DocumentQueryOrder[]}sizeOrder, lastModifiedOrder};
 filter.setQueryOrders(orders);
 //Perform query
 IDocument[] foundDocuments = documentManager.queryDocuments(project, filter);
 

Parameters:

project - the query will be restricted to documents contained in the given project. Cannot be null.

documentFilter - an IDocumentFilter instance specifying which query to perform, the desired sort order of the query result, and the maximum number of results to return. Cannot be null.

Returns:

an array of IDocuments satisfying the filter, in the specified project.

Throws:

CollaborationException - If the method call resulted in an error.

java.rmi.RemoteException - If there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - If the project has not yet been stored or has already been removed.

queryDocuments

public IDocument[] queryDocuments(IDocumentFolder documentFolder,
                                  IDocumentFilter documentFilter)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Queries for documents contained in the specified document folder, and returns an array of IDocuments that satisfies the query filter.

Parameters:

documentFolder - the document folder to query from. The query will be restricted to documents contained in the given folder. Cannot be null.

documentFilter - a IDocumentFilter instance specifying which query to perform, the desired sort order of the query result, and the maximum number of rows to return. Cannot be null.

Returns:

an array of IDocuments satisfying the filter, in the specified document folder.

Throws:

CollaborationException - If the method call resulted in an error.

java.rmi.RemoteException - If there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - If the document folder has not yet been inserted or has already been removed.

queryFolders

public IDocumentFolder[] queryFolders(IDocumentFolder folder,
                                      IDocumentFolderFilter queryfilter)
                               throws CollaborationException,
                                      java.rmi.RemoteException

Queries for document folders contained in the specified document folder, and returns an array of IDocumentFolders that satisfies the query filter.

To return all document folders in a project, get the top level document folder for the project using getTopLevelFolder, then use this method to query the top level document folder for all the document folders it contains.

 //The following sample code demonstrates how to query for document folders in a project.
 //Create the a query filter
 IDocumentFolderFilter filter = documentManager.createDocumentFolderFilter();
 //Set to order by name
 DocumentFolderQueryOrder nameOrder = new DocumentFolderQueryOrder(DocumentFolderAttribute.NAME, true);
 DocumentFolderQueryOrder[] orders = new DocumentFolderQueryOrder[]}nameOrder};
 filter.setQueryOrders(orders);
 //To find folders in a project, we must look in the top level folder
 IDocumentFolder topLevelFolder = documentManager.getTopLevelFolder(project);
 IDocumentFolder[] foundFolders = documentManager.queryFolders(topLevelFolder, filter);
 

Parameters:

folder - the document folder to query from. The query will be restricted to document folders contained in the given folder. Cannot be null.

queryfilter - an IDocumentFolderFilter instance specifying which query to perform, the desired sort order of the query result, and the maximum number of rows to return. Cannot be null.

Returns:

an array of IDocumentFolderss satisfying the filter, in the specified document folder.

Throws:

CollaborationException - If the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the document folder has not yet been inserted or has already been removed.

removeDocument

public void removeDocument(IDocument document)
                    throws PermissionDeniedException,
                           CollaborationException,
                           java.rmi.RemoteException

Deletes the document.

To perform this operation the current user must have ADMIN rights on the document. This can be checked by calling IDocument.isActionAllowed(DocumentPermission.DELETE). Note: if this document is currently checked out, this call will attempt to undo this check-out before deletion.

Parameters:

document - the document to be deleted. Cannot be null.

Throws:

PermissionDeniedException - if the user does not have permission to delete the document.

CollaborationException - if the method call resulted in an error, the object does not exist or the user does not have access to it.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

removeDocumentFolder

public void removeDocumentFolder(IDocumentFolder folder)
                          throws PermissionDeniedException,
                                 CollaborationException,
                                 java.rmi.RemoteException

Deletes the folder.

Parameters:

folder - folder to be deleted. Cannot be null.

Throws:

PermissionDeniedException - if the user does not have permission to delete the folder.

CollaborationException - if the method call resulted in an error, the object does not exist or the user does not have access to it.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

subscribeUsers

public void subscribeUsers(IDocumentFolder documentFolder,
                           int[] userIDs)
                    throws CollaborationException,
                           MultipleObjectException,
                           java.rmi.RemoteException

Subscribe users of the given IDs to the given document folder and all documents in that folder. The calling user must have ADMIN access to the project containing this document folder, and the users to be subscribed have to have at least READ access to the document folder. The call will make a best attempt to subscribe all supplied users. A MultipleObjectException will be thrown specifying the IDs that failed to be subscribed.

Parameters:

documentFolder - the document folder to subcribe users to. Cannot be null.

Throws:

java.lang.IllegalStateException - if the object has not yet been inserted or has already been removed.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

MultipleObjectException - if any users cannot be subscribed

CollaborationException - if the method call resulted in an error.

subscribeUsers

public void subscribeUsers(IDocument document,
                           int[] userIDs)
                    throws CollaborationException,
                           MultipleObjectException,
                           java.rmi.RemoteException

Subscribe users of the given IDs to the given document. The calling user must have ADMIN access to the project containing this document, and the users to be subscribed have to have at least READ access to the document. The call will make a best attempt to subscribe all supplied users. A MultipleObjectException will be thrown specifying the IDs that failed to be subscribed.

Parameters:

document - the document to subcribe users to. Cannot be null.

Throws:

java.lang.IllegalStateException - if the document has not yet been inserted or has already been removed.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

MultipleObjectException - if any users cannot be subscribed

CollaborationException - if the method call resulted in an error.

undoDocumentCheckout

public void undoDocumentCheckout(IDocument document)
                          throws PermissionDeniedException,
                                 CollaborationException,
                                 java.rmi.RemoteException

Puts a document that is currently in the checked-out state into the non-checked-out state.

Parameters:

document - the document whose check-out is being undone. Cannot be null.

Throws:

PermissionDeniedException - if the user does not have permission to perform this operation, or the document is checked-out to a different user.

CollaborationException - if the method call resulted in any error or the user does not have access to the document.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

java.lang.IllegalStateException - if the document is not checked-out, has not yet been inserted or has already been removed.

unsubscribeUsers

public void unsubscribeUsers(IDocumentFolder documentFolder,
                             int[] userIDs)
                      throws CollaborationException,
                             java.rmi.RemoteException

Unsubscribe users of the given IDs from a document folder, including all documents in the folder. Invalid IDs or IDs that do not describe subscribed users will be ignored.

Parameters:

documentFolder - the document folder from which to unsubcribe the users. Cannot be null.

Throws:

java.lang.IllegalStateException - if the object has not yet been inserted or has already been removed.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

CollaborationException - if any of the users specified cannot be subscribed.

unsubscribeUsers

public void unsubscribeUsers(IDocument document,
                             int[] userIDs)
                      throws CollaborationException,
                             java.rmi.RemoteException

Unsubscribe users of the given IDs from a document. Invalid IDs or IDs that do not describe subscribed users will be ignored.

Parameters:

document - the document from which to unsubcribe the users. Cannot be null.

Throws:

java.lang.IllegalStateException - if the document has not yet been inserted or has already been removed.

CollaborationException - if the method resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.