Confirm Service API

C H A P T E R 9

Confirm Service API

The Sun Java System Content Delivery Server Confirm Service API enables Content Delivery Server to handle confirmation messages sent after content is downloaded to a device. A confirm service adapter is needed only if you have devices defined to Content Delivery Server that are capable of sending confirmation messages, or if you are using a service that sends confirmation messages.

Content Delivery Server supports the following types of confirmation messages:

Messages sent through a Multimedia Messaging Service Center (MMSC) using MMS

Messages sent directly to Content Delivery Server using User Datagram Protocol (UDP)

The Confirm Service API consists of the following classes:

ConfirmServiceAdapter - Abstract class that you extend to connect to the external entity that delivers confirmation messages and to listen for messages.

ConfirmResponse - Class that contains the confirmation information received.

ConfirmServiceException - Exception that is thrown by the Confirm Service API.

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

9.1 General Process Flow

Content Delivery Server can send content in a multimedia message to devices that support the MMS standard. When a device receives content in an MMS message, a confirmation message is returned through the MMSC. The confirm service adapter that you write using the Confirm Service API sets up the connection between Content Delivery Server and the MMSC, and handles the confirmation messages from the MMSC.

If your system is set up to support services or devices that send UDP messages directly to Content Delivery Server, your confirm service adapter sets up Content Delivery Server to listen for and handle those confirmation messages.

9.2 `ConfirmServiceAdapter` Class

The ConfirmServiceAdapter class establishes the connection for confirmation messages, and passes the messages received to Content Delivery Server. Extend ConfirmServiceAdapter to create a confirm service adapter for your system.

The ConfirmServiceAdapter class is in the com.sun.content.server.confirmservice package.

9.2.1 `connect` Method

public abstract boolean connect() throws ConnectionFailedException

Use this method to connect Content Delivery Server to the MMSC , or to set up Content Delivery Server to receive UDP messages.

9.2.2 `init` Method

public void init(Properties properties) throws ConfirmServiceException

Use this method to initialize your implementation of this class, if needed. Implementation of this method is optional.

9.2.3 `listen` Method

public abstract void listen() throws ConfirmServiceException

Use this method to listen for confirmation messages. When a confirmation message is received, use the information in the message to create a ConfirmResponse object and call the messageReceived method.

The ConfirmResponse object requires the information shown in the following table.

TABLE 9-1 `ConfirmResponse` Parameters
Parameter	Description
`pushType`	The type of message received. Use one of the types defined in the `PushConstants` class (see Section 8.12, PushConstants Class.)
`messageID`	The ID assigned by the external entity to identify the message. For messages from an MMSC, the ID is assigned by the MMSC. The value can be null if, for example, UDP is used and the message is contained in a `responseObject`.
`responseStatus`	The status of the response. The value can be null.
`responseDescription`	The description of the response. The value can be null.
`responseObject`	Binary object that contains the confirmation message. The object can be null if, for example, the message is from an MMSC and is identified by a message ID.

9.2.4 `messageReceived` Method

protected void messageReceived(ConfirmResponse confirmResponse) throws ConfirmServiceException

Use this method to send the information received in the confirmation message to Content Delivery Server. Call this message from your implementation of the listen method.

9.3 Using the Confirm Service API

The classes for the Confirm Service API are available in the cdsapi.jar file. This file must be in your classpath when you compile your 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 ConfirmListener.properties file in the $CDS_HOME/deployment/deployment-name/conf directory.

a. Define another Confirm Service handler.

The following code example shows the statements to add to ConfirmListener.properties.

confirmservice.handler=handler-id
confirmservice.handler.handler-id.classname=adapter-name
confirmservice.handler.handler-id.processor.classname=confirm-processor-name
confirmservice.handler.handler-id.pushtype=push-type

handler-id is any unique string that identifies the handler that you are defining, adapter-name is the fully qualified name of the class for your implementation of the ConfirmServiceAdapter class. confirm-processor-name is one of the following values:

com.sun.content.server.confirmservice.mms.MMSConfirmProcessor - Use this value if your confirm service adapter works with an MMSC.

com.sun.content.server.confirmservice.udp.UDPConfirmProcessor - Use this value if your confirm service adapter works with UDP.

push-type is one of the following values:

mms - Use this value if your confirm service adapter works with an MMSC.

udp - Use this value if your confirm service adapter works with UDP.

b. Save your changes.

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

9.1 General Process Flow

9.2 ConfirmServiceAdapter Class

9.2.1 connect Method

9.2.2 init Method

9.2.3 listen Method