|
|
Using the Event Subscription Service (ESS) requires a working knowledge of the following concepts:
Before writing the code that implements the ESS features in your client-application code, devise an event-handling scheme that supports your specific needs. First, program your client application to obtain an object reference to the CiscoEventGateway::EventGateway server. Then register one or more CiscoEventGateway::Callback objects with the single EventGateway object to manage event subscriptions for your client applications. There are no specific rules for your usage of these objects other than those demanded by your client-application architecture or by your programming conventions. You must, however, use language-specific programming techniques to construct and destroy Callback objects.
When planning your event-handling scheme, devise a persistent storage mechanism to track the unique identifiers for all registered Callback objects. Upon restarting your client application, use the client-stored Callback identifier values as input to the EventGateway::reregisterCallback() operation to reregister the corresponding Callback objects with the Event Gateway server.
Two object types—CiscoEventGateway::EventGateway and CiscoEventGateway::Callback—are required when implementing the ESS in a client application. The EventGateway and Callback objects work cooperatively to supply event-notification service to your client application. The Callback requires a simple instantiation in the client code, while the EventGateway object must be bound by name with the Event Gateway server using the CORBA tools supplied as part of your CORBA implementation.
To use these interfaces, compile the CiscoEventGateway.idl file using the IDL compiler supplied with your CORBA implementation to generate a set of target-language output "stub" files that correspond with the source language of your client application. Use the include or import directives, as appropriate, to ensure the target-language contents generated from your IDL files are available to your executable client-code for its ESS usage.
The CiscoEventGateway::EventGateway interface binds by name to the Event Gateway server that is started by the Cisco VPN Solutions Center Watchdog server. This interface supplies the operations with which to define the event flow from the Event Gateway server to each registered and subject-subscribed CiscoEventGateway::Callback object in one or more client applications. Figure 10-1 shows how to obtain and object reference to the EventGateway server and how to destroy it.
Here are the basic steps for getting an object reference to the CiscoEventGateway::EventGateway interface from the Event Gateway server:
Step 2 Bind the context using the EventGateway server by name—always EventGateway—and specify the machine name where it is executing.
Step 3 Resolve the EventGateway namespace to get a generic object reference.
Step 4 Execute the CiscoEventGateway::EventGateway::narrow() operation with the generic object reference as an input parameter to get a qualified object reference. If the narrow() operation returns the correct object type, continue with the usage of your CiscoEventGateway::EventGateway object reference. If the narrow operation raises an exception, handle the exception.
Step 5 When you are finished using the object reference to the EventGateway server—after deregistering all CiscoEventGateway::Callback objects that are registered through the EventGateway interface—use the CORBA::release() operation to release the memory allocated to the EventGateway object by the client application.
The following pseudocode shows generically how to connect to the Event Gateway server:
// Include or import files, as needed.
...
// Declare and initialize variables, context, and object references.
string egHost = "";
string egBindName = "";
CORBA::NameComponent egBindName;
CORBA::Context rootContext = null;
CORBA::Object genericObjRef = null;
CiscoEventGateway::EventGateway egObjRef = null;
// Bind to an interface name.
egHost = "localhost";
egBindName.id = "EventGateway";
egBindName.kind = "EventGateway";
rootContext = CORBA::Context::<bind>(":" + egBindName.id, egHost);
// Resolve the "EventGateway" name space.
genericObjRef = CORBA::Context::<resolve>(egBindName.id);
// Narrow the object reference.
if (egObjRef = CiscoEventGateway::EventGateway::<narrow>(genericObjectRef))
{
... // Continue with usage of the narrowed object reference.
}
else
{
... // Handle the exception raised by the implicit <narrow> operation.
}
...
// Release the object reference to the Event Gateway server when finished.
CORBA::release(egObjRef);
...
In the if segment of the preceding if-else logic construct, the narrowed object reference, egObjRef, is used to manage registrations and subject subscriptions for the CiscoEventGateway::Callback object to enable and disable event flow to it.
The CiscoEventGateway::Callback object is a simple instance of the CiscoEventGateway::Callback interface, which is instantiated locally by the client-application code. Because this object is implemented by the client code, there is no need to resolve or narrow the namespace nor is there a need to bind the Callback object to an external CORBA server. Figure 10-2 diagram shows how to construct and destroy CiscoEventGateway::Callback objects.
The italicized construct and destroy operation names imply the usage of your language-specific construction and destruction operators, such as the new and delete operators in C++. For example:
... cbObjRef = new CiscoEventGateway::Callback; ... // Lifespan of the cbObjRef. delete cbObjRef;
After creating your CiscoEventGateway::Callback object you can register and subscribe it to accept delivery of subject-categorized events.
Before registering or subscribing any CiscoEventGateway::Callback objects, define a process for handling the CiscoEventGateway::Event data that is delivered to a registered and subscribed CiscoEventGateway::Callback object by the EventGateway server. The Event Gateway server delivers events to registered and subscribed CiscoEventGateway::Callback objects through the input parameter of the CiscoEventGateway::Callback::deliverEvents() operation.
Events are delivered to the CiscoEventGateway::Callback object as a sequence, EventSeq, of Event structures. You must implement the CiscoEventGateway::Callback::deliverEvents() operation somewhere for each Callback object to handle the event data that is sent to it by the EventGateway server.
...
CiscoEventGateway::Callback::deliverEvents (in EventSeq events) {
... // Implement your event-handling code here.
}
Refer to the CiscoEventGateway.idl chapter in the Cisco VPN Solutions Center: MPLS Solution API Programmer Reference to understand the relationship between the EventSeq, Event, Msg, MsgField, MsgFieldSeq types.
After creating an CiscoEventGateway::EventGateway object and a CiscoEventGateway::Callback object in your source code, you can proceed to register the callback objects with the Event Gateway server.
...
// Declare and initialize variables.
string cbSubject = "";
string cbId = "";
long egTimeout = 60 * 60 * 24; // Expressed in seconds.
...
// Create a callback object and get an object reference to the
// CiscoEventGateway::EventGateway interface from the Event Gateway server:
// cbObjRef and egObjRef, respectively.
...
// Register or reregister cbObjRef with the Event Gateway server.
if (cbId == null) {
// New registration.
cbId = egObjRef.registerCallback(cbObjRef, egTimeout);
}
else {
// Requires persistent storage of cbId values to reregister upon restarting the
// client application.
egObjRef.reregisterCallback(cbId, cbObjRef, mTimeout);
}
...
// Deregister cbObjRef when its registration with the Event Gateway server is no
// longer needed.
egObjRef.deregisterCallback(cbId);
...
Use the CiscoEventGateway::EventGateway::registerCallback() operation to register a new CiscoEventGateway::Callback object—that is, its ID value is not already stored on the Event Gateway server—with the Event Gateway server. Here is the IDL signature for the registerCallback() operation:
string registerCallback(
in Callback callbackObject,
in long timeoutValue)
raises(FailedRegistration);
where:
When an event-delivery error occurs, delivery attempts continue until the specified timeoutValue is exceeded. If the event is successfully delivered within the specified time, the EventGateway server resumes normal delivery of events to the CiscoEventGateway::Callback object; if not, the Callback object is automatically deregistered.
The registerCallback() operation raises a CiscoEventGateway::FailedRegistration exception if the specified callbackObject is not successfully registered with the EventGateway server
Use the CiscoEventGateway::EventGateway::reregisterCallback() operation to:
Because the unique ID is required to reregister a CiscoEventGateway::Callback object, you must implement some form of persistent storage to track the callbackId values for all registered CiscoEventGateway::Callback objects. Here is the IDL signature for the reregisterCallback() operation:
string reregisterCallback(
in string callbackId,
in Callback callbackObject,
in long timeoutValue)
raises(InvalidCallbackId, FailedRegistration);
where:
If a CiscoEventGateway::Callback object is unable to accept event notifications for any reason, you can specify the callbackId value of the previously registered Callback object, and supply a new Callback object as the callbackObject to reestablish the connection between the EventGateway server queue for the original Callback object and the new callbackObject. Event delivery then resumes at the point in the queue where event notification ceased.
 |
Note This applies if and only if the original Callback object is unreachable for a period of time that does not exceed the specified timeoutValue. |
When an event-delivery error occurs, the CiscoEventGateway::Callback object is marked internally as inactive and event delivery is suspended. While event delivery to the CiscoEventGateway::Callback object is suspended, events are queued by the server, and it periodically attempts to deliver them. If successful, the Event Gateway server resumes normal delivery of events to the CiscoEventGateway::Callback object.
The reregisterCallback() operation raises a CiscoEventGateway::InvalidCallbackId exception if the specified callbackId is not recognized by the Event Gateway server. The reregisterCallback() operation raises a CiscoEventGateway::FailedRegistration exception if the specified callbackObject is not successfully registered with the Event Gateway server.
Use the CiscoEventGateway::EventGateway::deregisterCallback() operation to deregister a registered CiscoEventGateway::Callback object with the Event Gateway server. Here is the IDL signature for the reregisterCallback() operation:
void deregisterCallback(
in string callbackId)
raises(InvalidCallbackId);
where callbackId is the return value of the CiscoEventGateway::EventGateway::registerCallback() operation when initially registering a CiscoEventGateway::Callback object with the Event Gateway server.
Upon execution, any queued events are discarded, and the callbackId value is freed for re-use by the Event Gateway server. Also, any subject subscriptions are terminated upon execution of the deregisterCallback() operation.
The deregisterCallback() operation raises a CiscoEventGateway::InvalidCallbackId exception if the specified callbackId is not recognized by the Event Gateway server.
As a default, you can subscribe a maximum of ten CiscoEventGateway::Callback objects to a given subject.
Use the CiscoEventGateway::EventGateway::beginDelivery() operation to subscribe a registered CiscoEventGateway::Callback object to a specific subject of interest. Here is the IDL signature for the beginDelivery() operation:
void beginDelivery(
in string callbackId,
in string subject)
raises(InvalidCallbackId, FailedRegistration);
where:
Subjects are expressed as a.b.c. You can use a greater than sign (>) to indicate interest in one or more fields—a.b.> matches a.b.c and a.b.d.e but not a.b. Use can also use an asterisk (*) as a wildcard indicator for any single field—for example, a.b.* matches a.b.c but not a.b.c.d or a.b.
The beginDelivery() operation does not validate the specified subject. If a client specifies a subject that is not published by the Event Gateway server, no error is issued and no events are delivered.
If the beginDelivery() operation executes multiple times requesting delivery of events of the same subject, the second and subsequent beginDelivery() executions are ignored by the Event Gateway server. However, if overlapping subjects are registered—for example, both a.> and a.b are requested subject values—multiple copies of the same event may be delivered.
For any unique subject, events are delivered in the order they were generated. No order is guaranteed for events published to different subjects. As described in the preceding sections, a.> and a.b are considered different subjects.
The beginDelivery() operation raises a CiscoEventGateway::InvalidCallbackId exception if the specified callbackId is not recognized by the Event Gateway server. The beginDelivery() operation raises a CiscoEventGateway::FailedRegistration exception if the specified callbackObject is not successfully registered with the Event Gateway server.
Use the CiscoEventGateway::EventGateway::endDelivery() operation to terminate a subject subscription for a registered CiscoEventGateway::Callback object. Here is the IDL signature for the endDelivery() operation:
void endDelivery(
in string callbackId,
in string subject)
raises(InvalidCallbackId);
where:
The deregisterCallback() operation automatically terminates all subject subscriptions for the CiscoEventGateway::Callback object to be deregistered.
The endDelivery() operation raises a CiscoEventGateway::InvalidCallbackId exception if the specified callbackId is not recognized by the Event Gateway server.
Posted: Fri Sep 22 20:06:48 PDT 2000
Copyright 1989-2000©Cisco Systems Inc.