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

public interface IDocument

This interface represents a document, or more specifically, a collection of meta-data about a collaboration document. To retrieve an existing document, use IDocumentManager.getDocument. To insert a new document, first obtain a new empty IDocument using IDocumentManager.createNewDocument, possibly set some of the meta-data such as author, then call IDocumentManager.insertNewDocument. To retrieve the actual content of a saved document, call getContentAsInputStream() Any modification of a document will not be stored permanently until store is called.

Method Summary

AccessLevel	getAccessLevel(RoleType roleType) Returns document access level for a given role type.
java.lang.String	getAuthor() Returns a string representing the author of the document.
java.util.Date	getCheckedOutDate() Returns the date at which the document was last checked out.
IDocumentFolder	getContainingFolder() Returns the document folder that this document is stored in.
IProject	getContainingProject() Returns the project that this document belongs to.
java.io.InputStream	getContentAsInputStream() Returns An InputStream for reading the contents of the current version of the document.
java.lang.String	getContentType() Returns a string representing the content type of the document.
java.lang.String	getContentURL() Returns the URL at which the document can be downloaded.
java.util.Date	getCreatedDate() Returns the creation date.
java.lang.String	getDescription() Returns the document description.
java.lang.String	getDetailsURL() Returns the URL at which the document details can be viewed.
int	getID() Returns the document ID.
java.util.Date	getLastModifiedDate() Returns the last modified date.
java.lang.String	getName() Returns the document name.
int	getOwnerUserID() Returns the user ID of the owner of this document.
java.lang.String	getPath(java.lang.String pathSeparationString) Returns a string representation of the path of a document.
int	getPublishedPortalDocumentID() Returns the corresponding document ID of the portal document that the document has been published to.
boolean	hasCheckedOutDate() Returns true if checked-out date is available, else false.
boolean	hasCreatedDate() Returns true if created date is available, else false.
boolean	hasLastModifiedDate() Returns true if last modified date is available, else false.
boolean	isActionAllowed(DocumentPermission permission) Returns if a given DocumentPermission is allowed for this document.
boolean	isCheckedOut() Returns a boolean indicating whether or not the document is currently in the checked-out state.
boolean	isDefaultSecurity() Indicates whether this document uses project-default security.
boolean	isPublishedToPortal() Returns a boolean value indicating whether or not the document has been published to the portal knowledge directory.
void	setAccessLevel(RoleType roleType, AccessLevel accessLevel) Set document access level for a given role type.
void	setAuthor(java.lang.String author) Sets the document author.
void	setContentType(java.lang.String contentType) Sets the document content type.
void	setDefaultSecurity(boolean isDefaultSecurity) Enables or disables this document's use of project default security.
void	setDescription(java.lang.String description) Sets the document description.
void	setName(java.lang.String name) Sets the document name.
void	store() Store properties or meta-data of a document.

Method Detail

getAccessLevel

public AccessLevel getAccessLevel(RoleType roleType)

Returns document access level for a given role type.

Parameters:

roleType - the role type for which to get the access level. Cannot be null.

Returns:

the access level for a given role type.

Throws:

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

getAuthor

public java.lang.String getAuthor()

Returns a string representing the author of the document.

This is an arbitrary string intended for display to the user. Note: If this is not set, it will default to to the current user's username.

Returns:

a String representing the author of the document. This is a settable property of the document.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

getCheckedOutDate

public java.util.Date getCheckedOutDate()

Returns the date at which the document was last checked out.

Returns:

the date at which the document was last checked out.

Throws:

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

getContainingFolder

public IDocumentFolder getContainingFolder()
                                    throws CollaborationException,
                                           java.rmi.RemoteException

Returns the document folder that this document is stored in.

Returns:

the document folder that this document is stored in.

Throws:

CollaborationException - if the method call resulted in an error.

java.lang.IllegalStateException - if the document has already been removed.

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

getContainingProject

public IProject getContainingProject()
                              throws CollaborationException,
                                     java.rmi.RemoteException

Returns the project that this document belongs to.

Returns:

the project that this document belongs to.

Throws:

CollaborationException - if the method call resulted in an error.

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.

getContentAsInputStream

public java.io.InputStream getContentAsInputStream()
                                            throws CollaborationException,
                                                   java.rmi.RemoteException

Returns An InputStream for reading the contents of the current version of the document.

WARNING: It is essential the the client call close() on the input stream once finished reading from it. It is recommended to put a call to close() in a finally block.

Returns:

an InputStream which can be used to read the document contents.

Throws:

CollaborationException - if the method call resulted in an error.

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.

getContentType

public java.lang.String getContentType()

Returns a string representing the content type of the document.

The content type is a MIME type, such as text/plain.

Returns:

a string representing the content type of the document.

Throws:

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

getContentURL

public java.lang.String getContentURL()

Returns the URL at which the document can be downloaded.

Note: this URL is gatewayed using the Collaboration Server's primary portal.

Returns:

the document content URL.

Throws:

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

getCreatedDate

public java.util.Date getCreatedDate()

Returns the creation date.

Returns:

the creation date.

Throws:

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

getDescription

public java.lang.String getDescription()

Returns the document description.

Returns:

the document description.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

getDetailsURL

public java.lang.String getDetailsURL()

Returns the URL at which the document details can be viewed.

Note: this URL is gatewayed using the Collaboration Server's primary portal.

Returns:

the document details URL.

Throws:

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

getID

public int getID()

Returns the document ID.

Returns:

the document ID.

Throws:

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

getLastModifiedDate

public java.util.Date getLastModifiedDate()

Returns the last modified date.

Returns:

the last modified date.

Throws:

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

getName

public java.lang.String getName()

Returns the document name.

Returns:

the document name.

Throws:

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

getOwnerUserID

public int getOwnerUserID()

Returns the user ID of the owner of this document. The owner of a document is the user who creates the document.

Returns:

the owner ID.

Throws:

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

getPath

public java.lang.String getPath(java.lang.String pathSeparationString)

Returns a string representation of the path of a document. The string is formed by concatenating the path component's strings using the specified separation string between path components.

Parameters:

pathSeparationString - the string to insert between path components. Cannot be null.

Returns:

a string representing the path of a folder.

Throws:

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

getPublishedPortalDocumentID

public int getPublishedPortalDocumentID()
                                 throws PermissionDeniedException,
                                        CollaborationException,
                                        java.rmi.RemoteException

Returns the corresponding document ID of the portal document that the document has been published to.

Returns:

the corresponding document ID of the portal document that the document has been published to.

Throws:

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

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

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.

hasCheckedOutDate

public boolean hasCheckedOutDate()

Returns true if checked-out date is available, else false.

Returns:

true if checked-out date is available, else false.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

hasCreatedDate

public boolean hasCreatedDate()

Returns true if created date is available, else false.

Returns:

true if created date is available, else false.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

hasLastModifiedDate

public boolean hasLastModifiedDate()

Returns true if last modified date is available, else false.

Returns:

true if last modified date is available, else false.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

isActionAllowed

public boolean isActionAllowed(DocumentPermission permission)
                        throws CollaborationException,
                               java.rmi.RemoteException

Returns if a given DocumentPermission is allowed for this document.

This method can be used to determine if a user can perform a given action within the context of a document such as editing a document, copying a document, editing document security, etc. See the enumeration type DocumentPermission for details about specific document permissions.

Parameters:

permission - document permission.Cannot be null.

Returns:

true if the user can perform the given action, else false.

Throws:

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.

CollaborationException - if the call resulted in an error.

isCheckedOut

public boolean isCheckedOut()

Returns a boolean indicating whether or not the document is currently in the checked-out state.

Returns:

a boolean indicating whether or not the document is currently in the checked-out state.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

isDefaultSecurity

public boolean isDefaultSecurity()

Indicates whether this document uses project-default security.

If true, modifying security on the current document will not be possible. setDefaultSecurity must be set to false in order to modify individual documents' security. Default value for isDefaultSecurity is true.

Returns:

true if the document uses project-default security, false if the document is enabled to use its own security.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

isPublishedToPortal

public boolean isPublishedToPortal()
                            throws PermissionDeniedException,
                                   CollaborationException,
                                   java.rmi.RemoteException

Returns a boolean value indicating whether or not the document has been published to the portal knowledge directory.

Returns:

a boolean indicating whether or not the document has been published to the portal knowledge directory.

Throws:

java.lang.IllegalStateException - if the document has not yet been inserted 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.

PermissionDeniedException

setAccessLevel

public void setAccessLevel(RoleType roleType,
                           AccessLevel accessLevel)

Set document access level for a given role type.

Note: To set custom access levels, default security must first be set to false calling setDefaultSecurity(false).

Parameters:

roleType - the role type for which access level will be set.

accessLevel - the access level.

Throws:

java.lang.IllegalStateException - if the document has not yet been inserted, has already been removed or is set to use default security.

setAuthor

public void setAuthor(java.lang.String author)

Sets the document author. This is an arbitrary string intended for display to the user. Note: If this is not set, it will default to to the current user's username.

Parameters:

author - string containing the author. Cannot be null.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

setContentType

public void setContentType(java.lang.String contentType)

Sets the document content type. The content type is a MIME type, such as text/plain.

Parameters:

contentType - a string containing the content type. Cannot be null.

Throws:

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

setDefaultSecurity

public void setDefaultSecurity(boolean isDefaultSecurity)

Enables or disables this document's use of project default security.

Calling this method with true will enable defaultSecurity, calling it with false will disable defaultSecurity.
By default all documents are created with defaultSecurity set to true. To modify security on individual documents, the documents must have defaultSecurity disabled before modification. After this method is called, any project-level security modification will not be applied to the documents, and only individual document's security will be used.
This method might be used in conjunction with isDefaultSecurity, which would indicate if the current document has defaultSecurity enabled.

Parameters:

isDefaultSecurity - true if it uses default security, otherwise false.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

setDescription

public void setDescription(java.lang.String description)

Sets the document description.

Parameters:

description - the description. Cannot be null.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

setName

public void setName(java.lang.String name)

Sets the document name.

Parameters:

name - the document name. Cannot be null.

Throws:

java.lang.IllegalStateException - if the document has already been removed.

store

public void store()
           throws PermissionDeniedException,
                  CollaborationException,
                  java.rmi.RemoteException

Store properties or meta-data of a document. Can be used to edit properties of an existing document. To change the content of a document, use IDocumentManager.checkInDocument.

Throws:

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

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 has not yet been inserted or has already been removed.