Event Service API

This chapter describes the Sun Java System Content Delivery Server Event Service API. The Event Service API consists of the following external interfaces:

The Event Service propagates messages that come through the Event Queue to any interested event listener that has subscribed to the topics published by the Event Service. The Event Service also stores the event data in the Content Delivery Server database. You can use either a database client or the JMS client application approach. Both approaches have access to the same information in near real time.

Use the Event Service API to write an application that listens for specific events and takes action as needed by your enterprise. For example, this API can be used to write a custom billing adapter that processes purchase events and charges subscribers after content is purchased.

FIGURE 2-1 is a simplified representation of the general systems and components that interact with the Event Service, which illustrates how information is passed through the various system interactions.

Content Delivery Server Catalog Manager and Vending Manager components publish appropriate messages to a JMS queue. These messages are retrieved and processed by the Event Service. Any component within Content Delivery Server can publish events to the Event Service. Because event publishing is an asynchronous operation, the publishing component continues processing as soon as the message is sent.

The Event Service runs as a separate process within the Content Delivery Server environment. The Event Service performs the following tasks:

The message can then be processed and possibly resubmitted to the Event Queue. The message is still acknowledged as successfully processed by the Event Service.

The current implementation of the Event Service API uses JMS Point-to-Point (PTP) messaging domain, where various publishers publish to a single queue and an instance of the Event Service JMS client application processes the messages.

After the events are successfully processed by the Event Service, they are placed into the database. When the Event Service is deployed with a Vending Manager, events are placed in the Vending Manager database schema. When the Event Service is deployed with only a Catalog Manager, the events are placed in the Catalog Manager database schema. The data model used to store these messages is described in Section 2.1.1, Event Tables.

2.1 Database Client Application

Data resides in a standard relational database. A set of views enables developers to write applications in any programming language that can query an Oracle database. For example, these applications can be written in the Java programming language, C++, or Visual Basic.

2.1.1 Event Tables

This section describes the tables that hold the event data after the event is processed by the Event Service. As an integrator, you have access to the data in these tables.

See the Sun Java System Content Delivery Server Installation Guide for information on the database configuration file.

2.1.1.1 CDS_EVENT Table

The CDS_EVENT table holds a record for each event processed successfully by the Event Service. This table is actively updated as events are processed.

TABLE 2-1 `CDS_EVENT` Table
Column Name	Data Type	Description
`CDS_EVENT_ID`	`NUMBER(18)`	Unique, system-generated number used as the record ID. This field is the table’s primary key.
`CDS_EVENT_DATE`	`DATE`	Timestamp indicating when the event message was generated.
`CDS_EVENT_TYPE_ID`	`NUMBER(18)`	Foreign key to the `CDS_EVENT_TYPE` table.
`EVENT_SOURCE_ID`	NUMBER(18)	Foreign key to the `EVENT_SOURCE_TYPE` table.
`SVR_INSTANCE_ID`	NUMBER(18)	System data.
`SVR_SESSION_ID`	`VARCHAR2(128)`	System data.
`SUB_SYSTEM_ID`	`VARCHAR2(80)`	The MSISDN associated with the session and event. If the MSISDN is not known, this column is null.
`CDS_USER_ID`	`NUMBER(18)`	The Content Delivery Server User ID associated with the session and event. If a user is not logged in, this column might be null.
`VENDOR_ID`	`NUMBER(18)`	Content provider ID.
`CONTENT_ID`	`NUMBER(18)`	Foreign key to the Content table.
`RAW_EVENT_MESSAGE`	`CLOB`	Raw event message XML.
`CREATE_DATE`	`DATE`	System data.
`MOD_DATE`	`DATE`	System data.
`LOCK_VERSION`	`NUMBER(1)`	System data.

2.1.1.2 CDS_EVENT_TYPE Table

The CDS_EVENT_TYPE table is a static table that contains Event Type definitions. These definitions are listed in Section 2.3, Events and Event Data.

TABLE 2-2 `CDS_EVENT_TYPE` Table
Column Name	Data Type	Description
`CDS_EVENT_TYPE_ID`	`NUMBER(18)`	Unique, system-generated number used as the record ID. This field is the table’s primary key.
`CDS_EVENT_GROUP_ID`	`NUMBER(18)`	Foreign key to the `EVENT_GROUP` table. Used to group Event Types.
`CDS_EVENT_TYPE_NAME`	`VARCHAR2(80)`	Human-readable name.
`DESCRIPTION`	`VARCHAR2(80)`	Description of the particular Event Type.
`LONG_DESCRIPTION`	`VARCHAR2(255)`	Long description of the Event Type, if needed.
`IS_ACTIVE`	`NUMBER(1)`	Flag that indicates if this is an active event type.
`CREATE_DATE`	`DATE`	System data.
`MOD_DATE`	`DATE`	System data.
`LOCK_VERSION`	`NUMBER(1)`	System data.

2.1.1.3 EVENT_SOURCE_TYPE_ID Table

The EVENT_SOURCE_TYPE_ID table is a static table that contains Event Source Type definitions.

TABLE 2-3 `EVENT_SOURCE_TYPE_ID` Table
Column Name	Data Type	Description
`EVENT_SOURCE_TYPE_ID`	`NUMBER(18)`	Unique, system-generated number used as the record ID. This field is the table’s primary key.
`EVENT_SOURCE_TITLE`	`VARCHAR2(255)`	Human-readable name.
`CREATE_DATE`	`DATE`	System data.
`MOD_DATE`	`DATE`	System data.
`LOCK_VERSION`	`NUMBER(1)`	System data.

2.1.2 Reporting Tools

You can use any database reporting tool that connects to an Oracle database to build various types of reports from this data such as Crystal Reports or Jasper Reports. See Section 1.5, “Setting Up Custom Reports,” in the Sun Java System Content Delivery Server Integration and Configuration Guide for additional information on report data.

2.2 JMS Client Application

In addition to the SQL-based interface to the event data, you can implement a JMS client application that interfaces directly with the Event Service through a JMS topic. While more difficult to implement, this approach provides greater flexibility for using the events generated by Content Delivery Server.

To successfully use this API to integrate with the Event Service, you need to be familiar with writing JMS client applications and understand the Publish/Subscribe Messaging domain described in the JMS specification for the Java 2 Platform, Enterprise Edition (J2EE^TM platform). Any number of JMS client applications can subscribe to the messages published by the Event Service by using the Publish/Subscribe messaging model.

2.3 Events and Event Data

This section provides information on the events and the event data provided by the Event Service. Both the database and JMS client applications use this information to filter and process the events. Your client application can handle each type of event as needed by your enterprise. For example, premium SMS billing can be performed when the sms_content_push_sent event is received.

TABLE 2-4 Events
Event	Description
`content_changed`	A Catalog Manager administrator made a change to the content.
`content_purchased`	A subscriber purchased an item of content or downloaded a free item.
`content_refunded`	A refund was issued for an item of content.
`download_deleted`	Downloaded content was deleted from a device.
`download_error`	The device indicated that an error occurred when content was downloaded.
`download_initiated`	A subscriber started downloading content.
`download_install_notified`	A device confirmed that the download was successful.
`external_content_updated`	Externally hosted content was updated.
`gift_cancelled`	A gift subscription was cancelled.
`gift_download_confirm`	A gift was downloaded by the recipient.
`gift_download_deleted`	A gift that was downloaded by the recipient was deleted.
`gift_download_error`	An error occurred when a gift was downloaded.
`gift_download_initiated`	The recipient of a gift started downloading it.
`gift_expired`	The gift expired.
`gift_purchased`	An item of content was purchased as a gift.
`gift_refunded`	A refund was issued for a gift purchased by the subscriber.
`gift_subscription_purchased`	A subscription to an item of content was purchased as a gift.
`gift_usage_purchased`	A number of uses of an item of content was purchased as a gift.
`mms_push_sent`	An MMS message was sent.
`pricing_changed`	The pricing of one or more items of content was changed using the Category Price Edit feature.
`sms_content_push_sent`	Binary content was sent in an SMS message. Use this event to trigger premium SMS billing.
`sms_push_sent`	An SMS message was sent.
`sms_received`	An SMS message was received.
`smtp_push_sent`	An SMTP message was sent.
`status_changed_to_deleted`	The status of an item of content was changed to Deleted.
`status_changed_to_denied`	The status of an item of content was changed to Denied.
`status_changed_to_new`	The status of an item of content was changed to New.
`status_changed_to_pending`	The status of an item of content was changed to Pending.
`status_changed_to_published`	The status of an item of content was changed to Published.
`status_changed_to_testing`	The status of an item of content was changed to Testing.
`submission_failed`	Submitted content was rejected by Content Delivery Server.
`submission_successful`	Submitted content was accepted by Content Delivery Server.
`subscriber_registered`	A subscriber successfully registered.
`subscription_cancelled`	A subscription for an item of content was cancelled.
`subscription_purchased`	A subscription for an item of content was purchased.
`usage_purchased`	A number of uses were purchased for an item of content.
`validation_passed`	Submitted content was successfully processed by the submission verifier workflow.
`validation_failed`	Submitted content failed a step in the submission verifier workflow.
`wap_push_sent`	A WAP message was sent.

The following table lists information that can be included with an event. Each event contains only parameters that are relevant to that event.

TABLE 2-5 Event Data
Parameter	Data Type	Description
`billing-ticket`	String	The billing ticket for this transaction.
`campaign_coupon`	String	The coupon code for a campaign.
`campaign_id`	String	The unique identifier for the campaign.
`catalog-res-id`	String	The unique identifier for the content edition.
`content_binary_mimetype`	String	The MIME type of the content.
`content_class_id`	String	The unique identifier for the content item.
`content_description`	String	The long description of the content.
`content_drm_type_id`	String	The string that identifies the DRM method used to protect the content.
`content_short_description`	String	The short description of the content.
`content-id`	String	The unique identifier for the content that was purchased. This value is the same as `catalog-res-id`.
`content_name`	String	The name of the content.
`current-status`	String	The current status of this transaction.
`date`	Date	The date on which the transaction occurred.
`destination-address`	String	The address to which content is sent, for example, the MSISDN of the subscriber who requested content.
`developer-content-id`	String	The unique identifier used by the developer to identify the content.
`developer-id`	String	The unique identifier for the developer of the content.
`developer_name`	String	The name of the developer who submitted the content.
`download-confirm`	Boolean	The flag that indicates if a confirmation is required after a successful download.
`download-count`	Integer	The number of times the content can be downloaded for the price paid.
`download-current-count`	Integer	The number of times the subscriber downloaded this content, including this time.
`download-expiration`	Boolean	The flag that indicates if the download period is expired.
`download-period`	Integer	The time period during which the content can be downloaded without additional charge to the subscriber.
`download-price`	Float	The price of the content purchased.
`download-purchase`	Boolean	The flag that indicates this is a purchase request.
`download-recurring`	Boolean	The flag that indicates if the subscriber is charged for each download.
`event-log`	String	The name of the event log.
`event-msg`	String	The message issued with the event.
`event-source-type-id`	Integer	The number that identifies the source of the event.
`event-type`	Integer	The numeric representation of the event that occurred.
`event-type-id`	String	The type of event that occurred.
`external_content_id`	String	The tag used by the billing system to identify content.
`external_group_id`	String	The tag used by the billing system to identify the group to which the content belongs.
`external-request-text`	String	The text of the request from the subscriber, for example, the MO push request content.
`gift_message`	String	The message included with the gift.
`gifted_current_downloads`	Integer	The number of times the recipient downloaded this gift, including this time.
`gifted_current_subscriptions`	Integer	The number of subscription periods used by the recipient, including this period.
`gift_download_date`	Date	The date that the gift was first downloaded by the recipient.
`gift_expiration_date`	Date	The date by which the gift must be claimed by the recipient.
`gift_purchase_date`	Date	The date the gift was purchased by the giver.
`gifted_downloads`	Integer	The number of downloads included in the gift.
`gifted_subscriptions`	Integer	The number of subscription periods included in the gift.
i`s_on_device`	Boolean	The flag that indicates if the content is already on the device.
`is-prepay`	Boolean	The flag that indicates if the subscriber prepaid for the content.
`locale`	String	The subscriber’s locale.
`msisdn`	String	The MSISDN for the subscriber device.
`pricingoption_key`	String	String that identifies the pricing option.
`pricingoption_name`	String	Name of the pricing option.
`push-msgtext`	String	The message sent to the subscriber’s device or email.
`recipient_locale_code`	String	The locale of the intended recipient of the content.
`recipient_login_id`	String	The login ID of the intended recipient of the content.
`recipient_mobile_id`	String	The mobile ID of the intended recipient of the content.
`recipient_unique_device_id`	String	The unique device ID of the intended recipient.
`server-id`	String	The unique identifier for the Vending Manager.
`session-id`	String	The string that identifies the subscriber’s session.
`source-address`	String	The address of the external entity from which the message was received, for example, the MSISDN of the SMSC.
`streaming_content_upload_failed`	String	The message that indicates that uploading streaming content to the streaming server failed.
`streaming_content_delete_failed`	String	The message that indicates that deleting streaming content from the streaming server failed.
`subscription-expiration`	Date	The date that the subscription period ends.
`subscription-frequency`	String	How often the subscription price is charged.
`subscription-recurring`	Boolean	The flag that indicates if the subscriber is automatically charged for the next period when the current subscription period ends.
`subscription-price`	Float	The price of the subscription period.
`timestamp`	Timestamp	The time at which the transaction occurred.
`unique-device-id`	String	The unique identifier for the device used.
`usage-count`	Integer	The number of uses allowed for the price specified for `usage-price`.
`usage-price`	Float	The price charged for the number of uses specified for `usage-count`.
`user-id`	String	The unique identifier for the user who initiated the transaction.
`username`	String	The login name for the subscriber.
`vending-res-id`	String	The tag by which the Vending Manager identifies the content.

2.4 Using the Event Service API

To use the Event Service API, you need either a database client application or a JMS client application. This section provides information on developing the type of client that you need for your system.

2.4.1 Developing a Database Client Application

The application must obtain a connection to the database to directly query an Oracle database. The specifics of how that is done depends on your database server and your client application’s local environment.

2.4.2 Developing a JMS Client Application

To compile your JMS client, include in your classpath the Java Archive (JAR) file for JMS. This file is located at /cds-home/deployment/deployment-name/lib/jms.jar where cds-home is the directory in which you installed Content Delivery Server and deployment-name is the name that you gave the deployment.

1. Include in your classpath the JAR files for the components in the following table.

TABLE 2-6 Files Required for Execution
JAR File	Location^{^[1]}
JMS	`/`cds-home`/deployment/`deployment-name`/lib/external/javax.jms.jar`
File-system context (required only if you are using Sun Java System Application Server)	`/`sun-as-home`/imq/lib/fscontext.jar`

2.5 Sample Implementation of MessageListener

The following code example is an implementation of the MessageListener class. This sample shows what to do to receive billing events from the CDS billing topic.

CODE EXAMPLE 2-1 Sample `MessageListener` Implementation
package com.sun.content.server.eventservice.subscriber.internal; import java.util.Properties; import javax.jms.; import javax.naming.Context; import javax.naming.InitialContext; /* * Attach to the CDS billing topic to receive billing events / public class CDSBillingSubscriber implements ExceptionListener, MessageListener { private static final String kUSAGE = "CDSBillingSubscriber {JNDI Factory} {JNDI URL}"; private static final String kTOPIC_CONNECTION_FACTORY_NAME = "cds.jms.TopicConnectionFactory"; private static final String kTOPIC_NAME = "cds.messaging.billingTopic"; private TopicConnection fConnection; private TopicSession fSession; private boolean fDone = false; public static void main(String[] args) { if (args.length != 2) { System.out.println(kUSAGE); System.exit(-1); } try { CDSBillingSubscriber billingSubscriber = new CDSBillingSubscriber(); billingSubscriber.initJMS(args[0], args[1]); while (!billingSubscriber.fDone) { synchronized (billingSubscriber) { System.out.println("Waiting..."); billingSubscriber.wait(1000 10); } } } catch (Exception e) { e.printStackTrace(); System.exit(-1); } } /** * Initialize the JMS topic subscriber * * @param jndiFactory the JNDI context factory * @param jndiProviderUrl the JNDI connection URL * * @throws Exception / private void initJMS(String jndiFactory, String jndiProviderUrl) throws Exception { // Initialize the context Properties props = new Properties(); props.put(Context.INITIAL_CONTEXT_FACTORY, jndiFactory); props.put(Context.PROVIDER_URL, jndiProviderUrl); InitialContext context = new InitialContext(props); // Get the topic connection factory and topic TopicConnectionFactory topicConnectionFactory = (TopicConnectionFactory )context.lookup(kTOPIC_CONNECTION_FACTORY_NAME); Topic topic = (Topic )context.lookup(kTOPIC_NAME); // Initialize the topic connection fConnection = topicConnectionFactory.createTopicConnection(); fConnection.setExceptionListener(this); // Get a session and subscriber fSession = fConnection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE); TopicSubscriber subscriber = fSession.createSubscriber(topic); subscriber.setMessageListener(this); fConnection.start(); } /* * Listen for messages asynchronously. Simply print them. * * @param message / public void onMessage(Message message) { try { // simply prints the message TextMessage txtMsg = (TextMessage )message; System.out.println(txtMsg.getText()); } catch (JMSException e) { e.printStackTrace(); } } /* * Listen for exceptions and stop waiting * * @param jmse */ public void onException(JMSException jmse) { jmse.printStackTrace(); fDone = true; this.notifyAll(); } }

CODE EXAMPLE 2-1 Sample MessageListener Implementation


package com.sun.content.server.eventservice.subscriber.internal;
 
import java.util.Properties;
 
import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
 
/**
 * Attach to the CDS billing topic to receive billing events
 */
public class CDSBillingSubscriber
        implements ExceptionListener, MessageListener
{
    private static final String kUSAGE = "CDSBillingSubscriber {JNDI Factory} {JNDI URL}";
    private static final String kTOPIC_CONNECTION_FACTORY_NAME = "cds.jms.TopicConnectionFactory";
    private static final String kTOPIC_NAME = "cds.messaging.billingTopic";
 
    private TopicConnection                     fConnection;
    private TopicSession                        fSession;
    private boolean                             fDone = false;
 
    public static void main(String[] args)
    {
        if (args.length != 2)
        {
            System.out.println(kUSAGE);
            System.exit(-1);
        }
 
        try
        {
            CDSBillingSubscriber    billingSubscriber = new CDSBillingSubscriber();
            billingSubscriber.initJMS(args[0], args[1]);
 
            while (!billingSubscriber.fDone)
            {
                synchronized (billingSubscriber)
                {
                    System.out.println("Waiting...");
                    billingSubscriber.wait(1000 * 10);
                }
            }
        }
        catch (Exception e)
        {
            e.printStackTrace();
            System.exit(-1);
        }
    }
 
 
    /**
     * Initialize the JMS topic subscriber
     *
     * @param jndiFactory       the JNDI context factory
     * @param jndiProviderUrl   the JNDI connection URL
     *
     * @throws Exception
     */
    private void initJMS(String jndiFactory, String jndiProviderUrl)
        throws Exception
    {
        //  Initialize the context
        Properties  props = new Properties();
        props.put(Context.INITIAL_CONTEXT_FACTORY, jndiFactory);
        props.put(Context.PROVIDER_URL, jndiProviderUrl);
        InitialContext  context = new InitialContext(props);
 
        //  Get the topic connection factory and topic
        TopicConnectionFactory  topicConnectionFactory =
                (TopicConnectionFactory )context.lookup(kTOPIC_CONNECTION_FACTORY_NAME);
        Topic   topic = (Topic )context.lookup(kTOPIC_NAME);
 
        //  Initialize the topic connection
        fConnection = topicConnectionFactory.createTopicConnection();
        fConnection.setExceptionListener(this);
 
        //  Get a session and subscriber
        fSession = fConnection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
        TopicSubscriber subscriber = fSession.createSubscriber(topic);
        subscriber.setMessageListener(this);
 
        fConnection.start();
    }
 
 
    /**
     * Listen for messages asynchronously. Simply print them.
     *
     * @param message
     */
 
    public void onMessage(Message message)
    {
        try
        {
            // simply prints the message
            TextMessage txtMsg = (TextMessage )message;
            System.out.println(txtMsg.getText());
        }
        catch (JMSException e)
        {
            e.printStackTrace();
        }
    }
 
    /**
     * Listen for exceptions and stop waiting
     *
     * @param jmse
     */
    public void onException(JMSException jmse)
    {
        jmse.printStackTrace();
        fDone = true;
        this.notifyAll();
    }
}

^{1 (TableFootnote) cds-home is the directory in which you installed Content Delivery Server. deployment-name is the name that you gave the deployment. sun-as-home is the directory in which you installed Sun Java System Application Server.}

2.1 Database Client Application

2.1.1 Event Tables

2.1.1.1 `CDS_EVENT` Table

2.1.1.2 `CDS_EVENT_TYPE` Table

2.1.1.3 `EVENT_SOURCE_TYPE_ID` Table

2.1.2 Reporting Tools

2.2 JMS Client Application

2.3 Events and Event Data

2.4 Using the Event Service API

2.4.1 Developing a Database Client Application

2.4.2 Developing a JMS Client Application

2.5 Sample Implementation of `MessageListener`

2.1 Database Client Application

2.1.1 Event Tables

2.1.1.1 CDS_EVENT Table

2.1.1.2 CDS_EVENT_TYPE Table

2.1.1.3 EVENT_SOURCE_TYPE_ID Table

2.1.2 Reporting Tools

2.2 JMS Client Application

2.3 Events and Event Data

2.4 Using the Event Service API

2.4.1 Developing a Database Client Application

2.4.2 Developing a JMS Client Application

2.5 Sample Implementation of MessageListener

2.1.1.1 `CDS_EVENT` Table

2.1.1.2 `CDS_EVENT_TYPE` Table

2.1.1.3 `EVENT_SOURCE_TYPE_ID` Table

2.5 Sample Implementation of `MessageListener`