Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Jolt   |   Topic List   |   Previous   |   Next   |   Contents   |   Index

   Using BEA Jolt

Programmers developing client applications with Jolt can receive event notifications from either BEA Tuxedo Services or other BEA Tuxedo clients. The Jolt Class Library contains classes that support the following types of BEA Tuxedo notifications for handling event-based communication:

• Unsolicited Event Notifications. These are notifications that a Jolt client receives as a result of a BEA Tuxedo client or service issuing a broadcast using either a tpbroadcast() or a directly targeted message via a tpnotify() ATMI call.

• Brokered Event Notifications. These notifications are received by a Jolt client through the BEA Tuxedo Event Broker. The notifications are only received when the Jolt client subscribes to an event and any BEA Tuxedo client or server issues a system-posted event or tppost() call.

Event Subscription Classes

The Jolt Class Library provides four classes that implement the asynchronous notification mechanism for Jolt client applications:

• JoltSession. The JoltSession class includes an onReply() method for receiving notifications and notification messages.

• JoltReply. The JoltReply class gives the client application access to any messages received with an event or notification.

• JoltMessage. The JoltMessage class provides get() methods for obtaining information about the notification or event.

• JoltUserEvent. The JoltUserEvent class supports subscription to both unsolicited and event notification types.

For additional information about these classes refer to the API Reference in Javadoc.

For both unsolicited notifications and a brokered event notification, the Jolt client application requires an event handler routine that is invoked upon receipt of a notification. Jolt only supports a single handler per session. In BEA Tuxedo versions, you cannot determine which event generated a notification. Therefore, you cannot invoke an event-specific handler based on a particular event.

The client application must provide a single handler (by overriding the onReply() method) per session that will be invoked for all notifications received by that client for that session. The single handler call-back function is used for both unsolicited and event notification types. It is up to the (user-supplied) handler routine to determine what event caused the handler invocation and to take appropriate action. If the user does not override the session handler, then notification messages are silently discarded by the default handler.

The Jolt client provides the call back function by subclassing the JoltSession class and overriding the onReply() method with a user-defined onReply() method.

In BEA Tuxedo/ATMI clients, processing in the handler call-back function is limited to a subset of ATMI calls. This restriction does not apply to Jolt clients. Separate threads are used to monitor notifications and run the event handler method. A Jolt client can perform all Jolt-supported functionality from within the handler. All the rules that apply to a normal Jolt client program apply to the handler, such as a single transaction per session at any time.

Each invocation of the handler method takes place in a separate thread. The application developer should ensure that the onReply() method is either synchronized or written thread-safe, because separate threads could be executing the method simultaneously.

Jolt uses an implicit model for enabling the handler routine. When a client subscribes to an event, Jolt internally enables the handler for that client, thus enabling unsolicited notifications as well. A Jolt client cannot subscribe to event notifications without also receiving unsolicited notifications. In addition, a single onReply() method is invoked for both types of notifications.

Jolt supports notification receipts for clients working in either connection-retained or connection-less modes of operation. Connection-retained clients receive all notifications. Jolt clients working in connection-less mode receive notifications while they have an active network connection to the Jolt Session Handler (JSH). When the network connection is closed, the JSH logs and drops notifications destined for the client. Jolt clients operating in a connection-less mode do not receive unsolicited messages or notifications while they do not have an active network connection. All messages received during this time are logged and discarded by the JSH.

Connection mode notification handling includes acknowledged notifications for Jolt clients in the BEA Tuxedo environment. If a JSH receives an acknowledged notification for a client and the client does not have an active network connection, the JSH logs an error and returns a failure acknowledgment to the notification.

When a client receives notification, it is accompanied by a data buffer. The data buffer can be of any BEA Tuxedo data buffer type. Jolt clients (for example, the handler) receive these buffers as a JoltMessage object and should use the appropriate JoltMessage class get*() methods to retrieve the data from this object.

The Jolt Repository does not need to have the definition of the buffers used for notification. However, the Jolt client application programmer needs to know field names.

The Jolt system does not provide functionality equivalent to tptypes() in BEA Tuxedo. For FML and VIEW buffers, the data is accessed using the get*() methods with the appropriate field name, for example:

getIntDef ("ACCOUNT_ID", -1);

For STRING and CARRAY buffers, the data is accessed by the same name as the buffer type:

getStringDef ("STRING", null);
getBytesDef ("CARRAY", null);

STRING and CARRAY buffers contain only a single data element. This complete element is returned by the preceding get*() methods.

BEA Tuxedo brokered event notification allows BEA Tuxedo programs to post events without knowing what other programs are supposed to receive notification of an event's occurrence. The Jolt event notification allows Jolt client applications to subscribe to BEA Tuxedo events that are broadcast or posted using the BEA Tuxedo tpnotify() or tpbroadcast() calls.

Jolt clients can only subscribe to events and notifications that are generated by other components in BEA Tuxedo (such as a BEA Tuxedo service or client). Jolt clients can not send events or notifications.

Jolt only supports notification types of subscriptions. The Jolt onReply() method is called when a subscription is fulfilled. The Jolt API does not support dispatching a service routine or enqueueing a message to an application queue when a notification is received.

If a Jolt client subscribes to a single event notification, the client receives both unsolicited messages and event notification. Subscribing to an event implicitly enables unsolicited notification. This means that if the application creates a JoltUserEvent object for Event "X", the client automatically receives notifications directed to it as a result of tpnotify() or tpbroadcast().

Note: Subscribing to single event notification is not the recommended method for enabling unsolicited notification. If you want unsolicited notification, the application should explicitly subscribe to unsolicited notifications (as described in the JoltUserEvent class). The next section is about unsubscribing from notifications.

To stop subscribing to event notifications and/or unsolicited messages, you need to use the JoltUserEvent unsubscribe method. In Jolt, disabling unsolicited notifications with an unsubscribe method does not turn off all subscription notifications. This differs from BEA Tuxedo. In BEA Tuxedo the use of tpsetunsol() with a NULL handler turns off all subscription notifications.

When unsubscribing, the following considerations apply:

• If a client is subscribed to a single event, unsubscribing from notification disables both event notification and unsolicited messages.

• If a client has multiple subscriptions, then unsubscribing from any single subscription disables only that single subscription. Unsolicited notifications continue. Only the last subscription to be unsubscribed causes unsolicited notification to stop.

• If a client subscribes to both unsolicited and event notifications, then unsubscribing to only the unsolicited notification will not stop either type of notification from continuing. In addition, this unsubscribe does not throw an exception. However, the Jolt API notes that an unsubscribe has taken place, and a subsequent unsubscribe to the remaining event disables both event notification and unsolicited messages.

If you want to stop unsolicited messages in your client application, you need to make sure that you have unsubscribed to all events.

The Asynchronous Notification listing shows how to use the Jolt Class Library for receiving notifications and includes the use of the JoltSession, JoltReply, JoltMessage and JoltUserEvent classes.

class EventSession extends JoltSession
{
    public EventSession( JoltSessionAttributes attr, String user,
                         String role, String upass, String apass )
    {
           super(attr, user, role, upass, apass);
    }
    /**
    * Override the default unsolicited message handler.
    * @param reply a place holder for the unsolicited message
    * @see bea.jolt.JoltReply
    */
    public void onReply( JoltReply reply )
    {
        // Print out the STRING buffer type message which contains
        // only one field; the field name must be "STRING".  If the
        // message uses CARRAY buffer type, the field name must be
        // "CARRAY".  Otherwise, the field names must conform to the
        // elements in FML or VIEW.

        JoltMessage msg = (JoltMessage) reply.getMessage();
        System.out.println(msg.getStringDef("STRING", "No Msg"));
    }
    public static void main( Strings args[] )
    {
        JoltUserEvent    unsolEvent;
        JoltUserEvent      helloEvent;
        EventSession        session;
        ...

        // Instantiate my session object which can print out the
        // unsolicited messages.  Then subscribe to HELLO event
        // and Unsolicited Notification which both use STRING
        // buffer type for the unsolicited messages.

        session = new EventSession(...);

        helloEvent = new JoltUserEvent("HELLO", null, session);
        unsolEvent = new JoltUserEvent(JoltUserEvent.UNSOLMSG, null,
                                       session);
        ...
        // Unsubscribe the HELLO event and unsolicited notification.
        helloEvent.unsubscribe();
        unsolEvent.unsubscribe();
    }
}