Using the CORBA Notification Service

Channel_Factory::find_channel

CORBA IDL

Channel find_channel(
      in  ChannelID  channel_id );

Parameter

In this release of BEA Tuxedo, there can only be one event channel; therefore, the ChannelID that is passed in must be set to Tobj_SimpleEvents::DEFAULT_CHANNEL (for C++).

Exceptions

CORBA::BAD_PARAM

Indicates the following problem:

Tobj_Events::INVALID_CHANNEL_ID

Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" on page -59.

Description

Used by poster applications and subscriber applications. This operation is used to find the event channel so that it can be used by the poster to post events and by the subscriber to subscribe and unsubscribe to events.

Return Value

Returns the default event channel's object reference.

Examples

Note: Code examples shown here are abbreviated. For complete code examples, see "Getting the Event Channel" on page -2.

C++ code example:

channel_factory->find_channel(
               Tobj_SimpleEvents::DEFAULT_CHANNEL);

CosNotification Service API

This section contains a discussion of the operations defined by the CosNotification Service that are implemented by the BEA Tuxedo CORBA Notification Service. These operations are only a subset of the complete set of operations. This subset is a functionally complete API that can be used as an alternative to the BEA Simple Events API.

This API is more complex then the BEA Simple Events API. There are two reasons for this. First, the CosNotification Service API is more complex. Second, the BEA Tuxedo implementation of the CosNotification Service API places additional restrictions on the operations that are supported. Because this complexity offers no advantages in terms of performance or flexibility, BEA Systems, Inc. recommends that you use the BEA Simple Events API whenever possible.

The CosNotification API is provided for those who require that a standard API be used whenever possible for purposes of portability. In regard to functionality, this API provides no benefits beyond those offered by the Simple Events API. Applications that are developed using this API will be mostly, but not completely, portable. The reason for this is that not enough of the CosNotification Service API is supported to facilitate portability. For example, the filtering grammar required by the CORBA-based Notification Service is based on the COS Trader grammar. Since BEA Tuxedo does not support this grammar, but supports an alternative grammar based on the BEA Tuxedo EventBroker grammar, any application that requires filtering will not be portable. The same is true for QoS, that is, the CosNotification Service API does not support the CORBA-based Notification Service standard qualities of service, but it does support alternative qualities of service.

Overview of Supported CosNotification Service Classes

Figure 2-3 shows the CosNotification Service classes implemented, in full or in part, in this release of BEA Tuxedo and their relationships.

Figure 2-3 Implemented CosNotification Service Classes

Implemented CosNotification Service Classes

The operations supported by each class are summarized below. For more detailed descriptions, see "Detailed Descriptions of CosNotification Service Classes" on page -29.

CosNotifyChannelAdmin::EventChannelFactory Class

This class is used by the event poster and subscriber applications. It supports the get_channel_factory operation which is used to get the channel factory when posting, subscribing, and unsubscribing to events.

CosNotifyChannelAdmin::EventChannel Class

This class is used by event poster and subscriber applications. It supports three operations:

default_consumer_admin—used by event subscriber applications to get the consumer admin object.
default_supplier_admin—used by event poster applications to get the supplier admin object.
default_filter_factory—used by event subscriber applications to get the filter factory object.

CosNotifyChannelAdmin::SupplierAdmin Class

This class is used by event poster applications. It supports the obtain_notification_push_consumer operation. Poster applications use this operation to create proxy push consumer objects which in turn are used to post events to the Notification Service.

CosNotifyChannelAdmin::StructuredProxyPushConsumer Class

This class is used by event poster applications. It supports the following operations:

connect_structured_push_supplier—used by event poster applications to connect the proxy push supplier to the Notification Service event channel.
push_structured_event—used by event poster applications to post the event to the Notification Service event channel.
disconnect_structured_push_consumer—used by event poster applications to disconnect the proxy push supplier from the Notification Service event channel.

CosNotifyFilter::FilterFactory Class

This class is used by event subscriber applications to create a filter object. It supports the create_filter operation. The filter object provides all data filtering including domain, type, and filterable data.

CosNotifyFilter::Filter Class

This class is used by event subscriber applications. It supports the following operations:

add_contraints operation—used to set the filter's domain, type, and data filter.
destroy operation—used to destroy the filter object.

CosNotifyChannelAdmin::ConsumerAdmin Class

This class is used by event subscriber applications. It supports the following operations:

obtain_notification_push_supplier—used by event subscriber applications to create proxy push supplier objects which in turn are used to deliver events to the subscriber's callback object.
get_proxy_supplier—used by event subscriber applications to retrieve the object reference for the proxy push supplier object. This operation is only used when the subscriber application shuts down then restarts and cancels the subscription. This is because subscribers need to discard the object reference from the first run and get it back again for the next run. Subscribers cannot reuse object references from one run to the next.

CosNotifyChannelAdmin::StructuredProxyPushSupplier Class

This class is used by event subscriber applications. It supports the following operations:

connect_structured_push_consumer—used by event subscriber applications to connect the subscriber to the proxy push supplier.
set_qos—used by event subscriber applications to set the quality of service for subscriptions.
add_filter—used by event subscriber applications to add the filter object to the subscription.
get_filter—used by event subscriber applications when performing unsubscribe operations to get the filter associated with the subscription. This operation is only used when the subscriber application shuts down then restarts.
disconnect_structured_push_supplier—used by event subscriber applications to unsubscribe.

CosNotifyComm::StructuredPushConsumer

This interface is implemented by event subscriber applications. It supports the push_structured_event operation. The Notification Service invokes this operation to deliver events to the subscriber.

Detailed Descriptions of CosNotification Service Classes

This section describes the CosNotification Service classes that this release of BEA Tuxedo implements. These classes 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.

CosNotifyFilter::Filter Class

This class is used by event subscriber applications. The OMG IDL for this class is as follows:

Module CosNotifyFilter
{
interface Filter { 
     ConstraintInfoSeq add_constraints (
             in ConstraintExpSeq constraint)
          raises (InvalidConstraint);

      void destroy();
    };
}; //CosNotifyFilter