Skip navigation.

Using the CORBA Notification Service

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

CORBA Notification Service API Reference

This topic includes the following sections:

Note: The BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.0.

All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used:

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.



The BEA Tuxedo CORBA Notification Service supports two application programming interfaces. One is based on the CORBA-based Notification Service as defined by the CORBAservices: Common Object Services Specification. This interface is referred to in this document as the CosNotification Service interface. The other interface, called the BEA Simple Events interface, is a BEA proprietary interface designed as an easier to use alternative.

Both interfaces pass structured events as defined by the CORBA-based Notification Service specification and are compatible with each other; that is, events posted using the CosNotification Service interface can be subscribed to by the BEA Simple Events interface and vice versa.

Before using the Notification Service APIs, consider the following topics:

Quality of Service

To determine the persistence of the subscription and whether or not events delivery is retried following a failed delivery, subscribers specify a Quality of Service (QoS). There are two Quality of Service settings: persistent and transient Quality of Service (QoS). The QoS is a property of the subscription.

Persistent Subscriptions

Persistent subscriptions provide strong guarantees about event delivery and the permanence of the subscription. Persistent subscriptions do come with a cost, however, as they consume more system resources (for example, disk space, CPU cycles, and so on), and require more administration (such as managing queues and detecting dead subscribers).

Persistent subscriptions exhibit the following properties:

Transient Subscriptions

Transient subscriptions provide the best performance with the least overhead and exhibit the following properties:

The subscription is in effect until a failed event delivery is detected. On detection of a failed delivery, the subscription is terminated. Normally, the Notification Service, for performance reasons, does not check whether it successfully delivered an event to a transient subscriber. However, occasionally, when the Notification Service delivers an event to a transient subscriber, it checks whether or not the event was successfully delivered. If it was not successfully delivered and the CORBA::TRANSIENT exception is not returned, the Notification Service assumes that the subscription has gone away and cancels the subscription. If the Notification Service receives the CORBA::TRANSIENT exception when an attempt to deliver fails, it assumes that the subscriber is busy and discards the event, but it does not cancel the subscription.

The automatic cancellation of dead transient subscriptions provides a cleanup mechanism for transient subscribers that forget to unsubscribe. Note, however, that the Notification Service checks for successful delivery the first time it sends an event to a subscriber, but does not perform it again until five minutes have elapsed and it delivers another event. Therefore, the interval between checks is at least five minutes, but will be longer if there is no event to deliver when five minutes have elapsed. The minimum interval of five minutes is fixed and cannot be changed. Therefore, event delivery failure is not necessarily detected on the first failed delivery attempt. It is only detected when the Notification Service checks.

Obtaining the Channel Factory

The Channel Factory is used by event poster applications and subscriber applications to find the event channel. The event channel is then used to post events and to subscribe, or create subscriptions, and unsubscribe, or cancel subscriptions.

Notification Service applications use the Bootstrap object to obtain an object reference to the event channel factory. This is done by using the Tobj_Bootstrap::resolve_initial_references operation. The Bootstrap object supports two service IDs for Notification Service applications, NotificationService and Tobj_SimpleEventsService. The NotificationService object is used in applications that use the CosNotification Service API. The Tobj_SimpleEventsService object is used in applications that use the BEA SimpleEvents API.

Service ID

Object Type






Note: Release 8.0 of BEA Tuxedo CORBA continues to include the BEA client environmental objects provided in previous releases of BEA WebLogic Enterprise for use with the Tuxedo 8.0 CORBA clients. BEA Tuxedo 8.0 clients should continue to use these environmental objects to resolve initial references bootstrapping, security and transaction objects. In release 8.0 of BEA Tuxedo CORBA, support has been added for using the OMG Interoperable Naming Service (INS) to resolve initial references to bootstrapping, security, and transaction objects. For information on INS, see the CORBA Programming Reference.

Using Transactions

The behavior regarding transactions is the same for the BEA SimpleEvents API and the CosNotification Service API. The only operation that supports transactional behavior is push_structured_event, which is supported by the CosNotifyChannelAdmin::StructuredProxyPushConsumer and Tobj_SimpleEvents::Channel interfaces. All other operations can be used in the context of a transaction, but work the same regardless of whether they are executed in a transaction or not.

The behavior when posting an event is tied to the QoS of the subscription. If an event is posted in the context of a transaction, and the event delivery QoS of the subscription is persistent, the delivery will be affected by the outcome of the transaction; that is, if the transaction is committed, the Notification Service attempts to deliver the event to subscribers as it normally would. If the transaction is rolled back, then the Notification Service does not attempt to deliver the event.

If an event is posted in the context of a transaction, and the event delivery QoS of the subscriber's subscription is transient, one attempt will be made to deliver the event, regardless of the transaction outcome. That is, the transaction has no effect on whether the event is delivered or not, and one attempt will be made to deliver the event.

Note: There is no transaction context associated with event delivery. However, in the case of persistent subscriptions, once the poster's transaction commits, the Notification Service guarantees that the event will be delivered to the subscriber or put on the error queue to await administrative action.

Structured Event Fields, Types, and Filters

All events that are either pushed by posters to the Notification Service, or delivered to subscribers, are COS Structured Events; that is, they conform to the definition of Structured Events as specified by the CORBA-based Notification Service—a service which extends the CORBAservices Event Service (see Figure 2-1). If the events are to be filtered based on content (versus filtering on domain and type), or if the events are going to be subscribed to by BEA Tuxedo applications, then additional restrictions apply. The restrictions apply to data types and filtering based on event content. These restrictions are explained below.

Figure 2-1 Structured Event

Structured Event


Designing Events

The design of events is basic to any notification service. The design impacts not only the volume of information that is delivered to matching subscriptions, but the efficiency and performance of the Notification Service as well. Therefore, careful planning should be done to ensure that your Notification Service will be able to handle your needs now and allow for future growth.

The Notification Service supports five levels of event design: (1) domain name, (2) type name, (3) priority, (4) filterable data, and (5) remainder of body. When designing an event, you must specify a domain name and a type name; priority and filterable data are optional. The domain name you choose can relate to your business. Hospitals, for example, are in the health care business, so for a Notification Service application for a hospital you might choose "HEALTHCARE" as a domain name. You might want to categorize the events by the type of insurance provider, so you may choose "HMO" or "UNINSURED" as the type name. You may want to further define the events by the entity responsible for payment, so you might choose to use the filterable data to identify the entity as "billing" for a specific "HMO_Account" or a specific or "Patient_Account." Listing 2-1 shows an example of this type of event design.

Listing 2-1 Event Design

domain_name = "HEALTHCARE"
type_name = "HMO"
#Filterable data name/value pairs. = "billing"
filterable_data.value = 4498 = "patient_account"
filterable_data.value = 37621

Obviously, the more specific and precise you are in designing the events that you want your Notification Service application to post and receive, the fewer will be the events the Notification Service will have to process. This has a direct impact on system resources and configuration requirements. Therefore, a lot of thought should be given to event design.

Creating FML Field Table Files for Events

You must create Field Manipulation Language (FML) field table files for events only if one of the following capabilities is required; otherwise FML tables are not required.

A structured event's filterable_data field contains a list of name/value (NV) pairs. An event's data is typically stored in this list. The field names in the FML field table files must match the name in the structured event. The field type can be any allowable FML type (long, short, double, float, char, string) except carray. The value in the structured event must be the same type as defined in the field table. Table 2-1 shows the CORBA Any Types supported by BEA Tuxedo, and which ones can be used for data filtering and BEA Tuxedo interoperability.

Table 2-1 Supported CORBA Any Types 

CORBA Any Types

Supported for Data Filtering and Tuxedo Interoperability





unsigned short


unsigned long





















Listing 2-2 shows an example of an FML field table file. The *base 2000 is the base number for the fields. The first entry has a field name of billing, a field number of 1 relative to the base, and a field type of long.

Listing 2-2 Data Filtering FML Field Table File

*base 2000
#Field Name       Field #  Field Type    Flags     Comments
#----------- ------- ---------- ------ --------
billing 1 long - -
stock_name 2 string - -
price_per_share 3 double - -
number_of_shares 5 long - -

The following guidelines and restrictions apply to BEA Tuxedo FML field table files:

For information on how to create and configure FML field table files, see field_tables in the BEA Tuxedo Command Reference and the Programming BEA Tuxedo ATMI Applications Using FML.

Interoperability with BEA Tuxedo Applications

Applications that use the BEA Tuxedo CORBA Notification Service are interoperable with BEA Tuxedo applications that use the BEA Tuxedo EventBroker. An application using the BEA Tuxedo Notification Service can post events that are delivered to BEA Tuxedo EventBroker subscribers, and can receive events that have been posted by BEA Tuxedo EventBroker.

To achieve this interoperability, it is necessary to understand the mapping between CosNotification Structured Events and the BEA Tuxedo FML buffer so that the contents of the FML field tables can be coordinated by BEA Tuxedo. There are two cases to consider: posting events that are to be received by BEA Tuxedo applications via BEA Tuxedo EventBroker; and receiving events that have been posted to the Notification Service Event Channel by BEA Tuxedo applications.

Posting Events

For a BEA Tuxedo application to subscribe to events posted by a BEA Tuxedo application, you must understand how a BEA Tuxedo structured event is mapped to FML32 and the event name at posting time. The mapping is as follows:

Receiving Events

BEA Tuxedo system events and user events can be received by BEA Tuxedo applications. System events are generated by the BEA Tuxedo system—not by applications. User events are generated by BEA Tuxedo applications. For a listing of System events see EVENTS in the BEA Tuxedo Command Reference. System events and user events are mapped in CosNotification Structured Events as follows:

Structured Event Fields



Always set to "TMEVT"


Empty string


Empty string

Variable Header (Priority)

Empty sequence

Filterable Body Fields

Same as FML field name

Note: Filterable body fields consist of name/value pair, where the name portion is the same as the FML field name.

Remainder of Body

Always set to void


The BEA Tuxedo system detects and posts certain predefined events related to system warnings and failures. For example, system-generated events report on configuration changes, state changes, connection failures, and machine partitioning.

In order for a BEA Tuxedo application to receive events posted by a BEA Tuxedo application, it is necessary to understand how a FML buffer containing a BEA Tuxedo event is used to fabricate a BEA Tuxedo structured event. It is also necessary to know how the domain_name and type_name are related to the BEA Tuxedo event name. There are two cases to consider: system events and user events.

Note that BEA Tuxedo uses a leading dot (".") in the event name to distinguish system-generated events from application-defined events. An example of a system event is .SysNetworkDropped. An example of a user event is eventsdropped. To subscribe to these events, the Notification Service subscriber application must define the subscription as follows:

Parameters Used When Creating Subscriptions

When you create subscriptions, you can specify the following parameters. These parameters support the BEA Simple Events API and the CosNotification Service API.


Specifies a name that identifies the subscription to the Notification Service and the subscriber. Applications should use names that are meaningful to a system administrator since this is the primary way that an administrator associates an application with a subscription and the events that are delivered to the subscriber via the subscription. This parameter is optional (that is, an empty string can be passed in). More than one subscription can use the same name.

The subscription_name must not exceed 128 characters in length.


Same parameter as the domain_type field in the Fixed Header portion of a structured event, as defined by the CORBA-based Notification Service specification. This field is a string that is used to identify a particular vertical industry domain in which the event type is defined, for example, "Telecommunications", "Finance", and "Health Care". Because this parameter is a regular expression, you can also use it to set domain patterns on which to filter. For example, to subscribe to all domains that begin with the letter F, set the domain to "F.*". For information on how to construct regular expressions, see the recomp command in the BEA Tuxedo ATMI C Function Reference.


Same parameter as the type_name field in the Fixed Header portion of a structure event, as defined in the CORBA-based Notification Service specification. It is a string that categorizes the type of event, uniquely within the domain, for example, Comm_alarm, StockQuote, and VitalSigns. Because this parameter is a regular expression, you can also use it to set event type patterns on which to filter. For example, to subscribe to all event types that begin with the letter F, you would set the type to "F.*". For information on how to construct regular expressions, see the recomp command in the BEA Tuxedo ATMI C Function Reference.


Specifies the values of the fields of filterable data and variable headers on which you want to filter. For example, a subscription to news stories may have a domain of "News", a type of "Sports", and a data_filter of "Scores > 20".

This parameter defines the data that the subscription must match in Boolean expressions. The following data types are supported: short, long, char, float, double, and string. Table 2-2 lists the Boolean expression operators that are supported.

Table 2-2 Boolean Expression Operators




+, -, !, ~


*, /, %


+, -


< , >, <=, >=, ==, !=

equality and matching

==, !=, %%, !%

exclusive OR


logical AND


logical OR



To use data filtering, you must set up an FML table, include filters in the subscription, filter the data, and post the event. Listing 2-3 shows an example of these tasks.

Listing 2-3 Data Filtering Requirements

//Setting up the FML Table
Field table file.
*base 2000
*Field Name    Field #   Field Type   Flags    Comments
----------- ------- --------- ------ ------
StockName 1 string - -
PricePerShare 2 double - -
CustomerId 3 long - -
CustomerName 4 string - -

//Subscription data filtering.
1) "NumberOfShares > 100 && NumberOfShares < 1000"
2) "CustomerId == 3241234"
3) "PricePerShare > 125.00"
4) "StockName == 'BEAS'"
5) "CustomerName %% '.*Jones.*'" // CustomerName contains "Jones"
6) "StockName == 'BEAS' && PricePerShare > 150.00"
//Posting the event.
// C++
CosNotification::StructuredEvent ev;
ev.filterable_data[0].name = CORBA::string_dup("StockName");
ev.filterable_data[0].value <<= "BEAS";
ev.filterable_data[1].name = CORBA::string_dup("PricePerShare");
ev.filterable_data[1].value <<= CORBA::Double(175.00);
ev.filterable_data[2].name = CORBA::string_dup("CustomerId");
ev.filterable_data[2].value <<= CORBA::Long(1234567);
ev.filterable_data[3].name = CORBA::string_dup("CustomerName");
ev.filterable_data[3].value <<= "Jane Jones";

For more information about filter grammar, see "Creating FML Field Table Files for Events" on page -7 and the section "Boolean Expression of fielded Buffers" in Programming BEA Tuxedo ATMI Applications Using FML.


Identifies the callback object that will be used by the Notification Service to deliver a structured event. Subscriber applications must implement the CosNotifyComm::StructuredPushConsumer interface so that the Notification Service can call it to deliver events.

Note: You can use either transient or persistent object references for the callback objects. Both QoS and application run times should be taken into consideration when deciding which type of object reference to use. For information to assist you in deciding which type of object reference to use, refer to Table 2-3.

Table 2-3 When to Use Transient Versus Persistent Object References for Joint Client/Servers

If the subscription ...

Then ...

Will have a transient QoS and will start and shut down once.

You should use a transient object reference. It this case, BEA Systems, Inc. recommends the subscriber application unsubscribe on shutdown so as to release system resources, however, this is not a requirement.

Will have a persistent QoS and will start and shut down once.

You should use a transient object reference.

Will have a persistent Qos and will start and shut down multiple times.

You must use a persistent object reference and store the host and port so the same host and port is used each time the subscriber shuts down and restarts. In this case, use of the bidirectional IIOP feature is not recommended.

Note: If a joint client/server is used, it must be remote (outside the BEA Tuxedo domain) because persistent object references are not supported inside the domain.

Will have a transient QoS and will start and shut down multiple times.

You can use a persistent object reference; however, BEA Systems, Inc. does not recommend this configuration unless you can guarantee that no events for this subscriber will be posted while the subscriber is shut down.


qos (quality of service)

Specifies the desired quality of service of the subscription. It can take one of two values: transient or persistent.


For transient subscriptions, the Notification Service makes only one attempt to deliver the event to a subscriber. If that attempt fails, the event is discarded and, if the Notification Service does not receive the CORBA::TRANSIENT exception, it concludes that the subscriber is shutdown or otherwise not available and cancels the subscription. If the Notification Service receives the CORBA::TRANSIENT exception when an attempt to deliver fails, it assumes that the subscriber is busy and discards the event, but it does not cancel the subscription.

For persistent subscriptions, if the first delivery attempt fails, the Notification Service holds the event in the pending queue and keeps attempting to deliver the subscription until the configurable retry limit is reached. When the retry limit is reached, the Notification Service moves the event on an error queue where it is held for disposition by the system administrator. The system administrator either removes the event from the error queue, which in effect discards it, or moves it back to the pending queue so that further attempts to deliver it can be made.

Note: For persistent subscriptions, the Notification Service always does a two-way invoke on callback objects to deliver events. If a joint client/server does not activate a callback object (the event receiver) before it calls orb->run and then the Notification Service invokes on the callback object, as far as the POA is concerned, the callback object does not exist. In this case CORBA::OBJECT_NOT_EXIST exception is returned. If the Notification Service receives a CORBA::OBJECT_NOT_EXIST exception, it drops the subscription and the event; otherwise, the subscription is retained and the event is retried.


BEA Simple Events API

Simplicity and ease-of-use are the defining characteristics of the BEA Simple Events application programming interface (API). Its capabilities are similar to those of the BEA Tuxedo EventBroker.

The BEA Simple Events API consists of the following interfaces (see Figure 2-2):

The Tobj_SimpleEvents::Channel and the Tobj_SimpleEvents::ChannelFactory interfaces are implemented by the Notification Service and are described below.

The CosNotifyComm::StructuredPushConsumer interface is implemented by the subscribers. For a description of this interface, see "CosNotifyComm::StructuredPushConsumer::push_structured_event" on page -57.

Note: The CosNotification Service classes referred to in this section are fully described in the CosNotification Service IDL files, which are located in the tuxdir/include directory.

Note: If you use class operations that are not supported, the CORBA::NO_IMPLEMENT exception is raised.

TOBJ_SimpleEvents::Channel Interface

The Channel interface is used:

This interface provides these operations:

The CORBA IDL for this interface:

module Tobj_SimpleEvents
typedef long SubscriptionID;
typedef string RegularExpression;
typedef string FilterExpression;
  const SubscriptionType TRANSIENT_SUBSCRIPTION = 0;
const SubscriptionType PERSISTENT_SUBSCRIPTION = 1;
interface Channel
void push_structured_event(
in CosNotification::StructuredEvent event);
     SubscriptionID subscribe (
in string subscription_name,
in RegularExpression domain,
in RegularExpression type,
in FilterExpression data_filter,
in CosNotification::QoSProperties qos,
in CosNotifyComm::StructuredPushConsumer push_consumer);

boolean exists( in SubscriptionID id );
     void unsubscribe( in SubscriptionID  id );

These operations are described in the following section.


Skip navigation bar  Back to Top Previous Next