|
|
|
|
|
|
Creating Custom Events
This topic provides the information necessary to write a custom event. You can create a custom event for anything you wish to track. For example, you could create an event that would tell you which pages are displayed for each customer. You could then use the information to determine how many pages are viewed on average per session and which pages are the most popular. Additionally, marketing professionals could use this event when developing scenario actions that are based on the display of particular pages. To demonstrate how to write a custom event, a simple example is provided. Each section references and expands the example.
This topic includes the following sections:
Overview of Creating a Custom Event
The creation of a custom event is a multiple-step process. The following list provides an overview of the process and references the information not covered in this topic:
Writing a Custom Event Class
To create a custom event, you first write an event object. This object encapsulates all the necessary information for correctly interpreting and handling the event when it arrives at a listener. All custom events must subclass the com.bea.p13n.events.Event class. This base class handles setting and retrieving an event's timestamp and type and provided access to the custom event's attributes. Two Event class methods set and retrieve attributes:
setAttribute( String theKey, Serializable theValue )
getAttribute( String theKey )
These methods can be called from the custom event's constructor to set attributes specific to the new event. Keep in mind that all objects set as values in the Event object must be Java serializable. The getTimeStamp() method returns the date of the event's creation in milliseconds. The type of an event is accessed using the Event class's getType() method. The timestamp and type of an Event object instance can be set only at creation time in the Event constructor.
To illustrate the process of creating a custom event, a simple example is presented here, called TestEvent. The example is a basic demonstration of how to create an event subclass. An actual custom event would probably be more elaborate.
A custom event must first have a type. This type should be passed to the superclass constructor (for example, in the Event class); this type is returned at getType() invocations on custom-event object instances. For example:
/** Event Type */
public static final String TYPE = "TestEvent";
To properly initialize the Event base class of the custom event object, the value TYPE is passed to the event constructor. The type of all events must be a simple Java string object.
After defining the type, you must define the keys that access the attributes stored in the custom event. These attributes can be given values in the constructor. For example, the TestEvent class has two properties, userPropertyOne and userPropertyTwo; the type of the value associated with userPropertyOne is a String and userPropertyTwo is a Double. The keys are defined as follows:
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String USER_PROPERTY_ONE_KEY =
"userPropertyOne";
/**
* Event attribute key name for the second user defined property
* Attribute value is a Double
*/
public static final String USER_PROPERTY_TWO_KEY =
"userPropertyTwo";
Finally, a constructor brings the event type and the process of setting attributes together to create an event object. The constructor looks like:
/**
* Create a new TestEvent
*
*
* @param userPropertyOne some user defined property typed as
* a String
* @param userPropertyTwo some user defined property typed as
* a Double
*/
public TestEvent( String userPropertyOneValue,
Double userPropertyTwoValue )
{
/* calls the Event class constructor with this event's type */
super( TYPE );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY,
userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY,
userPropertyTwoValue );
}
Putting all the parts together, the entire custom event class is shown in Listing 2-1.
Listing 2-1 TestEvent Class
/* Start TestEvent class */
public class TestEvent
extends com.bea.p13n.events.Event
{
/** Event Type */
public static final String TYPE = "TestEvent";
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String USER_PROPERTY_ONE_KEY = "userPropertyOne";
/**
* Event attribute key name for the second user defined property
* Attribute value is a Double
*/
public static final String USER_PROPERTY_TWO_KEY = "userPropertyTwo";
/**
* Crate a new TestEvent
*
*
* @param userPropertyOne some user defined property typed as a String
* @param userPropertyTwo some user defined property typed as a Double
*/
public TestEvent( String userPropertyOneValue,
Double userPropertyTwoValue )
{
/* calls the Event class constructor with this event's type */
super( TYPE );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY, userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY, userPropertyTwoValue );
}
}
/* End TestEvent class */
The example in Listing 2-1 shows you how to use the fundamental aspects of the Event base class and the event service. An actual custom event constructor would probably be more complex. For example, it might check for default values or disallow null attributes. Additionally, the custom-event object might have more methods or member data.
Writing a Custom Event Listener
In order to listen for an event, you must define an event listener. All event listeners must implement the com.bea.p13n.events.EventListener interface and have a no arguments (default) constructor. This interface specifies two methods that are fundamental to transmitting events of a given type to interested listeners:
public String[] getTypes()
public void handleEvent( Event ev )
The first method returns the types, in a string array, that the listener is interested in receiving. The event service dispatches events of a given type to listeners that return the event's type in the types array. When the event service has determined that a given listener has registered to receive the type of the current event, an event of that type is dispatched to the listener using the handleEvent( Event ev ) call.
When writing a custom event listener, both methods must be implemented from the EventListener interface. Continuing with the TestEvent example, the TestEventListener listens for instances of TestEvent that are sent through the event service. This can be specified as follows:
/** The types this listener is interested in */
private String[] eventTypes = {"TestEvent"};
/**
The method invoked by the event service to determine the
types to propagate to this listener.
*/
public String[] getTypes()
{
return eventTypes;
}
To handle the event, the handleEvent( Event evt ) method is implemented as follows:
/**
* Handle events that are sent from the event service
*/
public void handleEvent( Event ev )
{
System.out.println("TestListener::handleEvent " +
" -> received an event" +
" of type: " + ev.getType() );
/* Do the work here */
return;
}
Putting all of these pieces together with a constructor, Listing 2-2 shows a simple event listener that registers to receive TestEvent objects.
Listing 2-2 Event Listener
import com.bea.p13n.events.EventListener;
import com.bea.p13n.events.Event;
/**
* TestListener to demonstrate the ease with which listeners can be plugged
* into the behavior tracking system.
*
* This class should be added to the property eventService.listeners
* in order to receive events. The fully qualified classname must be added
* to this property; don't forget to add the ",\" at the end of the previous
* line or the properties parser will not find the new classname.
*
* The types of events that are heard are listed in the eventTypes
* String array. Add and remove strings of that type as necessary.
*
* @author Copyright (c) 2001 by BEA Systems, Inc. All Rights Reserved.
*/
public class TestListener
implements EventListener
{
private String[] eventTypes = {"TestEvent"};
public TestListener()
{
}
public String[] getTypes()
{
return eventTypes;
}
public void handleEvent( Event ev )
{
System.out.println("TestListener::handleEvent -> received an event" +
" of type: " + ev.getType() );
return;
}
}
As with writing a simple event, writing a simple EventListener is also straightforward. Any event listener's internals should be generic; the same TestEventListener instance may not handle all TestEvent objects. Therefore TestEventListener should be entirely stateless and should operate on data that is contained in the event object or stored externally (that is, in a database).
Note: Multiple instances of any listener may execute concurrently.
Installing a Listener Class in the Event Service
To add or remove listeners to the event service, use the WebLogic Server Administration Console. To enable Behavior Tracking, you must add Behavior Tracking as a listener.
Warning: For proper operation, the WebLogic Server requires that changes to the application-config.xml file be made using the WebLogic Server Administration Console.
Note: For more information on using the WebLogic Server Administration Console, see the WebLogic Server Documentation Center.
To add a synchronous or asynchronous listener, take the following steps:
Note: Behavior Tracking listeners can only be implemented as synchronous listeners.
http://hostname:port/console-> wlcsDomain-> Deployments-> wlcsApp-> Service Configurations-> Event Service-> Configuration Tab-> Synchronous Listeners or Asynchronous Listeners
Figure 2-1 WebLogic Server Administration Console—Event Service
Writing a Behavior Tracking Event Class
A Behavior Tracking event is a special type of event that tracks a customer's interactions with an e-commerce site. E-analysis systems use the data gathered from Behavior Tracking events to evaluate customer behavior. The evaluation is primarily used for campaign development and optimizing customer experience on a Web site.
A Behavior Tracking event and its listeners are created in much the same way as the TestEvent class and TestEventListener examples. A simple example is also presented here. The example tracking event is called TestTrackingEvent. All Behavior Tracking events persisted (recorded) to a database for use with BEA Behavior Tracking are handled by the com.bea.p13n.tracking.listeners.BehaviorTrackingListener. The BehaviorTrackingListener extends the com.bea.p13n.events.EventListener class.
The BehaviorTrackingListener receives and persists Behavior Tracking events from the event service when it is plugged into one of the listener's properties in the application-config.xml file.
Notes: For scalability reasons, you should plug the BehaviorTrackingListener into the eventService.listeners property.
This listener receives events from the event service and adds them to a buffer that is intermittently persisted to the Event tables in the database. The frequency of the sweeping of events from the buffer is controlled by the following properties in the application-config.xml file:
You should tune these properties to optimize performance. A buffer sweep should be performed often enough that writing to the database is not too time consuming but not so frequent that the operation is wasteful.
Configuring Events Buffer Sweeping
Warning: For proper operation, the WebLogic Server requires that changes to the application-config.xml file be made using the WebLogic Server Administration Console.
Note: For more information on using the WebLogic Server Administration Console, see the WebLogic Server Documentation Center.
To configure the sweeping of the events buffer, take the following steps:
http://hostname:port/console-> wlcsDomain-> Deployments-> wlcsApp-> Service Configurations-> Behavior Tracking
Figure 2-2 WebLogic Server Administration Console—Behavior Tracking
Facilitating OffLine Processing
For facilitating offline processing of customer interactions with a Web site, Behavior Tracking events are designed to be persisted to a table in the database, called the EVENT table. Part of the process of recording data from Behavior Tracking events is creating an XML representation of the data, which is stored in the xml_definition column of the EVENT table. You can persist events in an alternate location and table structure as requirements dictate. This discussion assumes that you are planning to use the BEA Behavior Tracking event persistence mechanism. Therefore, to persist events in the provided EVENT table, your custom event must conform to the descriptions in this section so that it is created and persisted properly.
To formally specify the data comprising a Behavior Tracking event, you need to develop an XML-XSD schema for the new event. While XSDs are not used internally to verify the creation of XML, the XML that is created represents the event's data in the database. If the event class is properly developed and used, it will conform to the XML-XSD schema. With an XSD document, development of the constructor and attribute keys for a Behavior Tracking event follows easily.
To correctly turn a Behavior Tracking event into an XML representation, the Behavior Tracking event must have several pieces of member data that fully describe an XML instance document for the schema associated with the event type. This data describes the namespace and XSD file associated with the event. For example, Listing 2-3 and Listing 2-4 show the association between the following files:
com.bea.campaign.tracking.events.ClickCampaignEvent and
/lib/schema/ClickCampaignEvent.xsd in PORTAL_HOME\lib\campaign\ejb\campaign.jar.
For more examples, look at the existing XSD files.
Listing 2-3 ClickCampaignEvent.java
/**
Event for tracking click of campaign
*/
public class ClickCampaignEvent
extends ClickEvent
{
/** The event type */
public static final String TYPE = "ClickCampaignEvent";
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE =
"http://www.bea.com/servers/commerce/xsd/tracking/clickcampaign";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE = "ClickCampaignEvent.xsd";
/**
* Event attribute key name for the campaign id
* Attribute value is a String
*/
public static final String CAMPAIGN_ID = "campaign-id";
/**
* Event attribute key name for the scenario id
* Attribute value is a String
*/
public static final String SCENARIO_ID = "scenario-id";
/**
* Event attribute key name for storefront (aka application)
* Attribute value is a String
*/
public static final String APPLICATION_NAME = "application-name";
/**
* Event attribute key name for item category id
* Attribute value is a String
*/
public static final String PLACEHOLDER_ID = "placeholder-id";
/**
Suggestions for entry into the documentType data passed to the constructor
Attribute value is a String
*/
public static final String BANNER_AD_PROMOTION = "bannerAdPromotion";
/**
These are the keys and their order for elements that
will be present in the XML representing this object
*/
private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, DOCUMENT_TYPE, DOCUMENT_ID,
CAMPAIGN_ID, SCENARIO_ID, APPLICATION_NAME, PLACEHOLDER_ID
};
/**
* Create a new ClickCampaignEvent.
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or
* equivalent (null if unknown)
* @param theRequest the http servlet request object
* @param aDocumentType Document Type for the clicked content (optionally
* null)
* @param aDocumentId Document ID for the clicked content (optionally null)
* @param aCampaignId campaign id for the campaign from which the item was
* clicked
* @param aScenarioId scenario id for the scenario (within the campaign)
* for which the item was clicked
* @param aApplicationName application name (aka storefront) (optionally
* null)
* @param aPlaceholderId a placeholder id
*/
public ClickCampaignEvent( String theSessionId,
String theUserId,
HttpServletRequest theRequest,
String aDocumentType,
String aDocumentId,
String aCampaignId,
String aScenarioId,
String aApplicationName,
String aPlaceholderId )
{
super( TYPE,
theSessionId,
theUserId,
XML_NAMESPACE,
XSD_FILE,
localSchemaKeys,
theRequest,
aDocumentType,
aDocumentId);
if( aCampaignId != null ) setAttribute( CAMPAIGN_ID, aCampaignId );
if( aScenarioId != null ) setAttribute( SCENARIO_ID, aScenarioId );
if( aApplicationName != null ) setAttribute( APPLICATION_NAME,
aApplicationName );
if( aPlaceholderId != null ) setAttribute( PLACEHOLDER_ID,
Notice the cross-reference between ClickCampaignEvent and the XSD schema.
Listing 2-4 Corresponding XSD Schema
<xsd:schema
targetNamespace="http://www.bea.com/servers/commerce/xsd/tracking/clickcampaign"
xmlns="http://www.bea.com/servers/commerce/xsd/tracking/clickcampaign"
xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2000/10/XMLSchema
http://www.w3.org/2000/10/XMLSchema.xsd"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
version="2.1">
.
.
.The source code for your Behavior Tracking event should also list the keys and their order for creating an XML instance document from an event object. For an example, see Listing 2-3. The structure of an XSD document and details on XML namespaces can be found at http://www.w3.org/XML/Schema. Several XSD schemas for BEA Behavior Tracking events can be found in /lib/schema at the following location:
PORTAL_HOME\lib\p13n\ejb\events.jar
where PORTAL_HOME is the directory in which you installed BEA WebLogic Portal or BEA WebLogic Personalization Server.
The namespace and schema are specified as:
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE=
"http://<your URI>/testtracking";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE="TestTrackingEvent.xsd";Note: These values are used when creating an instance document to populate the fields.
The schemaKeys are a list of strings which are keys to the event class's getAttribute and setAttribute methods. These keys are used to extract the data that populate elements in the XML instance document which represent the Behavior Tracking event. The keys should be listed in an array that consists of string-typed objects. Their order specifies the order in which they appear in the XML instance document. In the XSD files that the Behavior Tracking system generates, the order of the elements is important; an XML file will not validate with an XSD file if elements are out of order. Elements can be omitted by using the XML numOccurs keyword and setting the value to zero. For examples of how this is done, see the XSD schemas for BEA Behavior Tracking events in /lib/schema, at the following location:
PORTAL_HOME\lib\p13n\ejb\events.jar
An example array for the Behavior Tracking version of the TestEvent described above might appear as:
/**
These are the keys and their order for elements that
will be present in the XML representing this object.
*/
private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY,
USER_PROPERTY_TWO_KEY
};The SESSION_ID and the USER_ID are data elements in the localSchemaKeys array that are useful in implementing a tracking event. The SESSION_ID is the WebLogic Server session ID that is created for every session object. (For more information, see the WebLogic Server 6.0 Documentation Center.) The USER_ID field (which may be null) is the username of the Web site customer associated with the session from which the event was generated. For some events, a user may not be associated with an event; as previously mentioned, the numOccurs for the USER_ID field in an XSD file should be zero. To persist events in the EVENT table, the SESSION_ID must be non-null.
All Behavior Tracking events must extend the com.bea.p13n.tracking.events.TrackingEvent class. This class defines three keys that are useful for setting attributes for all tracking events, as follows:
- TrackingEvent.SESSION_ID
- TrackingEvent.USER_ID
- TrackingEvent.REQUEST.
These keys are used in setAttribute calls made in the TrackingEvent constructor when setting the SESSION_ID, USER_ID, and REQUEST (an HttPServletRequest object), respectively. They should also be used to retrieve values associated with each key when invoking Event.getAttribute (String Key) on event objects that extend TrackingEvent.
TrackingEvent Base Class Constructor
The TrackingEvent base class has a constructor that is more complicated than the Event class's constructor. The Event constructor is invoked by the super( String eventType ) call in the TrackingEvent constructor. The TrackingEvent constructors are shown in Listing 2-5 and Listing 2-6.
Listing 2-5 Tracking Event Constructor—Example 1
/**
* Create a new TrackingEvent.
*
* @param theEventType the event's type
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param theXMLNamespace the namespace for an XML representation of this event
* type
* @param theXSDFile the file that contains the schema which specifies and
* enforces typing on the data in the XML file
* @param theSchemaKeys the list of keys (in their order in the XSD schema)
* representing the data to be persisted in this event's XML
*/
public TrackingEvent( String theEventType,
String theSessionId,
String theUserId,
String theXMLNamespace,
String theXSDFile,
String[] theSchemaKeys )The TrackingEvent constructor shown in Listing 2-6 takes an HttpServletRequest object.
Listing 2-6 Tracking Event Constructor—Example 2
/**
* Create a new TrackingEvent.
*
* @param theEventType the event's type
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param theXMLNamespace the namespace for an XML representation of this event
* type
* @param theXSDFile the file that contains the schema which specifies and
* enforces typing on the data in the XML file
* @param theSchemaKeys the list of keys (in their order in the XSD schema)
* representing the data to be persisted in this event's XML
* @param theRequest the http servlet request object
*/
public TrackingEvent( String theEventType,
String theSessionId,
String theUserId,
String theXMLNamespace,
String theXSDFile,
String[] theSchemaKeys,
HttpServletRequest theRequest )In the first constructor, shown in Listing 2-5, the only data that is optional (that is, that can be null) is theUerId; all other data is required so that the tracking event is correctly persisted to the EVENT table. In the second constructor, shown in Listing 2-6, the HttpServletRequest object can be passed in from generating locations where the HttpServletRequest object is available. This object provides the data needed to fire rules against event instances.
Note: In order to fire rules on a custom Behavior Tracking event, the HttpServletRequest and the USER_ID must be non-null. Generally, a non-null USER_ID means that a customer is logged into a Web site. Rules cannot be fired on an event with a null-user.
The TestTrackingEvent constructor is shown in Listing 2-7.
Listing 2-7 TestTrackingEvent Constructor
/**
* Create a new TestTrackingEvent
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param userPropertyOne some user defined property typed as a String
* @param userPropertyTwo another user defined property typed as a Double
*/
public TestTrackingEvent( String theSessionId,
String theUserId,
String userPropertyOneValue,
Double userPropertyTwoValue )
{
super( TYPE, theSessionId, theUserId, XML_NAMESPACE, XSD_FILE,
localSchemaKeys );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY, userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY, userPropertyTwoValue );
}This constructor calls the TrackingEvent constructor to populate the required values and then sets the attributes necessary for this particular Behavior Tracking event type.
The entire TestTrackingEvent is shown in Listing 2-8.
Listing 2-8 TestTracking Event
import com.bea.p13n.tracking.events.TrackingEvent;
/**
* Test, user-defined behavior tracking event.
*
* This event can be persisted to the database.
*
*/
public class TestTrackingEvent
extends TrackingEvent
{
/** Event type */
public static final String TYPE = "TestTrackingEvent";
/**
The XML namespace for this event
*/
private static final String XML_NAMESPACE="http://<your URI>/testtracking";
/**
The XSD file containing the schema for this event
*/
private static final String XSD_FILE="TestTrackingEvent.xsd";
/**
* Event attribute key name for the first user defined property
* Attribute value is a String
*/
public static final String USER_PROPERTY_ONE_KEY = "userPropertyOne";
/**
* Event attribute key name for the second user defined property
* Attribute value is a Double
*/
public static final String USER_PROPERTY_TWO_KEY = "userPropertyTwo";
/**
These are the keys and their order for elements that
will be present in the XML representing ths object.
*/
private static final String localSchemaKeys[] =
{
SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY, USER_PROPERTY_TWO_KEY
};
/**
* Create a new TestTrackingEvent
*
* @param theSessionId from HttpSession.getId()
* @param theUserId from HttpServletRequest.getRemoteUser() or equivalent
* (null if unknown)
* @param userPropertyOne some user defined property typed as a String
* @param userPropertyTwo another user defined property typed as a Double
*/
public TestTrackingEvent( String theSessionId,
String theUserId,
String userPropertyOneValue,
Double userPropertyTwoValue )
{
super( TYPE, theSessionId, theUserId, XML_NAMESPACE, XSD_FILE,
localSchemaKeys );
if( userPropertyOneValue != null )
setAttribute( USER_PROPERTY_ONE_KEY, userPropertyOneValue );
if( userPropertyTwoValue != null )
setAttribute( USER_PROPERTY_TWO_KEY, userPropertyTwoValue );
}
}The TestTrackingEvent, shown in Listing 2-8, correctly sets its own attributes and sets the attributes in its instantiation of TrackingEvent. This enables correct population of the XML instance document at the time of its creation. Recall that the XML instance document represents the TestTrackingEvent in the database's EVENT table.
If you want the custom Behavior Tracking event type to be persisted in the database, the event must be added to the behaviorTracking.persistToDatabase property in the application-config.xml file. If you are not persisting the event, you do not need to add the event type to this property.
Installing Behavior Tracking Events
Warning: For proper operation, the WebLogic Server requires that changes to the application-config.xml file be made using the WebLogic Server Administration Console.
Note: For more information on using the WebLogic Server Administration Console, see the WebLogic Server Documentation Center.
To install a Behavior Tracking Event listener, take the following steps:
- In the WebLogic Server Console, navigate to Behavior Tracking in the node tree for wlcsDomain as follows:
http://hostname:port/console-> wlcsDomain-> Deployments-> wlcsApp-> Service Configurations-> Behavior Tracking- Enter the name of the event in the Persisted Event Types field, as shown in Figure 2-3.
Figure 2-3 WebLogic Server Administration Console—Behavior Tracking
XML Creation of Behavior Tracking Events
When persisting Behavior Tracking events to the EVENT table, the bulk of the data must be converted to XML. The XML document should conform to an XML XSD schema that you create which specifies the order of the XML elements in the XML instance document. Additionally, the schema must include the types of elements and their cardinalities. The process of creating XML from an event object is handled by a helper class that utilizes variables and constants in a Behavior Tracking event's class file. All schema documents use the namespace: "http://www.w3.org/2000/10/XMLSchema" and all instances of Behavior Tracking schemas use the namespace: "http://www.w3.org/2000/10/XMLSchema-instance". The XML created in Listing 2-9 will conform to the XSD schema.
Listing 2-9 XSD Document Example
<schema targetNamespace="http://www.bea.com/servers/wlcs3.5/xsd/tracking/buy"
xmlns:bt="http://www.bea.com/servers/wlcs3.5/xsd/tracking/buy"
xmlns="http://www.w3.org/2000/10/XMLSchema">
<element name="BuyEvent">
<complexType>
<sequence>
<element ref="bt:event_date"/>
<element ref="bt:event_type"/>
<element ref="bt:session_id"/>
<element ref="bt:user_id" minOccurs="0"/>
<element ref="bt:sku"/>
<element ref="bt:quantity"/>
<element ref="bt:unit_price"/>
<element ref="bt:currency" minOccurs="0"/>
<element ref="bt:application_name" minOccurs="0"/>
<element ref="bt:order_line_id"/>
</sequence>
</complexType>
</element>
<element name="event_date" type="timeInstant"/>
<element name="event_type" type="string"/>
<element name="session_id" type="string"/>
<element name="user_id" type="string"/>
<element name="sku" type="string"/>
<element name="quantity" type="double"/>
<element name="unit_price" type="double"/>
<element name="currency" type="string"/>
<element name="application_name" type="string"/>
<element name="order_line_id" type="long"/>
</schema>Creation of an event's representation in XML takes place generically relative to the event's type. Consequently, to create an accurate XML instance document, each event must specify the namespace, event type, elements, and order of its elements. Using the TestTrackingEvent example, the XML representing an instance of the TestTrackingEvent is constructed as follows:
Note: Assume that testTrackingEvent is a well-formed instance of a TestTrackingEvent.
- Get the event's type with the testTrackingEvent.getType() call.
- Get the event's namespace with the ((TrackingEvent)testTrackingEvent).getXMLNamespace()call.
- Get the event's XSD filename with the ((TrackingEvent)testTrackingEvent).getXSDFile() call.
Using the schema keys from the TestTrackingEvent class, values are inserted into the XML document. Schema key/attribute value pairs correspond to XML elements in this way:
<schema Key>value</schema Key>
The helper class that creates XML for Behavior Tracking assumes that the elements inserted into an XML instance document are not deeply nested. Additionally, the toString() method is used to create a representation of the value object that is retrieved through the Event classes's getAttribute( String Key ) call. The contents of the string returned by invoking toString() on the value object must match the type specified in the event's schema document. The TestTrackingEvent retrieves values using the following keys in the order specified in the schemaKeys array:
- SESSION_ID
- USER_ID
- USER_PROPERTY_ONE_KEY
- USER_PROPERTY_TWO_KEY
The values for these keys are retrieved using the testTrackingEvent.getAttribute( <schema Key> ) call. The order in which the XML formatted key/value pairs are inserted into the instance document is specified by the constant schemaKeys array, which is defined and populated in the TestTrackingEvent class.
The steps assembled to create an XML instance document for the TestTrackingEvent are presented in Listing 2-10.
Listing 2-10 XML Instance Document Example
<TestTrackingEvent
xmlns="http://<your URI>/testtracking"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="http://<your URI>/testtracking TestTrackingEvent.xsd"
>
<event_date>XML time instant formatted event date</event_date>
<event_type>TestTrackingEvent</event_type>
<session_id>theSessionIdValue</session_id>
<user_id>theUserIdValue</user_id>
<userPropertyOne>userPropertyOneValue</userPropertyOne>
<userPropertyTwo>userPropertyTwoValue</userPropertyTwo>
</TestTrackingEvent>The XML creation is performed automatically when events arrive at the com.bea.p13n.tracking.listeners.BehaviorTrackingListener, which enables Behavior Tracking in WebLogic Portal or WebLogic Personalization Server. The Behavior Tracking listener is installed by adding it to the <EventService Listeners="..."> property in the application-config.xml file. For information on how to install a Behavior Tracking listener, seeInstalling Behavior Tracking Events.
You must be careful when defining the namespaces, XSD documents, and schema keys variables in custom Behavior Tracking event classes, especially if they will be persisted to the EVENT table. The method for creating and storing XML presented in this discussion exactly follows the variables and constants specified in the event class. You are free to develop other ways of creating and storing XML; this section is directed only at the process of persisting XML Behavior Tracking representations in the BEA EVENT table.
Note: The Event's date is retrieved using the Event class's getTimeStamp() call, which returns a Java primitive long typed value. That long must be converted into the type specified for the event_date element in the XSD schema document. The type in this case is time instant. Event date and event type the first two elements in all XML instance documents created through the BehaviorTrackingListener.
Custom Behavior Tracking Event Listeners
To create a custom Behavior Tracking listener, in addition to or instead of the default BehaviorTrackingListener, follow the example presented in Writing a Custom Event Listener. Add the new event types to the custom listener's eventTypes array (for example, TestTrackingEvent). A given listener can listen for any number of event types that may or may not be Behavior Tracking events. The custom Behavior Tracking listener can be installed on either the synchronous or asynchronous side of the event service, whichever is appropriate.
Writing Custom Event Generators
Once events are created, you must set up a mechanism for generating events in the application. Events may be generated from pipeline components, input processors, JSP scriptlets, or JSP tags. Some Behavior Tracking events are generated from within WebLogic Portal or WebLogic Personalization Server software.
After determining the mechanism for generating events, tracking events can be sent to the event system using the com.bea.p13n.tracking.TrackingEventHelper class. This class defines helper methods that pass events to the event service. Listing 2-11 shows an example of passing the TestTrackingEvent.
Listing 2-11 Dispatching an Event
/*
* Create the event
*/
Event theEvent = new TestTrackingEvent( "<some session id>",
"<some user id> ",
new String("userPropertyOneValue"),
new Double( 3.14 ) );
/*
* Dispatch the event
*/
TrackingEventHelper.dispatchEvent( theEvent );To dispatch a TestEvent to the event service, the event service name can be looked up in the JNDI, and an instance of the EventService bean can be obtained by invoking the create() method on an EventServiceHome instance. The JNDI name of the EventServiceHome interface is the classname of the EventServiceHome class (com.bea.p13n.events.EventServiceHome). Listing 2-12 shows an example.
Listing 2-12 JNDI Example
import com.bea.p13n.util.helper.JNDIHelper;
import com.bea.p13n.events.Event;
import com.bea.p13n.events.EventServiceHome;
import com.bea.p13n.events.EventService;
import javax.ejb.CreateException;
import javax.rmi.PortableRemoteObject;
/* code here */
public void demonstrateEventDispatch()
{
Event event = <some event instance>;
try
{
EventServiceHome home = (EventServiceHome)
JNDIHelper.lookup( "java:comp/env/ejb/EventService" ),
EventServiceHome.class );
EventService eventService = home.create();
eventService.dispatchEvent( event );
}
catch( Exception e )
{
/*
Do exception handling here
*/
}
}
/* more code here */
Debugging the Event Service
To debug the event service, create a debug.properties file in the following directory:
%PORTAL_HOME%\debug.properties (Windows)
$PORTAL_HOME/debug.properties (UNIX)
The contents of this file are shown in Listing 2-13.
Listing 2-13 Debugging the Event Service
usePackageNames: on
com.bea.p13n.cache: on
# Turns on debug for all classes under events
com.bea.p13n.events: on
# com.bea.p13n.events.internal.EventServiceBean: on
# Turns on debug for all classes under
# com.bea.p13n.tracking: on
com.bea.p13n.tracking.internal persistence: on
# Selectively turn on classes
com.bea.p13n.mbeans.BehaviorTrackingListerner: on
com.bea.p13n.tracking.listeners.BehaviorTrackingListerner: on
com.bea.p13n.tracking.SessionEventListerner: on
Registering a Custom Event
When you create a custom event, you must register the event. Registering a custom event lets the E-Business Control Center know that the custom event exists. Registering permits campaign developers using the E-Business Control Center to create scenario actions that refer to the event. Registering also identifies the event's properties.
Caution: Whenever you change the event code, you must update the event registration. Conversely, whenever you change the event registration, you must also update the event code. A possible ramification of event modification is that the scenario actions that refer to the event's properties may need to be modified.
Note: You cannot change any of the standard events supplied with WebLogic Portal or WebLogic Personalization Server.
To register a custom event, use the Event Editor in the E-Business Control Center. Registering an event is actually creating a property set for the event. A step-by-step procedure is available in both the E-Business Control Center online help and "Creating and Managing Property Sets" in the Guide to Building Personalized Applications.
Copyright © 2001 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.77 or higher, or Microsoft Internet Explorer 5.01 or higher.
Contact us (documentation feedback only)