|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Interface for managing IDocument
and IDocumentFolder
functionality. It handles creation,
copying, removal and querying for documents and document folders.
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 IDocument s
that satisfies the query filter. |
IDocument[] |
queryDocuments(IProject project,
IDocumentFilter documentFilter)
Queries for documents contained in the specified project, and returns an array of IDocument s 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 IDocumentFolder s
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 |
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
//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);
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.
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 removedpublic void checkOutDocument(IDocument document) throws PermissionDeniedException, CollaborationException, java.rmi.RemoteException
document
- the document to be checked out; cannot be null
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 removedpublic void copyToFolder(IDocumentFolder sourceParentFolder, IDocumentFolder targetFolder, IDocument[] documentsToCopy, IDocumentFolder[] foldersToCopy, boolean inheritSecurity, java.lang.String documentHistoryComment) throws CollaborationException, java.rmi.RemoteException, MultipleObjectException
MultipleException
will be thrown specifying the objects which caused
failures.
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
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.public IDocumentFilter createDocumentFilter()
IDocumentFilter
for querying documents.
The filter will initially be set to return all documents unordered.
public IDocumentFolderFilter createDocumentFolderFilter()
IDocumentFolderfilter
for querying documents.
The filter will initially be set to return all document folders unordered.
public IDocument createNewDocument(java.lang.String name, java.lang.String description)
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);
name
- the name of the document; cannot be null
description
- the description of the document; cannot be null
IDocument
instancepublic IDocumentFolder createNewFolder(java.lang.String name, java.lang.String description)
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);
name
- the name of the document folderdescription
- the description of the document folder
IDocumentFolder
instancepublic IDocument getDocument(int documentID) throws CollaborationException, java.rmi.RemoteException
IDocument
with the specified ID, or null
if there is no document with the given ID.
documentID
- the document ID. The ID of a document can be obtained using the
getID
method on the IDocument
interface. Must be positive.
IDocument
with the specified ID or 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 callpublic IDocumentFolder getDocumentFolder(int folderID) throws CollaborationException, java.rmi.RemoteException
IDocumentFolder
for the specified ID, or null
if there is no document folder
with the given ID.
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.
IDocumentFolder
with the specified ID or 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 callpublic int[] getSubscribedUserIDs(IDocumentFolder documentFolder) throws CollaborationException, java.rmi.RemoteException
documentFolder
- the document folder; cannot be null
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 subscribedpublic int[] getSubscribedUserIDs(IDocument document) throws CollaborationException, java.rmi.RemoteException
document
- the document; cannot be null
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 subscribedpublic IDocumentFolder getTopLevelFolder(IProject project) throws CollaborationException, java.rmi.RemoteException
project
- the project whose top-level folder is being requested; cannot be null
IDocumentFolder
for the top-level folder in the given project or 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 callpublic 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
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.
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
instance.
Note: The returned document will be a newly instantiated document and will not be equal to the
documentProperties
parameter.
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 newpublic IDocumentFolder insertNewFolder(IDocumentFolder parentFolder, IDocumentFolder newFolder, boolean inheritSecurity) throws PermissionDeniedException, NameAlreadyInUseException, CollaborationException, java.rmi.RemoteException
IDocumentFolder
is the persisted document folder.
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 folder
parameter.
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 newpublic IDocument[] queryDocuments(IProject project, IDocumentFilter documentFilter) throws CollaborationException, java.rmi.RemoteException
IDocument
s 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);
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
IDocument
s satisfying the filter, in the specified project
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 removedpublic IDocument[] queryDocuments(IDocumentFolder documentFolder, IDocumentFilter documentFilter) throws CollaborationException, java.rmi.RemoteException
IDocument
s
that satisfies the query filter.
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
.
IDocument
s satisfying the filter, in the specified document 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 document folder has not yet been inserted or has already been removedpublic IDocumentFolder[] queryFolders(IDocumentFolder folder, IDocumentFolderFilter queryfilter) throws CollaborationException, java.rmi.RemoteException
IDocumentFolder
s
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);
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
.
IDocumentFolders
s satisfying the filter, in the specified document 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 document folder has not yet been inserted or has already been removedpublic void removeDocument(IDocument document) throws PermissionDeniedException, CollaborationException, java.rmi.RemoteException
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.
document
- the document to be deleted; cannot be null
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 callpublic void removeDocumentFolder(IDocumentFolder folder) throws PermissionDeniedException, CollaborationException, java.rmi.RemoteException
folder
- the folder to be deleted; cannot be null
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 callpublic void subscribeUsers(IDocumentFolder documentFolder, int[] userIDs) throws CollaborationException, MultipleObjectException, java.rmi.RemoteException
MultipleObjectException
will be thrown specifying the IDs that failed to be subscribed.
documentFolder
- the document folder to subcribe users to; cannot be null
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 errorpublic void subscribeUsers(IDocument document, int[] userIDs) throws CollaborationException, MultipleObjectException, java.rmi.RemoteException
MultipleObjectException
will be thrown specifying the IDs that failed to be subscribed.
document
- the document to subcribe users to; cannot be null
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 errorpublic void undoDocumentCheckout(IDocument document) throws PermissionDeniedException, CollaborationException, java.rmi.RemoteException
document
- the document whose check-out is being undone; cannot be null
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 removedpublic void unsubscribeUsers(IDocumentFolder documentFolder, int[] userIDs) throws CollaborationException, java.rmi.RemoteException
documentFolder
- the document folder from which to unsubcribe the users; cannot be null
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 subscribedpublic void unsubscribeUsers(IDocument document, int[] userIDs) throws CollaborationException, java.rmi.RemoteException
document
- the document from which to unsubcribe the users; cannot be null
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
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright ©2010 Oracle® Corporation. All Rights Reserved.