This chapter describes the Sun Java System Content Delivery Server Event Service API. The Event Service API consists of the following external interfaces:
- A database schema for querying the event data directly from database client applications
- The Java Message Service (JMS) topics available for subscription by JMS client applications
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
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:
- Consumes all of the messages published by the various server components
- Extracts the context and details of the message and inserts the information into the database
- Sends an acknowledgement to the JMS queue upon successful processing of the message
- If an error occurs, puts the message into an error queue
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.
- If the Event Service is deployed with a Vending Manager, connect to the Oracle database using the user prefix_vs_app. prefix is the value specified for the Prefix element under the Vending element in the database configuration file used to create the database. Use the password that was specified for the Password element under the Vending element.
- If the Event Service is deployed with only a Catalog Manager, connect to the Oracle database using the user prefix_ps_app. prefix is the value specified for the Prefix element under the Catalog element in the database configuration file used to create the database. Use the password that was specified for the Password element under the Catalog element.
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
|
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:
- -Dcds.home=cds-home
- -Dcds.config.file=CDS.properties
- -Dcds.config.dir=cds-home/deployment/deployment-name/conf
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();
}
}
|