com.plumtree.remote.prc.content.folder
Interface IFolderManager

public interface IFolderManager

IFolderManager is an interface for managing IFolder functionality. It handles folder creation, removal and retrieval. An IFolder is a container for other Content Server objects, such as IContentItem, IDataEntryTemplate, IPresentationTemplate, ISelectionList, and other IFolder objects.

For additional details about Content folder functionality and folder security management, please see the Administrator Guide for Content Server.

Note that folder security management is handled primarily by the Content Server Explorer. Currently the remote API does not provide a way to manage security for any Content Server object or expose any administrative control.

When a new folder is created and stored, the security level of the newly-created folder will inherit the security of its parent folder by default. Please use Content Server Explorer for administration or security modification.

Method Summary

void	copyFolder(IFolder sourceFolder, IFolder destinationFolder) Copy all the objects of the source folder to the destination folder recursively, including any content items, Data Entry Templates, Presentation Templates, selection lists, sub-folders and all objects in each sub-folder.
IFolder	createFolder(IFolder parentFolder, java.lang.String name) Creates a new IFolder instance.
IFolder	getFolder(java.lang.String UUID) Returns an IFolder by its UUID.
IFolder	getFolderByPath(java.lang.String path) Returns an IFolder by its path.
IFolder	getRootFolder() Returns the Content Server root folder.
IFolder[]	getSubfolders(IFolder folder) Returns the immediate sub-folders contained in the specified folder.
void	moveFolder(IFolder sourceFolder, IFolder destinationParentFolder) Move all the objects of the source folder into the specified destination parent folder, including any content items, Data Entry Templates, Presentation Templates, selection lists, sub-folders and all objects in each sub-folder.
void	removeFolder(IFolder folder) Deletes the folder.

Method Detail

copyFolder

public void copyFolder(IFolder sourceFolder,
                       IFolder destinationFolder)
                throws ContentSecurityException,
                       ContentException,
                       java.rmi.RemoteException

Copy all the objects of the source folder to the destination folder recursively, including any content items, Data Entry Templates, Presentation Templates, selection lists, sub-folders and all objects in each sub-folder.

This method will attempt to copy all the objects in the source folder in an atomic operation. If an error occurs while copying one of the objects, the copying will stop and all changes will be rolled-back.

Prior to the call, both the source and destination folders have to be stored. A ContentException will be thrown if you copy a folder to any of its subfolders. An IllegalStateException will be thrown if you copy a folder to itself.

Parameters:

sourceFolder - the folder to copy; cannot be null and has to be persisted prior to call.

destinationFolder - the folder to copy into; cannot be null and has to be persisted prior to call.

Throws:

java.lang.IllegalStateException - if you copy a folder to itself or the destination or souce folder has not yet been stored or has been removed.

ContentSecurityException - if the user does not have permission to access the destination or source folders.

ContentException - if the method call resulted in a Content Server exception.

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

createFolder

public IFolder createFolder(IFolder parentFolder,
                            java.lang.String name)

Creates a new IFolder instance. The method IFolder.store needs to be called to persist this newly-created folder.

The security level of a newly-created, persisted folder will inherit the security of its parent folder by default.

An IllegalStateException will be thrown if the parent folder has not been stored.

Parameters:

parentFolder - the parent folder to insert into; cannot be null.

name - the name of the folder. The name cannot be null, empty, or longer than 255 characters. The string used for the name will be trimmed of leading and trailing whitespace when it is stored and is case-insensitive during name comparison. If there is already a folder in the parent folder with the same name a NameAlreadyInUseException will be thrown when IFolder.store is called.

Returns:

a new IFolder instance.

Throws:

java.lang.IllegalStateException - if specified parent folder has not yet been stored or has been removed.

java.lang.IllegalArgumentException - if the name is an empty string or longer than 255 characters.

getFolder

public IFolder getFolder(java.lang.String UUID)
                  throws ContentSecurityException,
                         ContentException,
                         java.rmi.RemoteException

Returns an IFolder by its UUID.

Parameters:

UUID - the IFolder UUID. The UUID of an object can be obtained using the getUUID method in the IFolder class; cannot be null, empty or longer than 255 characters.

Returns:

the IFolder or null if the folder does not exist.

Throws:

java.lang.IllegalArgumentException - if the UUID is an empty string or longer than 255 characters.

ContentSecurityException - if the user does not have permission to access the folder.

ContentException - if the method call resulted in a Content Server exception.

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

getFolderByPath

public IFolder getFolderByPath(java.lang.String path)
                        throws ContentSecurityException,
                               ContentException,
                               java.rmi.RemoteException

Returns an IFolder by its path. The path of a folder can be obtained using the getPath method in the IFolder class.

Note: This method will not function properly if the folder to be retrieved or any of its containing folders has '/' in its name, since all instances of '/' will be treated as path separator.

Parameters:

path - the IFolder path delimited by '/'; cannot be null, empty or longer than 255 characters.

Returns:

the IFolder or null if the folder does not exist.

Throws:

java.lang.IllegalArgumentException - if the path is an empty string or longer than 255 characters.

ContentSecurityException - if the user does not have permission to access the folder.

ContentException - if the method call resulted in a Content Server exception.

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

getRootFolder

public IFolder getRootFolder()
                      throws ContentSecurityException,
                             ContentException,
                             java.rmi.RemoteException

Returns the Content Server root folder.

Returns:

an IFolder for the root folder or null if the user does not have access to the folder.

Throws:

ContentSecurityException - if the user does not have permission to access the root folder.

ContentException - if the method call resulted in a Content Server exception.

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

getSubfolders

public IFolder[] getSubfolders(IFolder folder)
                        throws ContentSecurityException,
                               ContentException,
                               java.rmi.RemoteException

Returns the immediate sub-folders contained in the specified folder.

To retrieve folders or traverse the Content Server folder hierarchy, first retrieve the root folder using getRootFolder, then use this method to retrieve the immediate sub-folders the root folder contains and so on.

Parameters:

folder - the parent folder. Cannot be null.

Returns:

an array of IFolders which are the immediate sub-folders of the specified parent folder. The returned array is not ordered.

Throws:

ContentException - if the method call resulted in a Content Server exception.

ContentSecurityException - if the user does not have permission to access the folder.

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 been deleted or has not been stored.

moveFolder

public void moveFolder(IFolder sourceFolder,
                       IFolder destinationParentFolder)
                throws ContentSecurityException,
                       ContentException,
                       java.rmi.RemoteException

Move all the objects of the source folder into the specified destination parent folder, including any content items, Data Entry Templates, Presentation Templates, selection lists, sub-folders and all objects in each sub-folder.

This method will attempt to move all the objects in the source folder in an atomic operation. If an error occurs while moving one of the objects, the move will stop and all changes will be rolled-back.

Prior to the call, both the source and destination folders have to be stored. A ContentException will be thrown if you move a folder to any of its subfolders.

Note: The sourceFolder will be refreshed with new values for its folder path and parent folder value, i.e. the parent folder will become the specified destination parent folder, and the folder path will become a sub-folder path in the desintation parent folder. Any existing instances of IFolder that refer to the sourceFolder prior to this move operation will need to be refreshed from the server.

Parameters:

sourceFolder - the folder to move; cannot be null and has to be persisted prior to call.

destinationParentFolder - the parent folder to move the folder into; cannot be null and has to be persisted prior to call.

Throws:

java.lang.IllegalStateException - if source folder has not yet been stored or has been removed or the destination parent folder has not been stored or has been removed.

ContentSecurityException - if the user does not have permission to access one of the folders.

ContentException - if the method call resulted in a Content Server exception.

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

removeFolder

public void removeFolder(IFolder folder)
                  throws ContentSecurityException,
                         ContentException,
                         java.rmi.RemoteException

Deletes the folder. If the folder contains sub-folders, all sub-folders and items in those sub-folders will be removed as well.

Parameters:

folder - folder to be deleted; cannot be null.

Throws:

ContentSecurityException - if the user does not have permission to delete the folder or one of its sub-folders.

ContentException - if the method call resulted in a Content Server exception.

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