Sun Java System Content Delivery Server Customization Guide

The Sun Java System Content Delivery Server Content Management API provides an interface between the 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).

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 the 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.
• 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, 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 the 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, the 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. The 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 the 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 the Content Delivery Server for information on the selected content item.

3. The 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.

4. The Content Delivery Server passes the detailed information about the content item 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 the 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 the 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 the 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 the 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()

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

This method is called by the 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.

4.2.2 getContentInfos()

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

This method is called by the 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()

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

This method is called by the Content Delivery Server when the subscriber initiates a request to download the content descriptor to a device. The 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 the Content Delivery Server for delivery to the subscriber.

4.2.4 getContentBinary()

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

This method is called by the 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 the Content Delivery Server.

---

4.3 Using the Content Management API

The classes for the Content Management API are available in cdsapi.jar, which is found in the $CDS_HOME/deployment/deployment-name/lib/cdslib directory. The cdsapi.jar file and the foundation.jar file must be in your classpath when you compile your adapter.

To make your adapter available to the Content Delivery Server, follow these steps:

1. Create a JAR file for your adapter.

2. Place the JAR file in the $CDS_HOME/deployment/deployment-name/lib/external directory.

3. Open the security.config file in the $CDS_HOME/deployment/deployment-name/conf directory.

4. 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 the Content Delivery Server and must appear first.

5. 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.content.external.SunContentManager

module.security.contentmanager=myapps.adapters.ContentManagerImpl

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

7. Save your changes.

8. Restart the Content Delivery Server 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

819-3213-10

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