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

public interface IDocument

Interface that represents a document, or more specifically, a collection of metadata 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, set some of the metadata 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 on which the document was last checked out.
IDocumentFolder	getContainingFolder() Returns an IDocumentFolder object representing the document folder that this document is stored in.
IProject	getContainingProject() Returns An IProject instance representing the project to which this document belongs.
java.io.InputStream	getContentAsInputStream() Returns an InputStream for reading the contents of the current version of the document.
java.io.InputStream	getContentAsInputStream(int version) 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.
IObjectReference[]	getObjectReferences() Returns an array of IObjectReference.
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 to which the document has been published.
IDocumentVersion[]	getVersionHistory() Returns an array of IDocumentVersion.
boolean	hasCheckedOutDate() Returns true if the date of the last check-out is available, otherwise false.
boolean	hasCreatedDate() Returns true if the created date is available, otherwise false.
boolean	hasLastModifiedDate() Returns true if last modified date is available, otherwise false.
boolean	isActionAllowed(DocumentPermission permission) Returns whether or not a given DocumentPermission is allowed for this document.
boolean	isCheckedOut() Returns a boolean indicating whether or not the document is currently checked out.
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, which is a MIME type, such as text/plain, text/xml;charset=utf-8", etc.
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() Stores properties or metadata 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 property is not set, it will default to to the current user's username.

Returns:

a string representing the author of the document (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 on which the document was last checked out.

Returns:

the date on which the document was last checked out

Throws:

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

getContainingFolder

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

Returns an IDocumentFolder object representing 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 was a communication problem during the execution of the remote method call

getContainingProject

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

Returns An IProject instance representing the project to which this document belongs.

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

getContentAsInputStream

public java.io.InputStream getContentAsInputStream(int version)
                                            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.

Parameters:

version - a valid document version

Returns:

an InputStream that 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, or if the version number does not exist.

java.rmi.RemoteException - if there was 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

getObjectReferences

public IObjectReference[] getObjectReferences()
                                       throws CollaborationException,
                                              java.rmi.RemoteException

Returns an array of IObjectReference. For documents, object references include attached task lists and discussions.

Returns:

an array of IObjectReference for the current document

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, or if the version number does not exist.

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

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 to which the document has been published.

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

getVersionHistory

public IDocumentVersion[] getVersionHistory()
                                     throws CollaborationException,
                                            java.rmi.RemoteException

Returns an array of IDocumentVersion.

Returns:

an array of IDocumentVersion for the current document

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, or if the version number does not exist.

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

hasCheckedOutDate

public boolean hasCheckedOutDate()

Returns true if the date of the last check-out is available, otherwise false.

Returns:

true if the date of the last check-out is available, else false

Throws:

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

hasCreatedDate

public boolean hasCreatedDate()

Returns true if the created date is available, otherwise false.

Returns:

true if the 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, otherwise 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 whether or not 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 - the 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 checked out.

Returns:

a boolean indicating whether or not the document is currently checked out

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 security for an individual document. 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 was 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 by 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 property is not set, it will default to to the current user's username.

Parameters:

author - a 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, which is a MIME type, such as text/plain, text/xml;charset=utf-8", etc. When uploading a document that contains non-ASCII characters (particularly, European accented letters), this method must be called to set the content type to text/xml;charset=iso-8859-1 prior to calling IDocumentManager.insertNewDocument.

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 an individual document, the document must have defaultSecurity disabled before modification. After this method is called, any project-level security modification will not be applied to the document, and only the individual document's security will be used.
This method can 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

Stores properties or metadata 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 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