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

public interface IFolderManager

Interface for managing IFolder functionality. Handles folder creation, removal and retrieval. An IFolder is a container for other Publisher objects, such as IContentItem, IDataEntryTemplate, IPresentationTemplate, ISelectionList, and other IFolder objects.

For additional details about folder functionality and folder security management, see the Administrator Guide for AquaLogic Interaction Publisher.

Note: The folder security management is handled primarily by the Publisher Explorer. Currently the remote API does not provide a way to manage security for any Publisher 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. Use Publisher Explorer for administration or security modification.

Method Summary

void	copyFolder(IFolder sourceFolder, IFolder destinationFolder) Copies all the objects of the source folder to the destination folder recursively, including any content items, Data Entry Templates, Presentation Templates, selection lists, subfolders and all objects in each subfolder.
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 Publisher root folder.
IFolder[]	getSubfolders(IFolder folder) Returns the immediate subfolders contained in the specified folder.
void	moveFolder(IFolder sourceFolder, IFolder destinationParentFolder) Moves all the objects of the source folder into the specified destination parent folder, including any content items, Data Entry Templates, Presentation Templates, selection lists, subfolders and all objects in each subfolder.
void	removeFolder(IFolder folder) Deletes the folder.

Method Detail

copyFolder

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

Copies all the objects of the source folder to the destination folder recursively, including any content items, Data Entry Templates, Presentation Templates, selection lists, subfolders and all objects in each subfolder.

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 must 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 must be persisted prior to call

destinationFolder - the folder to copy into; cannot be null and must 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 Publisher 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 must 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; 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; cannot be null, empty or longer than 255 characters. The UUID of an object can be obtained using the getUUID method in the IFolder class.

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 Publisher 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 a 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 Publisher 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 Publisher 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 Publisher 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 subfolders contained in the specified folder.

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

Parameters:

folder - the parent folder; cannot be null

Returns:

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

Throws:

ContentException - if the method call resulted in a Publisher 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

Moves all the objects of the source folder into the specified destination parent folder, including any content items, Data Entry Templates, Presentation Templates, selection lists, subfolders and all objects in each subfolder.

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 must 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; the parent folder will become the specified destination parent folder, and the folder path will become a subfolder 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 must be persisted prior to call

destinationParentFolder - the parent folder to move the folder into; cannot be null and must 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 Publisher 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 subfolders, all subfolders and items in those subfolders 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 subfolders

ContentException - if the method call resulted in a Publisher exception

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