Sun Java System Content Delivery Server Customization Guide

The Sun Java System Content Delivery Server Content Management API provides an interface between Content Delivery Server and your content management system. Use this API to write a content management adapter that instruments the content binary or alters the content information at the time that content is sent to a subscriber’s device. For example, you can create a content management adapter that adds code to handle Digital Rights Management (DRM) or adds a watermark to a preview file.

The time needed by the content management adapter to process the calls received can delay the delivery of the content to the subscriber. As much as possible, limit the use of the Content Manager API to operations that do not add a lot of overhead.

The Content Management API consists of the following elements:

• ContentManager - Interface that you implement to integrate Content Delivery Server with your content management system. The ContentManager interface provides several methods for accessing the information about the content.
• ContentInfo - Class that contains the information for a content object, such as the content descriptor and binary, the MIME type of the content descriptor and binary, the content size and type (for example, MIDlet, ringtone, and so on) and the transaction details, such as one-step or two-step download.
• ContentPreview - Class that contains the information for a preview file, such as the MIME type of the file, the binary, the date last modified, and other attributes.
• MimeType - Class that contains the information for a MIME type, such as the file extension and MIME type string.
• ContentException - Exception that is thrown by the Content Management API. Use this class to report errors in processing the information about content or in a purchase transaction.
• ContentConstants - Class that defines the key values used by the ContentInfo object to access content metadata.

For additional information on these classes and interfaces, see the HTML output of the Javadoc tool at $CDS_HOME/javadoc/cdsapi/index.html.

---

4.1 General Process Flow

The Content Management API handles the communication between Content Delivery Server and the external content management system or DRM server. The details of the content and transaction are maintained in a ContentInfo object. Use this API to access and manipulate the information about content at the time it is delivered to subscribers.

This section describes the flow of information between the device, Content Delivery Server, and the content management adapter. The following topics are discussed:

• Obtaining a List of Content
• Obtaining Content Details
• Downloading Content

4.1.1 Obtaining a List of Content

A request for a list of content is initiated when the subscriber clicks a content heading under Categories in the Subscriber Portal. The following actions occur to fulfill the request:

1. The subscriber’s device sends a request to Content Delivery Server for the information about the content items in the selected category.

2. Content Delivery Server creates the initial ContentInfo objects for the items in the list, based on information in the Content Delivery Server database. This information is shown to subscribers or used by Content Delivery Server.

3. Content Delivery Server calls getContentInfos and passes ContentInfo objects for the items in the list.

Your implementation of getContentInfos can alter the content information as needed for your system. Modify only information that is shown to subscribers in the list of content at this time.

4. Content Delivery Server returns the list of content items for that category and additional information to the subscriber’s device.

5. The Subscriber Portal displays the list in the Results section of the page.

4.1.2 Obtaining Content Details

A request for detailed information about a specific item of content is initiated when the subscriber clicks either the name of a content item or More Details in the Results page of the Subscriber Portal. The following items describe the transaction steps for obtaining content details:

1. The subscriber clicks the name of a particular content item or More Details in the Results page of the Subscriber Portal.

2. The subscriber’s device sends a request to Content Delivery Server for information on the selected content item.

3. Content Delivery Server calls getContentInfo for a single item. Your implementation of the method can return detailed information about the content, such as its binary and descriptor MIME type, its content size and type (ringtone or MIDlet, for example), and the transaction details. You can also modify any preview files associated with the item.

4. Content Delivery Server passes the detailed information about the content item and any preview files to the subscriber’s device.

4.1.3 Downloading Content

The process of obtaining content is initiated when subscribers choose to purchase content from their device. Typically, the content is instrumented before it is delivered to the subscriber. The instrumentation can be based on a number of factors, such as the subscriber’s phone type (CDMA or GSM), pricing model (subscription or usage), content type, or other characteristics. The following items describe the transaction steps for downloading content:

1. The subscriber chooses the desired content item in the Subscriber Portal and clicks Download Now. The subscriber must be accessing the Subscriber Portal from a device, not a PC.

2. For two-step downloads, the device sends a request to Content Delivery Server to download the content descriptor.

3. Content Delivery Server generates the initial ContentInfo object for the requested content item.

4. Content Delivery Server retrieves the content binary, the descriptor, and their MIME types from the Content Delivery Server database, and passes them to the content management system.

5. Content Delivery Server calls getContentDescriptor to process the content details and make the appropriate updates to the descriptor file.

6. The content management system returns the updated version of the descriptor file that contains the values that are delivered to the subscriber.

7. Content Delivery Server passes the updated descriptor file to the subscriber’s device.

8. The device sends a request to Content Delivery Server for the content binary. One of the ways this occurs is when a subscriber clicks a URL displayed on the device.

9. Content Delivery Server populates the ContentInfo object with the content binary and its MIME type, and passes the object to the content management adapter.

10. Content Delivery Server calls getContentBinary to create an updated content binary file.

11. The content management adapter instruments the content and passes the updated content binary file and binary MIME type back to Content Delivery Server.

12. Content Delivery Server passes the updated content to the subscriber’s device.

---

4.2 ContentManager Interface

The ContentManager interface provides the interface between Content Delivery Server and your content management system or DRM server. It provides methods that you can implement to modify the content binary, the descriptor, and other information, before they are delivered to the subscriber.

The methods in this class take a ContentInfo object and a BillingInfo object as parameters. The ContentInfo object contains the content binary, the content descriptor file, and information such as the content binary and descriptor MIME type, the content size and type, and the number of steps required to download the content.

The BillingInfo object contains transaction details, such as the pricing model. This object also contains subscriber information. For more information on billing and BillingInfo objects, see Chapter 3.

The ContentManager interface is in the com.sun.content.server.content package.

4.2.1 getContentInfo Method

abstract ContentInfo getContentInfo(ContentInfo inContentInfo, BillingInfo inBillingInfo) throws ContentException

This method is called by Content Delivery Server when the subscriber requests information on a single item of content. The ContentInfo object contains information about the initial content item, such as the content binary and descriptor MIME type, estimated content size and type (ringtone or MIDlet, for example), and how many steps are needed to download the content.

To modify preview files, use the ContentInfo.getValue method with the KEY_CONTENT_PREVIEWS key to get the original collection of ContentPreview objects in the ContentInfo object. Each ContentPreview object represents one preview file. If the content item has no preview files, the method returns an empty collection. If neither the flag for returning resource binaries nor the flag for returning resource URLs was included when the content details were requested from the Subscriber Portal, the method returns null.

After you modify the preview files, use the ContentInfo.setValue method with the KEY_CONTENT_PREVIEWS key to save the collection of modified ContentPreview objects in the ContentInfo object that is returned to Content Delivery Server.

4.2.2 getContentInfos Method

abstract ContentInfo[] getContentInfos(ContentInfo[]inContentInfos, BillingInfo[] inBillingInfos) throws ContentException

This method is called by Content Delivery Server when the subscriber requests information on a list of content items in a category. Code your implementation to alter only the information that is shown in the list of content.

4.2.3 getContentDescriptor Method

abstract ContentInfo getContentDescriptor(ContentInfo inContentInfo, BillingInfo inBillingInfo) throws ContentException

This method is called by Content Delivery Server when the subscriber initiates a request to download the content descriptor to a device. Content Delivery Server retrieves the content descriptor file. The content descriptor and binary are passed to the content management system. The content management system can update the content descriptor information, including the size, and return it to Content Delivery Server for delivery to the subscriber.

4.2.4 getContentBinary Method

abstract ContentInfo getContentBinary(ContentInfo inContentInfo, BillingInfo inBillingInfo) throws ContentException

This method is called by Content Delivery Server when the subscriber initiates a request to download content binary to a device. The binary might be passed to the content management adapter when getContentBinary is called. The instrumented content binary to be delivered to the subscriber must be returned to Content Delivery Server.

---

4.3 Using the Content Management API

The classes for the Content Management API are available in cdsapi.jar. The cdsapi.jar file must be in your classpath when you compile your content management adapter. For convenience, a copy of all Content Delivery Server JAR files are available in the $CDS_HOME/dist/cds/staging/jar directory. Use this staging area in your classpath when compiling the adapter that you create.

Making your adapter available to Content Delivery Server depends on the application server you are using and whether you have already deployed. To make your adapter available, follow these steps:

1. Create a JAR file for your adapter.

2. For all application servers, place the JAR file in the $CDS_HOME/dist/cds/lib/external directory.

The adapter is now included in all future deployments.

3. If you have existing deployments that need to use the adapter, place the JAR file in the $CDS_HOME/deployment/deployment-name/lib/external directory for each deployment.

If you are using WebLogic Server, the classpath is handled for you.

If you are using Sun Java System Application Server, update the classpath for each deployment:

a. Back up the $CDS_HOME/deployment/deployment-name/sun/domains/cdsdomain/config/domain.xml file before editing it so you can recover from any errors that might be introduced during editing.

b. Edit domain.xml and modify the java-config element to add the absolute path for your JAR file to the classpath-suffix attribute.

c. Save your changes.

4. Edit the security.config file in the $CDS_HOME/deployment/deployment-name/conf directory:

a. Add a property named module.security.contentmanager after the existing property with the same name.

The existing module.security.contentmanager property points to the implementation used by the DRM agents provided with Content Delivery Server and must appear first.

b. Set the property that you added to the fully qualified package and class name of your implementation of the ContentManager interface.

The following code shows sample settings for the module.security.contentmanager property:

module.security.contentmanager=
com.sun.content.server.fulfillment.content.external.SunContentManager
module.security.contentmanager=myapps.adapters.ContentManagerImpl

c. Set the module.security.contentmanager.enabled property to true to indicate that an adapter is available for Content Delivery Server to call.

d. Save your changes.

5. Restart any existing deployment to make it aware of the new JAR file.

---

4.4 Sample Content Management Adapter

CODE EXAMPLE 4-1 shows a sample implementation of the ContentManager interface.

import com.sun.content.server.content.*;
import com.sun.content.server.billing.BillingInfo;
 
public class ContentManagerImpl implements ContentManager
{
  public ContentInfo getContentInfo(
    ContentInfo inContentInfo,
    BillingInfo inBillingInfo)
  throws ContentException
  {
    // Update the information that is shown to the user
    return inContentInfo;
  }
 
  public ContentInfo[] getContentInfos(
    ContentInfo[] inContentInfos,
    BillingInfo[] inBillingInfos)
  throws ContentException
  {
    // Iterate through each ContentInfo object and update the
    // information that is shown to the user when a list of
    // content is shown.
    return inContentInfos;
  }
 
  public ContentInfo getContentDescriptor(
    ContentInfo inContentInfo,
    BillingInfo inBillingInfo)
  throws ContentException
  {
    // Update content download descriptor
    return inContentInfo;
  }
 
  public ContentInfo getContentBinary(
    ContentInfo inContentInfo,
    BillingInfo inBillingInfo)
  throws ContentException
  {
    // Update content binary, binary MIME type
    return inContentInfo;
  }
}

Sun Java System Content Delivery Server Customization Guide

820-1941-10

Copyright © 2008, Sun Microsystems, Inc. All Rights Reserved.