com.plumtree.remote.prc.content.item
Interface IContentItemManager

public interface IContentItemManager

Interface for managing IContentItem instances. Handles content item creation, removal, retrieval, check-in, check-out, and publishing.

To retrieve or update property values of an existing content item call checkOutItem to check out the item then IContentItem.get/setPropertyValue to modify the property values. When you are finished use IContentItemManager.checkInItem to check in the item and persist the changes.

For information about the conditions that make a content item searchable in the Search Server, refer to IPresentationTemplate.isSearchable.

Refer to the Administrator Guide for AquaLogic Interaction Publisher for additional details on Content Item functionality.

The following example demonstrates creating and publishing a content item.

 // Create a property to use in the content item
 ITextLineProperty textLineProperty = propertyManager.createTextLineProperty("TextLineProperty", "A line of text.");
 // Create Presentation Template text that uses the property
 String templateText = "TextLineProperty=<pcs:value expr=\"TextLineProperty\">unset</pcs:value>\n";
 IPresentationTemplate presentationTemplate = presentationTemplateManager.createPresentationTemplate(containingFolder, "PresentationTemplate", templateText);
 presentationTemplate.store();
  
 // Create a Data Entry Template using the property and Presentation Template
 IDataEntryTemplate dataEntryTemplate = dataEntryTemplateManager.createDataEntryTemplate(containingFolder, "DataEntryTemplate");
 dataEntryTemplate.addProperty(textLineProperty);
 dataEntryTemplate.attachPresentationTemplate(presentationTemplate);
 dataEntryTemplate.store();
  
 // Create a content item and set a value for the property
 IContentItem contentItem = contentItemManager.createContentItem(containingFolder, "ContentItem", dataEntryTemplate);
 contentItem.setTextLinePropertyValue(textLineProperty, "This is the string value that will appear in the published content item.");
 contentItemManager.checkInItem(contentItem, "Initial checkin.");
  
 // Publish the content item and get the URL string to the published item
 contentItemManager.publishContentItem(contentItem);
 String publishedURLString = contentItem.getPublishURL();
 

Method Summary

void	checkInItem(IContentItem contentItem, java.lang.String checkInComment) Checks in and stores a content item.
void	checkOutItem(IContentItem contentItem) Puts the content item into the checked-out state.
IContentItem	copyContentItem(IContentItem contentItem, java.lang.String name) Copies an IContentItem.
IContentItem	createContentItem(IFolder containingFolder, java.lang.String name, IDataEntryTemplate dataEntryTemplate) Creates a new IContentItem with the given IDataEntryTemplate in the containing folder.
void	expireContentItem(IContentItem contentItem) Expires a IContentItem so it can no longer be published.
IContentItem	getContentItem(IFolder folder, java.lang.String name) Retrieves an IContentItem in a folder by its name.
IContentItem	getContentItem(java.lang.String UUID) Returns an IContentItem by its UUID.
IContentItem[]	getContentItems(IFolder folder) Returns all IContentItems contained in a given IFolder.
IContentItem[]	getContentItems(IFolder folder, IDataEntryTemplate dataEntryTemplate) Returns an array of IContentItems using the specified IDataEntryTemplate in an IFolder.
void	previewContentItem(IContentItem contentItem) Previews the IContentItem and copies it to a preview target set internally by Publisher.
void	publishContentItem(IContentItem contentItem) Publishes the IContentItem and copies it to a publishing target set in Publisher.
void	publishContentItems(IFolder folder, boolean publishSubfolders) Publishes all IContentItems in a folder and optionally publishes items in subfolders.
void	removeContentItem(IContentItem contentItem) Deletes the IContentItem.
void	undoCheckOutItem(IContentItem contentItem) Puts a content item that is currently in the checked-out state into the non-checked-out state.
void	unexpireContentItem(IContentItem contentItem) Re-publishes the IContentItem and removes the item from its expired state if expireContentItem has been previously called.

Method Detail

checkInItem

public void checkInItem(IContentItem contentItem,
                        java.lang.String checkInComment)
                 throws NameAlreadyInUseException,
                        ContentSecurityException,
                        ContentException,
                        java.rmi.RemoteException

Checks in and stores a content item. When an item is checked in, a new version of the item will be saved, the version number will be incremented and the version check in comments will be updated.

This method is used to store a newly-created content item or to persist property value and name changes. A content item must be checked out before updating the name or property values.

Parameters:

contentItem - the content item to check in; cannot be null

checkInComment - a string containing a comment that will be inserted into the content item history as a check in comment of the new version; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to check in the content item

NameAlreadyInUseException - if there is already a content item with the given name in the same folder

ContentException - if the content item is associated with an invalid portlet ID, or 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

java.lang.IllegalStateException - if the item has has been removed, the containing folder has been removed, the item is not checked out, or there was an attempt to associate the item with a portlet ID that was already associated with another content item

java.lang.IllegalArgumentException - if an invalid selection list value was set for an ISelectionListProperty

checkOutItem

public void checkOutItem(IContentItem contentItem)
                  throws ContentSecurityException,
                         ContentException,
                         java.rmi.RemoteException

Puts the content item into the checked-out state. A content item can only be checked out by one user at a time.

Parameters:

contentItem - the item to be checked out; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to check out the item

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

java.lang.IllegalStateException - if the content item has not been persisted, has been removed, or is already checked out

copyContentItem

public IContentItem copyContentItem(IContentItem contentItem,
                                    java.lang.String name)
                             throws NameAlreadyInUseException,
                                    ContentSecurityException,
                                    ContentException,
                                    java.rmi.RemoteException

Copies an IContentItem. Creates a copy of the an IContentItem with a new name in the same IFolder as the passed in content item.

The copied item will be checked in and will have a new version number and version history.

 // Create a new content item name from an existing, persisted item
 String nameOfCopy = originalContentItem.getName() + " Copy";
 IContentItem copyOfItem = contentItemManager.copyContentItem(originalContentItem, nameOfCopy);
 // Now a copy of the item exists in the same folder
 

Parameters:

contentItem - the content item to copy; cannot be null

name - the name of the copied item; 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.

Returns:

a new content item that is a copy of the original item with the new name

Throws:

ContentSecurityException - if the user does not have permission to copy the item

NameAlreadyInUseException - if there is already a content item with the given name in the same folder

ContentException - if the method call resulted in a Publisher exception

java.lang.IllegalStateException - if the content item to be copied has not been persisted or has already been removed

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

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

createContentItem

public IContentItem createContentItem(IFolder containingFolder,
                                      java.lang.String name,
                                      IDataEntryTemplate dataEntryTemplate)

Creates a new IContentItem with the given IDataEntryTemplate in the containing folder. This method does not create a persistent object. To create and persist a content item use this method to create a new item, then use IContentItem.setPropertyValue to set the property values, and IContentItemManager.checkInItem to persist the item.

The containing folder and the Data Entry Template must be persisted prior to calling this method otherwise an IllegalStateException will be thrown.

Parameters:

containingFolder - the folder the IContentItem will be created in; cannot be null

name - the name of the content item; 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.

dataEntryTemplate - the IDataEntryTemplate used for the content item; cannot be null

Returns:

an IContentItem that has not been persisted. IContentItemManager.checkInItem must be called to persist the item.

Throws:

java.lang.IllegalStateException - if the specified folder or the Data Entry Template has not been stored or has already been removed

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

expireContentItem

public void expireContentItem(IContentItem contentItem)
                       throws ContentSecurityException,
                              ContentException,
                              java.rmi.RemoteException

Expires a IContentItem so it can no longer be published. This method removes the published content for a content item from the publish target of Publisher. After an item is expired, unexpireContentItem can be used to re-publish the item. Content items cannot be expired multiple times consecutively.

 // Publish a persisted content item with
 // an attached Data Entry Template and
 // a Presentation Template associated
 contentItemManager.publishContentItem(contentItem);
 // Expire the published content (e.g. the published html file)
 // and mark the content item as expired
 contentItemManager.expireContentItem(contentItem);
 // Unexpire the published content and content item
 contentItemManager.unexpireContentItem(contentItem);
 // The content item can again be published
 

Parameters:

contentItem - the content item to expire; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to expire the item

java.lang.IllegalStateException - if the the content item has not been persisted or has already been removed

ContentException - if the method call resulted in a Publisher exception. For example, expiring a content item multiple times or expiring a content item that has not been published will cause this exception.

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

getContentItem

public IContentItem getContentItem(IFolder folder,
                                   java.lang.String name)
                            throws ContentSecurityException,
                                   ContentException,
                                   java.rmi.RemoteException

Retrieves an IContentItem in a folder by its name. The specified name is the full name of the content item. The name will be trimmed of leading and trailing whitespace and is case-insensitive for comparison. The name does not support wildcards.

 // Assuming a contentItem is persisted in containingFolder
 // Retrieve the item by name
 IContentItem sameContentItem = contentItemManager.getContentItem(containingFolder, contentItem.getName());
 // sameContentItem.getUUID() is the same as contentItem.getUUID()
 

Parameters:

folder - the folder containing the IContentItem; cannot be null

name - the name of the IContentItem; cannot be null, empty, or longer than 255 characters. The string used for the name will be trimmed of leading and trailing whitespace and is case-insensitive during comparison.

Returns:

the IContentItem in the folder with the specified name otherwise null

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 folder has not been stored or has already been removed

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

getContentItem

public IContentItem getContentItem(java.lang.String UUID)
                            throws ContentSecurityException,
                                   ContentException,
                                   java.rmi.RemoteException

Returns an IContentItem by its UUID.

Parameters:

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

Returns:

the IContentItem or null if the item does was not found.

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 content item

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

getContentItems

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

Returns all IContentItems contained in a given IFolder. Since all items shared the same access level as the containing folder, if a user has permission to access a folder, all items contained in that immediate folder will be returned.

Parameters:

folder - the folder to retrieve content items from; cannot be null

Returns:

an array of IContentItems in the specified folder or an empty array if there are no content items. 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 folder has not been stored or has already been removed

getContentItems

public IContentItem[] getContentItems(IFolder folder,
                                      IDataEntryTemplate dataEntryTemplate)
                               throws ContentSecurityException,
                                      ContentException,
                                      java.rmi.RemoteException

Returns an array of IContentItems using the specified IDataEntryTemplate in an IFolder. Only the top level of the folder is searched; any subfolders are not searched.

Parameters:

folder - the folder to retrieve content items from; cannot be null

dataEntryTemplate - the Data Entry Template; cannot be null

Returns:

an array of IContentItems of the specified IDataEntryTemplate in a folder or an empty array if no items are found. 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 Data Entry Template or the folder

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

java.lang.IllegalStateException - if the folder or the Data Entry Template has not been stored or one of them has been removed

previewContentItem

public void previewContentItem(IContentItem contentItem)
                        throws ContentSecurityException,
                               ContentException,
                               java.rmi.RemoteException

Previews the IContentItem and copies it to a preview target set internally by Publisher. The preview URL can be retrieved via IContentItem.getPreviewURL method. An IllegalStateException will be thrown if the IDataEntryTemplate of the item does not have an attached IPresentationTemplate. A ContentException will be thrown if the attached IPresentationTemplate contains invalid template text.

Refer to the Administrator Guide for AquaLogic Interaction Publisher for more details about previewing content items.

Parameters:

contentItem - the content item to be previewed; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to preview the item

java.lang.IllegalStateException - if the content item's IDataEntryTemplate does not have an attached IPresentationTemplate

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

publishContentItem

public void publishContentItem(IContentItem contentItem)
                        throws ContentSecurityException,
                               ContentException,
                               java.rmi.RemoteException

Publishes the IContentItem and copies it to a publishing target set in Publisher. This method should be called prior to retrieving the publish URL via IContentItem.getPublishURL method, otherwise an IllegalStateException will be thrown. An IllegalStateException will also be thrown if the IDataEntryTemplate of the item does not have an attached IPresentationTemplate. A ContentException will be thrown if the attached IPresentationTemplate contains invalid template text. IContentItem.isPublishable can be used to check if some of the above conditions are met. However, if IContentItem.isPublishable returns true it does not guarantee the content item will be published successfully.

Refer to the Administrator Guide for AquaLogic Interaction Publisher for more details about publishing content items.

For an example of using publishContentItem, refer to IContentItemManager

Parameters:

contentItem - the content item to be published; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to publish the item

java.lang.IllegalStateException - if the content item's IDataEntryTemplate does not have an attached IPresentationTemplate, the attached IPresentationTemplate contains invalid template text, or the content item has not been persisted or has been removed

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

publishContentItems

public void publishContentItems(IFolder folder,
                                boolean publishSubfolders)
                         throws ContentSecurityException,
                                ContentException,
                                java.rmi.RemoteException

Publishes all IContentItems in a folder and optionally publishes items in subfolders. All the published items will be copied to the publishing target set in Publisher for the folder in which they reside.

A best-effort is made to publish all items in the specified folder and, when publishSubfolders is true, for all subfolders. Failure to publish an item does not cause immediate failure and publishing is attempted for all remaining items. If a failure occurred during this best-effort publishing, a ContentException will be thrown.

If a folder contains both publishable and non-publishable items, the non-publishable items will cause failure. See the above best-effort publishing rules.

If any of the content items contained in a folder fail to be published, the ContentException thrown will contain information indicating which item(s) failed; however, the format of the exception message might vary in future versions. Parsing of the error message to retrieve information is not recommended. There is no reliable way to retrieve information about which items succeeded and which failed.

Publishing multiple content items is a blocking operation. Control will return to the caller after all items are published or a failure occurs. Extremely long running publishing operations may cause a connection timeout and an exception on the client but they will continue to publish in Publisher.

Refer to IContentItem.publishContentItem for details about publishing individual content items and the Administrator Guide for AquaLogic Interaction Publisher for general information about publishing a content item.

Parameters:

folder - the folder containing zero or more items to be published; cannot be null. Publishing empty folders has no effect.

publishSubfolders - if true, publish all content items in sub-folders; otherwise only publish content items in the immediate folder

Throws:

ContentSecurityException - if the user does not have permission to publish content items

java.lang.IllegalStateException - if the the folder has not been persisted or has already been removed

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

removeContentItem

public void removeContentItem(IContentItem contentItem)
                       throws ContentSecurityException,
                              ContentException,
                              java.rmi.RemoteException

Deletes the IContentItem. Note: An item can be removed even if it is published. An IllegalStateException will be thrown if remove is called on a checked out content item.

Parameters:

contentItem - the content item to be deleted; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to delete the item

ContentException - if the method call resulted in a Publisher exception

java.lang.IllegalStateException - if the content item is checked out

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

undoCheckOutItem

public void undoCheckOutItem(IContentItem contentItem)
                      throws ContentSecurityException,
                             ContentException,
                             java.rmi.RemoteException

Puts a content item that is currently in the checked-out state into the non-checked-out state. All modifications to the checked out content item will be lost when the check-out is undone.

Parameters:

contentItem - the content item whose check-out is being undone; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to perform this operation

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

java.lang.IllegalStateException - if the item is not checked-out, has not been persisted, or has already been removed

unexpireContentItem

public void unexpireContentItem(IContentItem contentItem)
                         throws ContentSecurityException,
                                ContentException,
                                java.rmi.RemoteException

Re-publishes the IContentItem and removes the item from its expired state if expireContentItem has been previously called. The item must be in the expired state prior to calling this method, otherwise a ContentException will be thrown.

For an example of using unexpireContentItem, refer to expireContentItem(com.plumtree.remote.prc.content.item.IContentItem)

Parameters:

contentItem - the content item to un-expire and re-publish; cannot be null

Throws:

ContentSecurityException - if the user does not have permission to un-expire or publish the item

java.lang.IllegalStateException - if the content item has not been persisted, or has already been removed

ContentException - if the content item is not in the expired state, or 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