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

public interface IDocumentFolder

This interface represents a document folder or a collection of meta-data about a document folder. To retrieve an existing folder use IDocumentManager.getFolder. To insert a newly created folder, first obtain a new empty folder using IDocumentManager.createNewFolder, set some of the meta-data, then store the document folder by calling IDocumentManager.insertNewFolder. Any modification or updates of the meta-data of a document folder will not be stored permanently until store is called.

Method Summary

AccessLevel	getAccessLevel(RoleType roleType) Returns document folder access level for a given role type.
IProject	getContainingProject() Returns the project that this document folder belongs to.
java.util.Date	getCreatedDate() Returns the creation date.
java.lang.String	getDescription() Returns the document folder description.
java.lang.String	getDetailsURL() Returns the URL which can be used to view the document folder details.
int	getID() Returns the document folder ID.
java.util.Date	getLastModifiedDate() Returns the last modified date.
java.lang.String	getName() Returns the document folder name.
int	getOwnerUserID() Returns the user ID of the owner of this document folder.
IDocumentFolder	getParentFolder() Returns the parent folder, or null if this is the top-level folder for a project.
java.lang.String	getPath(java.lang.String pathSeparationString) Returns a string representation of the path of a document folder.
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(DocumentFolderPermission permission) Returns if a given DocumentFolderPermission is allowed for this document folder.
boolean	isDefaultSecurity() Indicates whether this document folder uses project-default security.
void	setAccessLevel(RoleType roleType, AccessLevel accessLevel) Set document folder access level for a given role type.
void	setDefaultSecurity(boolean isDefaultSecurity) Enables or disables this document folder's use of project default security.
void	setDescription(java.lang.String description) Sets the document folder description.
void	setName(java.lang.String name) Sets the document folder name.
void	store() Stores a document folder.

Method Detail

getAccessLevel

public AccessLevel getAccessLevel(RoleType roleType)

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

getContainingProject

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

Returns the project that this document folder belongs to.

Returns:

the project that this document folder belongs to.

Throws:

CollaborationException - if the method call resulted in an error.

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

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

getCreatedDate

public java.util.Date getCreatedDate()

Returns the creation date.

Returns:

the creation date.

Throws:

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

getDescription

public java.lang.String getDescription()

Returns the document folder description.

Returns:

the document folder description.

Throws:

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

getDetailsURL

public java.lang.String getDetailsURL()

Returns the URL which can be used to view the document folder details.

Note: this URL is gatewayed using the collaboration server's primary portal.

Returns:

the document folder details URL.

getID

public int getID()

Returns the document folder ID.

Returns:

the document folder ID.

Throws:

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

getName

public java.lang.String getName()

Returns the document folder name.

Returns:

the document folder name.

Throws:

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

getOwnerUserID

public int getOwnerUserID()

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

Returns:

the owner ID.

Throws:

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

getParentFolder

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

Returns the parent folder, or null if this is the top-level folder for a project.

Returns:

the parent folder or null if this is the top-level folder for a project.

Throws:

CollaborationException

java.rmi.RemoteException

getPath

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

Returns a string representation of the path of a document folder. 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 folder has not yet been inserted or 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 folder 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 folder has already been removed.

isActionAllowed

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

Returns if a given DocumentFolderPermission is allowed for this document folder.

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

Parameters:

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

CollaborationException - if the call resulted in an error.

isDefaultSecurity

public boolean isDefaultSecurity()

Indicates whether this document folder uses project-default security.

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

Returns:

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

Throws:

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

setAccessLevel

public void setAccessLevel(RoleType roleType,
                           AccessLevel accessLevel)

Set document folder 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. Cannot be null.

accessLevel - the access level.

Throws:

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

setDefaultSecurity

public void setDefaultSecurity(boolean isDefaultSecurity)

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

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

Note: Adjusting the security on a folder makes no changes to the security on any of its contained documents or folders.

Parameters:

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

Throws:

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

setDescription

public void setDescription(java.lang.String description)

Sets the document folder description.

Parameters:

description - the description. Cannot be null.

Throws:

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

setName

public void setName(java.lang.String name)

Sets the document folder name.

Parameters:

name - the document folder name. Cannot be null.

Throws:

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

store

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

Stores a document folder. Any modification of the meta-data of a documnet folder will not be stored permanently until this method is called.

Throws:

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

CollaborationException - if the method call resulted in an error.

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