Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

public interface IContentItemManager

`IContentItemManager` is an interface for managing `IContentItem` instances. It 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 Content Server 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 `IContentItem`s contained in a given `IFolder`.
`IContentItem[]` | `getContentItems(IFolder folder, IDataEntryTemplate dataEntryTemplate)` Returns an array of `IContentItem`s using the specified `IDataEntryTemplate` in an `IFolder`.
`void` | `previewContentItem(IContentItem contentItem)` Previews the `IContentItem` and copies it to a preview target set internally by Content Server.
`void` | `publishContentItem(IContentItem contentItem)` Publishes the `IContentItem` and copies it to a publishing target set in Content Server.
`void` | `publishContentItems(IFolder folder, boolean publishSubfolders)` Publishes all `IContentItem`s in a folder and optionally publishes items in sub-folders.
`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 Content Server 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 Content Server 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 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.
  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 Content Server 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 need to 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 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.
    `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 Content Server. 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 Content Server 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` 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 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 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 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. The UUID of an object can be obtained using the `getUUID` method in the `IContentItem` class; cannot be `null`, empty or longer than 255 characters.
  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 Content Server 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 `IContentItem`s 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 `IContentItem`s 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 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 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 `IContentItem`s using the specified `IDataEntryTemplate` in an `IFolder`. Only the top level of the folder is searched, sub-folders 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 `IContentItem`s 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 Content Server 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 Content Server. 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 Content Server 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 Content Server 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 Content Server. 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 Content Server 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 Content Server 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 `IContentItem`s in a folder and optionally publishes items in sub-folders. All the published items will be copied to the publishing target set in Content Server 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) fail; 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 Content Server.

  Refer to `IContentItem.publishContentItem` for details about publishing individual content items and the Administrator Guide for Content Server 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 Content Server 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 that 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 Content Server 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 Content Server 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 Content Server exception.
    `java.rmi.RemoteException` - if there was a communication problem during the execution of the remote method call.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

For additional information on the IDK, including tutorials, blogs, code samples and more,see the AquaLogic User Interaction Developer Center on BEA dev2dev.

Copyright ©2007 BEA Systems, Inc. All Rights Reserved.