|
|
Notification Service API Reference
This topic includes the following sections:
Introduction
The BEA 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:
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 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 |
---|---|
NotificationService |
CosNotifyChannelAdmin::EventChannelFactory |
Tobj_SimpleEventsService |
Tobj_SimpleEvents::ChannelFactory |
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
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.
filterable_data.name = "billing"
filterable_data.value = 4498
filterable_data.name = "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 WebLogic Enterprise, and which ones can be used for data filtering and BEA Tuxedo interoperability.
CORBA Any Types |
Supported for Data Filtering and Tuxedo Interoperability |
---|---|
short |
Yes |
long |
Yes |
unsigned short |
No |
unsigned long |
No |
float |
Yes |
double |
Yes |
char |
Yes |
boolean |
No |
octet |
No |
string |
Yes |
void |
No |
null |
No |
any |
No |
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 WebLogic Enterprise FML field table files:
For information on how to create and configure FML field table files, see field_tables(5) in the BEA Tuxedo Reference and the BEA Tuxedo FML Programmer's Guide.
Interoperability with BEA Tuxedo Applications
Applications that use the WebLogic Enterprise Notification Service are interoperable with BEA Tuxedo applications that use the BEA Tuxedo Event Broker. An application using the WebLogic Enterprise Notification Service can post events that are delivered to BEA Tuxedo Event Broker subscribers, and can receive events that have been posted by BEA Tuxedo Event Broker.
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 between BEA Tuxedo and WebLogic Enterprise. There are two cases to consider: posting events that are to be received by BEA Tuxedo applications via BEA Tuxedo Event Broker; 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 WebLogic Enterprise application, you must understand how a WebLogic Enterprise structured event is mapped to FML32 and the event name at posting time. The mapping is as follows:
BEA Tuxedo system events and user events can be received by WebLogic Enterprise 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(5) in the BEA TUXEDO Reference. System events and user events are mapped in CosNotification Structured Events as follows:
Structured Event Fields |
Value |
---|---|
domain_name |
Always set to "TMEVT" |
type_name |
Empty string |
event_name |
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 WebLogic Enterprise 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 WebLogic Enterprise 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:
domain_name ="TMEVT"
type_name=".SysNetworkDropped"
domain_name ="TMEVT"
type_name="eventsdropped"
When the events are received, the Notification Service subscriber application parses each event as follows:
domain_name="TMEVT"
type_name=""
event_name=""
variable_header=empty
Filterable_data=(content of the FML buffer)
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.
Expression |
Operators |
---|---|
unary |
+, -, !, ~ |
multiplicative |
*, /, % |
additive |
+, - |
relational |
< , >, <=, >=, ==, != |
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";
// Java
StructuredEvent ev;
...
ev.filterable_data[0].name = "StockName";
ev.filterable_data[0].value.insert_string("BEAS");
ev.filterable_data[1].name = "PricePerShare";
ev.filterable_data[1].value.insert_double(175.00);
ev.filterable_data[2].name = "CustomerId";
ev.filterable_data[2].value.insert_long(1234567);
ev.filterable_data[3].name = "CustomerName";
ev.filterable_data[3].value.insert_string("Jane Jones");
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.
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 WebLogic Enterprise 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. |
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 Event Broker.
The BEA Simple Events API consists of the following interfaces (see Figure 2-2):
Figure 2-2 BEA Simple Events Interfaces
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" .
Note: The CosNotification Service classes referred to in this section are fully described in the CosNotification Service IDL files, which are located in the wledir/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.
Channel::subscribe
CORBA IDL
SubscriptionID subscribe (
in string subscription_name,
in RegularExpression domain,
in RegularExpression type,
in FilterExpression data_filter,
// The filter expression must length 1 and the name must
// be TRANSIENT_SUBSCRIPTION or PERSISTENT_SUBSCRIPTION.
in CosNotification::QoSProperties qos,
in CosNotifyComm::StructuredPushConsumer push_consumer
);
Exceptions
Tobj_Events::SUB_INVALID_FILTER_EXPRESSION
Tobj_Events::SUB_UNSUPPORTED_QOS_VALUE
Tobj_Events::SUB_DOMAIN_BEGINS_WITH_SYSEV
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Use this operation to subscribe to events. This operation is called by a subscriber application on the Notification Service to create a subscription to a particular event. The subscription name, domain name, type name, data filter, quality of service, and the object reference of the subscriber's callback object are passed in. The callback object implements the CosNotifyComm::StructuredPushConsumer IDL interface.
Note: For subscribers that shut down and restart, you must write the subscription_id to persistent storage.
To use data filtering or subscribe to BEA Tuxedo system events or events posted by a BEA Tuxedo application, see the sections "Creating FML Field Table Files for Events" and "Interoperability with BEA Tuxedo Applications" .
Parameters
For a description of the parameters supported by this operation, see "Parameters Used When Creating Subscriptions" .
Return Value
Returns a unique subscription identifier. The effect of this operation is not instantaneous. There can be a delay between returning from this operation and the actual start of event delivery. The length of the delay period may be significant depending on your configuration. For more information on factors impacting this delay period, see "Synchronizing Databases" .
Note: Notification Service applications that start and shut down only once can use the subscription_id to determine if their subscription has been cancelled automatically or by the system administrator.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
subscription_id = channel->subscribe(
subscription_name,
"News", // domain
"Sports", // type
"", // No data filter.
qos,
news_consumer.in()
);
Java code example:
int subscription_id = channel.subscribe(
subscription_name,
"News", // domain
"Sports", // type
"", // no data filter
qos,
news_consumer_impl
);
Channel::unsubscribe
CORBA IDL
void unsubscribe( in SubscriptionID id );
Parameter
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used to unsubscribe. Subscriber applications use this operation to terminate subscriptions. On return from this operation, no further events can be delivered. There is one input parameter: SubscriptionID, which you got when you subscribed.
Note: This operation is not instantaneous. After returning from this operation, a subscriber may continue to receive events for a period of time. The period of time may be significant depending on your configuration. For more information on factors impacting this period of time, see "Synchronizing Databases" .
Examples
C++ code example:
channel->unsubscribe(subscription_id);
Java code example:
channel.unsubscribe(subscription_id);
Channel::push_structured_event
CORBA IDL
void push_structured_event(
in CosNotification::StructuredEvent notification
);
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Parameter
Description
Used by the poster application to post an event to the Notification Service.
Note: This operation has transactional behavior when used in the context of a transaction. For more information, see the section "Using Transactions" .
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
channel->push_structured_event(notification);
Java code example:
channel.push_structured_event(notification);
Channel::exists
CORBA IDL
boolean exists(in SubscriptionID subscription_id);
Parameter
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used by subscriber applications to determine if a subscription exists. Since the system administrator can delete subscriptions manually and the Notification Service can delete transient subscriptions automatically, a subscriber application might want to use this operation so that it can recreate the subscription, if necessary. The subscription_id used in this operation is the same one that you got when you subscribed.
Return Value
Returns Boolean True of the subscription exists and False if it does not.
Examples
C++ code example:
if channel->exists (subscription_id) {
// The subscription is still valid.
} else {
// The subscription no longer exists.
}
Java code example:
if channel.exists (subscription_id) {
// The subscription is still valid.
} else {
// The subscription no longer exists.
}
TOBJ_SimpleEvents::ChannelFactory Interface
The ChannelFactory interface is used to find event channels. This interface provides a single operation: find_channel.
The CORBA IDL for this interface:
module Tobj_SimpleEvents
{
typedef long ChannelID;
interface ChannelFactory
{
Channel find_channel(
in ChannelID channel_id // Must be DEFAULT_CHANNEL
);
};
};
Channel_Factory::find_channel
CORBA IDL
Channel find_channel(
in ChannelID channel_id );
Parameter
In this release of WebLogic Enterprise, there can only be one event channel; therefore, the ChannelID that is passed in must be set to Tobj_SimpleEvents::DEFAULT_CHANNEL (for C++) or Tobj_SimpleEvents.DEFAULT_CHANNEL.Value (for Java).
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
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" .
C++ code example:
channel_factory->find_channel(
Tobj_SimpleEvents::DEFAULT_CHANNEL);
Java code example:
channel_factory.find_channel(DEFAULT_CHANNEL.value);
CosNotification Service API
This section contains a discussion of the operations defined by the CosNotification Service that are implemented by WebLogic Enterprise Notification Services. 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 necessarily more complex then the BEA Simple Events API. There are two reasons for this. First, the CosNotification Service API is more complex. Second, the WebLogic Enterprise 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 WebLogic Enterprise does not support this grammar, but supports an alternative grammar based on the BEA Tuxedo Event Broker 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 WebLogic Enterprise and their relationships.
Figure 2-3 Implemented CosNotification Service Classes
The operations supported by each class are summarized below. For more detailed descriptions, see "Detailed Descriptions of CosNotification Service Classes" .
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.
This class is used by event poster and subscriber applications. It supports three operations:
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.
This class is used by event poster applications. It supports the following operations:
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.
This class is used by event subscriber applications. It supports the following operations:
This class is used by event subscriber applications. It supports the following operations:
This class is used by event subscriber applications. It supports the following operations:
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 WebLogic Enterprise implements. These classes are fully described in the CosNotification Service IDL files, which are located in the wledir/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
CosNotifyFilter::Filter::add_constraints
Synopsis
Sets the domain, type, and data filter parameters on the filter object.
OMG IDL
ConstraintInfoSeq add_constraints (
in ConstraintExpSeq constraint)
raises (InvalidConstraint);
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used when subscribing. This operation is used in subscriber applications to define the kind of event to which you want to subscribe. You set the domain, type, and data filter parameters on the filter object. For a description of these parameters, see "Parameters Used When Creating Subscriptions" .
Note: The WebLogic Enterprise implementation of the add_constraints operation 1) can only be called once, 2) must be called before the filter is added to the proxy object, and 3) must consist of only a single constraint which has a single event type.
Return Value
Returns an empty list, which we recommend that the caller ignores.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
// set the filtering parameters
// (domain = "News", type, and no data filter)
CosNotifyFilter::ConstraintExpSeq constraints;
constraints.length(1);
constraints[0].event_types.length(1);
constraints[0].event_types[0].domain_name =
CORBA::string_dup("News");
constraints[0].event_types[0].type_name =
CORBA::string_dup ("Sports");
// no data filter
constraints[0].constraint_expr = CORBA::string_dup(""); CosNotifyFilter::ConstraintInfoSeq_var
add_constraints_results = // ignore this returned value
filter->add_constraints(constraints);
Java code example:
// set the filtering parameters
// (domain = "News", type, and no data filter).
ConstraintExp constraints[] = new ConstraintExp[1];
constraints[0] = new ConstraintExp();
constraints[0].event_types = new EventType[1];
constraints[0].event_types[0] = new EventType();
constraints[0].event_types[0].domain_name = "News";
constraints[0].event_types[0].type_name = "Sports";
constraints[0].constraint_expr = ""; // No data filter.
ConstraintInfo add_constraints_results[] =
filter.add_constraints(constraints); //Ignore this return value.
CosNotifyFilter::Filter::destroy
Synopsis
Destroys the filter object.
OMG IDL
void destroy();
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used when unsubscribing. This operation is used in subscriber applications to destroy the target filter object.
Note: Do not destroy the filter object until you are ready to cancel the corresponding subscription.
CosNotifyFilter::FilterFactory Class
This class is used by event subscriber applications. The OMG IDL for this class is as follows:
Module CosNotifyFilter
{
interface FilterFactory {
Filter create_filter (
in string constraint_grammar)
raises (InvalidGrammar);
destroy();
};
}; //CosNotifyFilter
CosNotifyFilter::FilterFactory::create_filter
Synopsis
Determines which events are delivered to a subscription.
OMG IDL
Filter create_filter (
in string constraint_grammar)
raises (InvalidGrammar);
Exceptions
Description
Used in the subscriber application to create a new filter object. This filter is used to determine which events are delivered to a subscription. The subscriber must set up the filter and add it to the proxy within five minutes; otherwise, the filter will be destroyed. The filter grammar must be set to Tobj_Notification::Constraint_grammar; otherwise, the InvalidGrammar exception is raised.
Return Value
Returns the new filter's object reference.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
filter_factory->create_filter(
Tobj_Notification::CONSTRAINT_GRAMMAR
);
Java code example:
filter_factory.create_filter(CONSTRAINT_GRAMMAR.value);
CosNotifyChannelAdmin::StructuredProxyPushSupplier Class
This class is used by event subscriber applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface StructuredProxyPushSupplier :
ProxySupplier,
CosNotifyComm::StructuredPushSupplier {
void connect_structured_push_consumer (
in CosNotifyComm::StructuredPushConsumer push_consumer)
raises(CosEventChannelAdmin::AlreadyConnected,
CosEventChannelAdmin::TypeError );
};
// The following operations are inherited.
void set_qos(in QoSProperties qos)
raises (UnsupportedQoS);
FilterID add_filter (in Filter new_filter );
Filter get_filter( in FilterID filter )
raises ( FilterNotFound);
void disconnect_structured_push_supplier();
readonly attribute ProxyType MyType;
};
}; //CosNotifyChannelAdmin
CosNotifyChannelAdmin::StructuredProxyPushSupplier:: connect_structured_push_consumer
Synopsis
Completes a subscription.
OMG IDL
void connect_structured_push_consumer (
in CosNotifyComm::StructuredPushConsumer push_consumer)
raises(CosEventChannelAdmin::AlreadyConnected,
CosEventChannelAdmin::TypeError );
Exceptions
Note: For exception definitions and corresponding minor codes, see "Exception Minor Codes" .
Description
Use this operation when subscribing. This operation is used in subscriber applications to subscribe to events. The push_consumer parameter identifies the subscriber's callback object.
Once the connect_structured_push_consumer has been called, the Notification Service will proceed to send events to the subscriber by invoking the callback object's push_structured_event operation. If the connect_structured_push_consumer has already been called, the AlreadyConnected exception is raised.
Note: You must call set_qos and add_filter before calling connect_structured_push_consumer.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
subscription->connect_structured_push_consumer(
news_consumer.in()
);
Java code example:
subscription.connect_structured_push_consumer(
news_consumer_impl
);
CosNotifyChannelAdmin::StructuredProxyPushSupplier::set_qos
Synopsis
Sets the QoS for the subscription.
OMG IDL
void set_qos(in QoSProperties qos)
raises (UnsupportedQoS);
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used when subscribing. This operation is used in subscriber applications to set the QoS for the subscription. It takes as an input parameter a sequence of name-value pairs which encapsulates quality-of-service property settings that the subscriber is requesting.
There are two components of the QoS: the subscription type and the subscription name. The subscription type is set by constructing a name-value pair where the name is Tobj_Notification::SUBSCRIPTION_TYPE and the value is either Tobj_Notification::PERSISTENT_SUBSCRIPTION, or Tobj_Notification::TRANSIENT_SUBSCRIPTION. For more information and additional usage details, see "Quality of Service" .
The subscription name is set by constructing a name-value pair, where the name is Tobj_Notification::SUBSCRIPTION_NAME, and the value is a user-defined string.
For more information on this parameter, see "Parameters Used When Creating Subscriptions" .
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
CosNotification::QoSProperties qos;
qos.length(2);
qos[0].name =
CORBA::string_dup(Tobj_Notification::SUBSCRIPTION_NAME);
qos[0].value <<= "MySubsription";
qos[1].name =
CORBA::string_dup(Tobj_Notification::SUBSCRIPTION_TYPE);
qos[1].value <<=
Tobj_Notification::TRANSIENT_SUBSCRIPTION;
subscription->set_qos(qos);
Java code example:
Property qos[] = new Property[2];
qos[0] = new Property();
qos[0].name = SUBSCRIPTION_NAME.value;
qos[0].value = orb.create_any();
qos[0].value.insert_string("MySubsription");
qos[1] = new Property();
qos[1].name = SUBSCRIPTION_TYPE.value;
qos[1].value = orb.create_any();
qos[1].value.insert_short(TRANSIENT_SUBSCRIPTION.value);
subscription.set_qos(qos);
CosNotifyChannelAdmin::StructuredProxyPushSupplier::add_filter
Synopsis
Sets the filter object on the subscriber's callback object.
OMG IDL
add_filter(
in Filter new_filter
);
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used when subscribing. This operation is used in subscriber applications to set the filter object to the subscriber's callback object. If the application using this operation will be shut down and restarted, the filter_id should be written to persistent storage.
Note: This operation: 1) cannot be called after the subscriber callback object is connected (see connect_structured_push_consumer above), 2) cannot be called more than once, and 3) when it is called, the filter constraint expression must already be present in the filter (see CosNotifyFilter::Filter add_constraints).
Note: Only filters created by the event channel's default filter factory can be added.
Return Value
Returns a filter_id.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
CosNotifyFilter::FilterID filter_id =
subscription->add_filter(filter.in());
Java code example:
int filter_id = subscription.add_filter(filter);
CosNotifyChannelAdmin::StructuredProxyPushSupplier::get_filter
Synopsis
Gets an object reference to the filter currently associated with the subscriber's callback object.
OMG IDL
Filter get_filter( in FilterID filter )
raises ( FilterNotFound);
Exceptions
Description
Used when a restartable subscriber wants to unsubscribe. This operation is used in subscriber applications to get an object reference to the filter currently associated with the subscriber's callback object. The FilterID that is passed in must be valid for the subscriber's StructuredProxyPushSupplier object. If the FilterID is not valid for any proxy object associated with the event channel, then a FilterNotFound exception is thrown. The operation is only used by subscribers that shut down and restart.
Restrictions
The following usage restrictions and guidelines apply to this operation:
Return Value
Returns a filter object reference to the filter currently associated with the subscriber's callback object.
Examples
C++ code example:
CosNotify::Filter_var filter =
subscription->get_filter( filter_id() );
Java code example:
Filter filter = subscription.get_filter( filter_id() );
CosNotifyChannelAdmin::StructuredProxyPushSupplier::
disconnect_structured_push_supplier
Synopsis
Used to unsubscribe.
OMG IDL
void disconnect_structured_push_supplier();
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Description
Used by subscriber applications when unsubscribing. This operation is used in subscriber applications to terminate a connection between the Notification Service and the subscriber's callback object.
Note: This operation does not stop event delivery instantaneously. After returning from this operation, a subscriber may continue to receive events for a period of time.
Examples
C++ code example:
subscription->disconnect_structured_push_supplier();
Java code example:
subscription.disconnect_structured_push_supplier();
CosNotifyChannelAdmin::StructuredProxyPushSupplier::MyType
Synopsis
Always returns CosNotifyChannelAdmin::PUSH_STRUCTURED proxy.
OMG IDL
readonly attribute ProxyType MyType
Description
Always returns CosNotifyChannelAdmin::PUSH_STRUCTURED proxy.
CosNotifyChannelAdmin::StructuredProxyPushConsumer Class
This class is used by event posting applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface StructuredProxyPushConsumer :
ProxyConsumer,
CosNotifyComm::StructuredPushConsumer {
void connect_structured_push_supplier (
in CosNotifyComm::StructuredPushSupplier push_supplier)
raises(CosEventChannelAdmin::AlreadyConnected);
// The following operations are inherited.
readonly attribute MyType;
void push_structured_event(
in CosNotification::StructuredEvent notification )
raises( CosEventComm::Disconnected );
void disconnect_structured_push_consumer();
};
}; \\StructuredProxyPushConsumer
CosNotifyChannelAdmin::StructuredProxyPushConsumer::
connect_structured_push_supplier
Synopsis
Prepares the Notification Service to receive an event.
OMG IDL
void connect_structured_push_supplier (
in CosNotifyComm::StructuredPushSupplier push_supplier)
raises(CosEventChannelAdmin::AlreadyConnected);
Exception
Description
Used by poster applications when posting events. You must call this operation to prepare the Notification Service to receive an event and you must pass in a NIL when you use this operation. The sequence of usage is as follows:
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
proxy_push_consumer->connect_structured_push_supplier(
CosNotifyComm::StructuredPushSupplier::_nil()
);
Java code example:
proxy_push_consumer.connect_structured_push_supplier(null);
CosNotifyChannelAdmin::StructuredProxyPushConsumer::
push_structured_event
Synopsis
Posts events to the event channel.
OMG IDL
void push_structured_event(
in CosNotification::StructuredEvent notification )
raises( CosEventComm::Disconnected );
Exceptions
Note: For more information on exceptions and corresponding minor codes, see "Exception Minor Codes" .
Descriptions
Used when posting events. This operation is used in poster applications to post events to the event channel.
Note: This operation differs from the standard CORBA definition in the following ways:
1) The Priority in the variable header section of the event, if specified, must be short value in the range of 1 to 100.
2) If event filterable data filtering (versus filtering on domain and type only) is required, or if events are to be received by a BEA Tuxedo subscriber, then additional restrictions apply. See "Structured Event Fields, Types, and Filters" and "Interoperability with BEA Tuxedo Applications" .
Note: This operation has transactional behavior when used in the context of a transaction. For more information, see Using Transactions.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
proxy_push_consumer->push_structured_event(notification);
Java code example:
proxy_push_consumer.push_structured_event(notification);
CosNotifyChannelAdmin::StructuredProxyPushConsumer::
disconnect_structured_push_consumber
Synopsis
Stops posting events.
OMG IDL
void disconnect_structured_push_consumer();
Descriptions
Used when posting events. This operation is used by poster applications to stop posting events. It takes no input parameters and returns no values. The recommended usage sequence is as follows:
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
proxy_push_consumer->disconnect_structured_push_consumer();
Java code example:
proxy_push_consumer.disconnect_structured_push_consumer();
CosNotifyChannelAdmin::StructuredProxyPushconsumer::MyType
Synopsis
Always returns CosNotifyChannelAmdmin::PUSH_STRUCTURED proxy.
OMG IDL
readonly attribute ProxyType MyType
Description
Always returns CosNotifyChannelAmdmin::PUSH_STRUCTURED proxy.
CosNotifyChannelAdmin::ConsumerAdmin Class
This class is used by event subscriber applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface ConsumerAdmin :
CosNotification::QoSAdmin,
CosNotifyComm::NotifySubscribe,
CosNotifyFilter::FilterAdmin,
CosEventChannelAdmin::ConsumerAdmin {
ProxySupplier obtain_notification_push_supplier (
in ClientType ctype,
out ProxyID proxy_id)
raises ( AdminLimitExceeded )
ProxySupplier get_proxy_supplier (
in ProxyID proxy_id )
raises ( ProxyNotFound );
};
}; //CosNotifyChannelAdmin
CosNotifyChannelAdmin::ConsumerAdmin::
obtain_notification_push_supplier
Synopsis
Creates proxy push supplier objects.
OMG IDL
ProxySupplier obtain_notification_push_supplier (
in ClientType ctype,
out ProxyID proxy_id)
raises ( AdminLimitExceeded )
Exceptions
Description
Used when subscribing. This operation is used in subscriber applications to create proxy push supplier objects. Only structured events are supported (that is, ANY_EVENT and SEQUENCE_EVENT ClientTypes are not supported). Therefore, the ClientType input parameter must be set to CosNotifyComm::STRUCTURED_EVENT. If you shut down and restart the subscriber and subscription survives more than one run of your program, the ProxyID returned by this operation should be durably stored. The subscriber must narrow the proxy supplier to CosNotifyChannelAdmin::StructuredProxyPushSupplier. All required operations must be completed in five minutes.
Note: Notification Service applications that start and shut down only once can use the proxy_id to determine if their subscription has been cancelled automatically or by the system administrator.
Return Value
This operation returns the new proxy's object reference. The new proxy_id is also returned through the proxy_id out parameter.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating a Subscription" .
C++ code example:
CosNotifyChannelAdmin::ProxySupplier_var generic_proxy =
consumer_admin->obtain_notification_push_supplier(
CosNotifyChannelAdmin::STRUCTURED_EVENT,
proxy_id
);
CosNotifyChannelAdmin::StructuredProxyPushSupplier_var proxy =
CosNotifyChannelAdmin::StructuredProxyPushSupplier::_narrow(
generic_proxy.in ()
);
Java code example:
ProxySupplier generic_proxy =
consumer_admin.obtain_notification_push_supplier(
ClientType.STRUCTURED_EVENT,
proxy_id
);
StructuredProxyPushSupplier proxy =
StructuredProxyPushSupplierHelper.narrow(
generic_proxy
);
CosNotifyChannelAdmin::ConsumerAdmin::get_proxy_supplier Synopsis
Returns the proxy push supplier object created using the consumer admin object obtain_notification_push_supplier operation.
OMG IDL
ProxySupplier get_proxy_supplier (
in ProxyID proxy_id )
raises ( ProxyNotFound );
Exceptions
Descriptions
Used when unsubscribing. This operation is used in subscriber applications to return the proxy push supplier object created using the consumer admin object obtain_notification_push_supplier operation. The ProxyID input parameter uniquely identifies the proxy object. Callers should be aware that the proxy object can be destroyed either due to an error in delivering a transient subscription or through an ntsadmin administrative command. When a proxy object is destroyed, the ProxyID associated with it is invalidated. If the ProxyID is invalid, a ProxyNotFound exception is raised. The subscriber must narrow the proxy supplier to CosNotifyChannelAdmin::StructuredProxyPushSupplier.
Return Value
Returns the object reference for the existing proxy.
Examples
C++ code example:
CosNotifyChannelAdmin::ProxySupplier_var generic_proxy =
m_consumer_admin->get_proxy_supplier(
m_subscription_info.news_proxy_id()
);
CosNotifyChannelAdmin::StructuredProxyPushSupplier_var proxy =
CosNotifyChannelAdmin::StructuredProxyPushSupplier::_narrow(
generic_proxy.in()
);
Java code example:
ProxySupplier generic_subscription =
m_consumer_admin.get_proxy_supplier(
m_subscription_info.news_proxy_id()
);
StructuredProxyPushSupplier subscription =
StructuredProxyPushSupplierHelper.narrow(
generic_proxy);
CosNotifyChannelAdmin::SupplierAdmin Class
This class is used by event poster applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface SupplierAdmin :
CosNotification::QoSAdmin,
CosNotifyComm::NotifyPublish,
CosNotifyFilter::FilterAdmin,
CosEventChannelAdmin::SupplierAdmin {
ProxyConsumer obtain_notification_push_consumer (
in ClientType ctype,
out ProxyID proxy_id)
raises ( AdminLimitExceeded );
};
}; //SupplierAdmin
CosNotifyChannelAdmin::SupplierAdmin::
obtain_notification_push_consumer
Synopsis
Creates proxy push consumer objects.
OMG IDL
ProxyConsumer obtain_notification_push_consumer (
in ClientType ctype,
out ProxyID proxy_id)
raises ( AdminLimitExceeded );
Exceptions
Description
Used when posting events. This operation is used in poster applications to create proxy push consumer objects. ClientType must be set to "CosNotifyChannelAdmin::STRUCTURED_EVENT". The ProxyID returned should be ignored. The Proxy Consumer must be narrowed the proxy supplier to CosNotifyChannelAdmin::StructuredProxyPushConsumer.
Note: Notification Service applications that start and shut down only once can use the proxy_id to determine if their subscription has been cancelled automatically or by the system administrator.
Return Value
This operation returns the new proxy's object reference. The new proxy_id is also returned through the proxy_id out parameter.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
CosNotifyChannelAdmin::ProxyConsumer_var generic_proxy_consumer =
supplier_admin->obtain_notification_push_consumer(
CosNotifyChannelAdmin::STRUCTURED_EVENT,
proxy_id
);
CosNotifyChannelAdmin::StructuredProxyPushConsumer_var
proxy_push_consumer =
CosNotifyChannelAdmin::StructuredProxyPushConsumer::_narrow(
generic_proxy_consumer
);
Java code example:
supplier_admin.obtain_notification_push_consumer(
ClientType.STRUCTURED_EVENT, proxy_id );
CosNotifyChannelAdmin::EventChannel Class
This class is used by event poster applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface EventChannel :
CosNotification::QoSAdmin,
CosNotification::AdminPropertiesAdmin,
CosEventChannelAdmin::EventChannel {
readonly attribute ConsumerAdmin default_consumer_admin;
readonly attribute SupplierAdmin default_supplier_admin;
readonly attribute CosNotifyFilter::FilterFactory
default_filter_factory;
};
}; //CosNotifyChannelAdmin
CosNotifyChannelAdmin::EventChannel::
ConsumerAdmin default_consumer_admin
Synopsis
Gets the ConsumerAdmin object.
OMG IDL
readonly attribute ConsumerAdmin default_consumer_admin;
Description
Used when subscribing and unsubscribing. This operation is used in subscriber applications to get the ConsumerAdmin object.
Return Value
Returns the object reference to the ConsumerAdmin object.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Getting the Event Channel, ConsumerAdmin Object, and Filter Factory Object" .
C++ code example:
channel->default_consumer_admin();
Java code example:
channel.default_consumer_admin();
CosNotifyChannelAdmin::EventChannel::
ConsumerAdmin default_supplier_admin
Synopsis
Gets the Supplier Admin object.
OMG IDL
readonly attribute SupplierAdmin default_supplier_admin;
Description
Used when posting events. This operation is used in event poster applications to get the SupplierAdmin object.
Return Value
SupplierAdmin object reference.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Creating and Posting Events" .
C++ code example:
channel->default_supplier_admin();
Java code example:
channel.default_supplier_admin();
CosNotifyChannelAdmin::EventChannel::default_filter_factory
Synopsis
Gets the default FilterFactory object.
OMG IDL
readonly attribute CosNotifyFilter::FilterFactory
default_filter_factory;
Description
Used when subscribing. This operation is used in subscriber applications to get the default FilterFactory object.
Return Value
Default FilterFactory object reference.
Examples
Note: Code examples shown here are abbreviated. For complete code examples, see "Getting the Event Channel, ConsumerAdmin Object, and Filter Factory Object" .
C++ code example:
channel->default_filter_factory();
Java code example:
channel.default_filter_factory();
CosNotifyChannelAdmin::EventChannelFactory Class
This class is used by event poster applications. The OMG IDL for this class is as follows:
Module CosNotifyChannelAdmin
{
interface EventChannelFactory {
EventChannel get_event_channel ( in ChannelID id )
raises (ChannelNotFound);
};
}; //CosNotifyChannelAdmin
CosNotifyChannelAdmin::EventChannelFactory::get_event_channel
Synopsis
Gets the EventChannel object.
OMG IDL
EventChannel get_event_channel ( in ChannelID id )
raises (ChannelNotFound);
Exceptions
Description
Used when subscribing, unsubscribing, and posting events. This operation is used in applications to get the EventChannel object. When subscribing, the EventChannel object is used to get the filter factory object and the ConsumerAdmin object. When unsubscribing, the EventChannel object is used to get the ConsumerAdmin object.When posting an event, the EventChannel object is used to get the SupplierAdmin object. The ChannelID parameter that is passed in must be set to Tobj_Notification::DEFAULT_CHANNEL; otherwise, the ChannelNotFound exception is raised.
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" and "Getting the Event Channel, ConsumerAdmin Object, and Filter Factory Object" .
C++ code example:
channel_factory->get_event_channel(
Tobj_Notification::DEFAULT_CHANNEL );
Java code example:
channel_factory.get_event_channel(DEFAULT_CHANNEL.value);
CosNotifyComm::StructuredPushConsumer Interface
This interface is used by event subscriber applications for event delivery. You must implement this interface so that the Notification Service can invoke on it to deliver events to subscribers. It has three methods which you have to implement.
The OMG IDL for this class is as follows:
Module CosNotifyComm
{
interface StructuredPushConsumer : NotifyPublish {
void push_structured_event(
in CosNotification::StructuredEvent event)
raises(CosEventComm::Disconnected);
void disconnect_structured_push_consumer:
//The following operations are inherited.
void offer_change(
in CosNotification::EventTypeSeq added,
in CosNotification::EventTypeSeq removed )
raises ( InvalidEventType );
};
}; //CosNotifyComm
CosNotifyComm::StructuredPushConsumer::push_structured_event
Synopsis
Delivers a structured event.
OMG IDL
void push_structured_event(
in CosNotification::StructuredEvent event)
raises(CosEventComm::Disconnected);
Exceptions
Description
Used when subscribing. This operation is implemented by the subscriber's callback object and is invoked by the Notification Service each time a structured event is delivered. This operation contains a single input parameter, which is a structured event.
Note: This operation will not be called in a transaction. Also, when this operation is called, it must return quickly because the Notification Service might not start delivering events to other subscribers until this operation returns.
Note: Code examples shown here are abbreviated. For complete code examples, see "Implementing the CosNotifyComm::StructuredPushConsumer Interface" .
C++ code example:
virtual void push_structured_event(
const CosNotification::StructuredEvent& notification );
{
// Process the event.
}
Java code example:
public void push_structured_event(StructuredEvent notification)
{
// Process the event.
}
CosNotifyComm::StructuredPushConsumer::
disconnect_structured_push_consumer
Synopsis
Never invoked.
OMG IDL
void disconnect_structured_push_consumer;
Description
This operation is never invoked. The subscriber application must provide a stubbed-out version of this operation.
Examples
C++ code example:
virtual void push_structured_event(
const CosNotification::StructuredEvent& notification );
{
throw new CORBA::NO_IMPLEMENT();
}
Java code example:
public void disconnect_structured_push_consumer()
{
throw new CORBA::NO_IMPLEMENT();
}
CosNotifyComm::StructuredPushConsumer::Offer_change
Synopsis
Never invoked.
OMG IDL
void offer_change(
in CosNotification::EventTypeSeq added,
in CosNotification::EventTypeSeq removed )
raises ( InvalidEventType );
Exceptions
Description
This operation is never invoked. The subscriber application must provide a stubbed-out version of this operation.
Examples
C++ code example:
virtual void offer_change(
const CosNotification::EventTypeSeq& added,
const CosNotification::EventTypeSeq& removed )
{
throw CORBA::NO_IMPLEMENT();
}
Java code example:
public void offer_change(EventType[] added, EventType[] removed)
{
throw new NO_IMPLEMENT();
}
Exception Minor Codes
This section provides information about the Notification Service exception symbols and minor codes. The minor codes are in the Tobj_Events.idl and Tobj_Notification.idl files. These files are located in the wledir\include directory (for Microsoft Windows NT systems) and wledir/include directory (for UNIX systems).
Table 2-4 and Table 2-5 list the exception symbols and corresponding minor codes for the Tobj_Events and Tobj_Notification exceptions respectively. CORBA system events have a minor code field and those minor codes are also defined in these tables.
Note: The exception symbols are organized within the tables by the higher-level exceptions (CORBA::IMP_LIMIT, CORBA::CORBA::BAD_PARAM, CORBA::BAD_INV_ORDER, CORBA::INV_OBHJREF, and CORBA::OBJECT_NOT_EXIST)and listed in alphabetical order.
Exception Symbols |
Definitions |
Minor Codes (Hexadecimal) |
---|---|---|
CORBA::IMP_LIMIT Exceptions |
||
Tobj_Events:: This exception is raised by:
|
When posting an event, the user specified a domain name and type name whose combined length was greater than 31 characters. |
5455580D |
Tobj_Events:: This exception is raised by:
|
When posting an event, the user specified a domain name that contained the "." character. |
54555802 |
Tobj_Events::POST_EMPTY_DOMAIN This exception is raised by:
|
When posting an event, the user specified an empty domain name. |
5455580B |
Tobj_Events::POST_EMPTY_TYPE This exception is raised by:
|
When posting an event, the user specified an empty type name. |
5455580C |
Tobj_Events:: This exception is raised by:
|
When posting an event, the user tried to post a Tuxedo system event; that is, the domain name is "TMEVT" and the type name starts with the "." character. |
54555804 |
Tobj_Events:: This exception is raised by:
|
When posting an event, the user specified a type name that contained the "." character. |
54555803 |
Tobj_Events:: This is exception is raised by:
|
When posting an event, the user added a "Priority" field in the variable header. However, the user did not set the field's value to a "short" in the range of 1-100. |
54555801 |
Tobj_Events:: This exception is raised by:
|
When posting an event, the user put an unsupported type (for example, a structure, union, sequence, etc.) into one of the "anys" in the structured event field. The unsupported type is in the variable header's value field, the filterable data's value field, or the remainder_of_body field. |
54555800 |
Tobj_Events:: This exception is raised by:
|
When subscribing, the user specified a domain name and type name whose combined length is greater than 255 characters. |
54555809 |
Tobj_Events:: This exception is raised by:
|
When subscribing, the user specified a domain name that begins with the "." character. |
54555805 |
Tobj_Events::SUB_EMPTY_DOMAIN This exception is raised by:
|
The user specified an empty domain name when subscribing. |
54555807 |
Tobj_Events::SUB_EMPTY_TYPE This exception is raised by:
|
The user specified an empty type name when subscribing. |
54555808 |
Tobj_Events::SUB_FILTER_TOO_LONG This exception is raised by:
|
The user specified a data filter expression longer than 255 characters. |
5455580A |
Tobj_Events::SUB_NAME_TO_LONG This exception is raised by:
|
When subscribing, the user specified a subscription name longer than 127 characters. |
5455580E |
Tobj_Events:: This exception is raised by:
|
The user tried to create a persistent subscription, but the system was configured to support transient subscriptions only. |
54555806 |
CORBA::BAD_PARAM Exceptions |
|
|
Tobj_Events::INVALID_CHANNEL_ID This exception is raised by:
|
When looking up the channel using the Simple Events API, the user specified an invalid channel ID, that is, a channel ID that is not Tobj_SimpleEvents:: |
54555813 |
Tobj_Events:: This exception is raised by:
|
When unsubscribing using the Simple Events API, the user specified an invalid subscription ID, that is, a non-existent or a CosNotification subscription ID. When looking up a subscription using the CosNotification Service API, the user specified an invalid subscription ID, that is, a non-existent or a Simple Events API subscription ID. When calling the exists operation using the BEA Simple Events API, the user passed in a CosNotification subscription_id. |
54555812 |
Tobj_Events:: This exception is raised by:
|
When subscribing, the user specified an invalid data filter expression. This either means that there is a syntax error in the expression or that one of the field names in the expression is not defined as an FML field. Check that you have correctly created FML field tables that contain all fields that you want to data filter on, and check that the UBBCONFIG file is properly configured so that the field table files can be found. |
54555810 |
Tobj_Events:: This exception is raised by:
|
54555811 When subscribing, the user specified an invalid subscription quality of service. For the Simple Events API, this means that the quality of service specified did not meet one of the following requirements:
For the CosNotification Service API, this means that the quality of service specified did not meet one of the following requirements:
|
|
CORBA::INV_OBHJREF |
||
Tobj_Events:: This exception is raised by:
|
When subscribing, the user specified a NIL object reference for the callback object which receives events. |
54555830 |
Exception Symbols |
Definitions |
Minor Codes (Hexadecimal) |
---|---|---|
CORBA::IMP_LIMIT Exceptions |
|
|
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber waited more than five minutes after creating a filter to call add_constraints on the filter. This means that the filter has been destroyed (timed out) and the subscriber must create a new filter. |
54555858 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called add_constraints on a filter that had already been added to a proxy. |
5455585E |
Tobj_Notification:: This exception is raised by:
|
After creating a filter and calling "add_constraints" on it, a CosNotification subscriber waited more than five minutes to call add_filter to add the filter to the proxy. This means that the filter has been destroyed (timed out) and that the subscriber must create a new filter. |
5455585D |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called add_filter after connecting to the proxy. |
54555852 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called set_qos after connecting to the proxy. |
54555856 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called add_constraints more than once on a filter. |
54555859 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called add_filter more than once on a proxy. |
54555851 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber called set_qos more than once on a proxy. |
54555855 |
Tobj_Notification:: This exception is raised by:
|
When a CosNotification subscriber called add_constraints on a filter, the subscriber passed in a list of constraints that had more than one item; that is, the subscriber was trying to send in a list of data filters instead of one data filter. |
5455585A |
Tobj_Notification:: This exception is raised by:
|
When a CosNotification subscriber called add_constraints on a filter, the subscriber passed on a constraint that had more than one domain/type set; that is, the subscriber was trying to send in a list of desired event types instead of one event type. |
5455585B |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber passed a nil filter object reference into add_filter. |
54555853 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber passed a filter object that was not created by the default filter factory into add_filter. For example, a CosNotification subscriber implemented the CosNotifyFilter::Filter interface to do some kind of "custom" filtering and passed one of those filter objects into add_filter. |
54555854 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber did not call add_filter to the proxy before connecting to the proxy. |
54555850 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber did not call add_filter to the proxy before connecting to the proxy. |
54555857 |
Tobj_Notification:: This exception is raised by:
|
A CosNotification subscriber passed in a domain name of "TMEVT" and a type name that begins with "."; that is, the CosNotification subscriber was trying to subscribe to Tuxedo system events. This is not supported. It is only supported by the Simple Events API. |
5455585C |
Tobj_Notification:: This is exception raised by:
|
When creating a proxy, a CosNotification subscriber or poster passed in a client type other than CosNotifyChannelAdmin::STRUCTURED_EVENT. |
5455585F |
CORBA::OBJECT_NOT_EXIST Exception |
||
Tobj_Notification:: This exception is raised by:
Note: connect_structured_push_
|
A CosNotification subscriber called a method on a proxy that had already been destroyed. The proxy has been destroyed by one of the following actions:
|
54555880 |
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|