C H A P T E R  2

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.

FIGURE 2-1 Event Service Overview


Diagram of components that interact with the Event Service. This figure is described in the text.

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 (J2EETM 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.

The following table describes the events generated by the Event Service.


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.

is_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.

See Section 2.1.1, Event Tables for information on connecting to the database.

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.

To execute your JMS client, follow these steps:

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. Specify the following options for the execute command:


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();
    }
}

 


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.