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) Subscribes users with the given IDs to the given document folder and all documents in that folder.
void	subscribeUsers(IDocument document, int[] userIDs) Subscribes users with 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 (reverses the current check-out).
void	unsubscribeUsers(IDocumentFolder documentFolder, int[] userIDs) Unsubscribes users with the given IDs from a document folder, including all documents in the folder.
void	unsubscribeUsers(IDocument document, int[] userIDs) Unsubscribes users with 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 - true to automatically check in and 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 was 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 was 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. For example, 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 was 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 must 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 was 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 was 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 was 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 this document

Throws:

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

java.rmi.RemoteException - if there was 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 was 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 already exists). The name of the returned IDocument can be checked to see if it differs from the name requested in the document parameter.

If the document to be uploaded contains non-ASCII characters (particularly, european accented letters), please set the content type of the document to "text/xml;charset=iso-8859-1" using IDocument.setContentType before calling this method.

Parameters:

parentFolder - the folder into which to insert the new document; cannot be null

documentProperties - an IDocument instance containing metadata properties for the new document. This object can 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 - true to override the security set on the IDocument object and use the same security as the parent folder instead.

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 was 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 - true to override the security set on the IDocumentFolder object and use the same security as the parent folder instead

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 - a 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 was 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 - an 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 was 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 was 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 the 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 was 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 - the 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 was 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

Subscribes users with 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 must 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 was a communication problem during the execution of the remote method call

MultipleObjectException - if any of the users specified 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

Subscribes users with 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 must 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 was a communication problem during the execution of the remote method call

MultipleObjectException - if any of the users specifiedcannot 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 (reverses the current check-out).

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 was 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

Unsubscribes users with 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 was 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

Unsubscribes users with 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 was a communication problem during the execution of the remote method call