VisiBroker for C++ API Reference Guide : Event service interfaces and classes

Event service interfaces and classes
This section describes the interfaces and classes for the VisiBroker for C++ Event Service.
ConsumerAdmin
public interface ConsumerAdmin extends ConsumerAdminPOA
This interface is used by consumer applications to obtain a reference to a proxy supplier object. This is the second step in connecting a consumer application to an EventChannel.
IDL definition
module CosEventChannelAdmin {
interface
ConsumerAdmin {
ProxyPushSupplier obtain_push_supplier();
ProxyPullSupplier obtain_pull_supplier();
};
};
ConsumerAdmin methods
public ProxyPushSupplier obtain_push_supplier();
The obtain_push_supplier method should be invoked if the calling consumer application is implemented using the push model. If the application is implemented using the pull model, the obtain_pull_supplier method should be invoked.
public ProxyPullSupplier obtain_pull_supplier();
The returned reference is used to invoke either the connect_push_consumer, described in , or the connect_pull_consumer method, described in “ProxyPullConsumer”.
EventChannel
public interface EventChannel
The EventChannel provides the administrative operations for adding suppliers and consumers to the channel and for destroying the channel. For information on creating an event channel, see “EventChannelFactory”.
Suppliers and consumers both use the _bind method to obtain an EventChannel reference. As with any _bind invocation, the caller can optionally specify the object name of the desired EventChannel as well as any desired bind options. These arguments can be passed to the supplier or consumer as initial parameters or they may be obtained from the Naming Service, if it is available. If the object name is not specified, VisiBroker Edition locates a suitable EventChannel. Once a supplier or consumer is connected to an EventChannel, it may invoke any of the EventChannel methods.
IDL definition
module CosEventChannelAdmin {
interface EventChannel {
ConsumerAdmin for_consumers();
SupplierAdmin for_suppliers();
void destroy();
};
};
Methods
The following code sample shows the supplier binding to an EventChannel with the object name "power".
int main(int argc, char* const* argv)
{
...
CosEventChannelAdmin::EventChannel_var my_channel =
CosEventChannelAdmin::EventChannel::_bind("power");
CosEventChannelAdmin::SupplierAdmin_var =
channel->for_suppliers();
...
}
ConsumerAdmin for_consumers();
This method returns a ConsumerAdmin object that can be used to add consumers to this EventChannel.
SupplierAdmin for_suppliers();
This method returns a SupplierAdmin object that can be used to add suppliers to this EventChannel.
void destroy();
This method destroys this EventChannel.
EventChannelFactory
public interface EventChannelFactory
The EventChannelFactory provides methods for creating, locating, and destroying event channels.
IDL definition
module CosEventChannelAdmin {
interface
EventChannelFactory {
exception AlreadyExists();
exception ChannelsExist();
EventChannel create();
EventChannel create_by_name(in string name)
raises(AlreadyExists);
EventChannel lookup_by_name(in string name);
void destroy()
raises(ChannelsExist);
};
};
EventChannelFactory methods
EventChannel create();
This method creates an anonymous, transient event channel.
EventChannel create_by_name(in string name) raises(AlreadyExists);
This method creates a named, persistent event channel. If an event channel with the specified name has already been created, an AlreadyExists exception is raised.
EventChannel lookup_by_name(in string name);
This method attempts to return the EventChannel with the specified name. If no channel with the specified name exists, a NULL value is returned.
void destroy();
This method destroys this event channel. The disconnect methods of all suppliers and consumers connected to the channel are called before the channel is destroyed. Once destroyed, if the channel was created by the create_by_name method, it is no longer found by the lookup_by_name method.
ProxyPullConsumer
public interface ProxyPullConsumer
This interface is used by a pull supplier application and provides the connect_pull_supplier method for connecting the supplier's PullSupplier-derived object to the EventChannel. An AlreadyConnected exception is raised if an attempt is made to connect the same proxy more than once. It can also raise the TypeError exception if the proxy objects of an event channel implementation impose additional type constraints that are connected to them.
IDL definition
module CosEventChannelAdmin {
exception AlreadyConnected();
interface
ProxyPullConsumer : CosEventComm::PullConsumer {
void connect_pull_supplier(
in CosEventComm::PullSupplier pull_supplier)
raises(AlreadyConnected, TypeError);
};
};
ProxyPushConsumer
public interface ProxyPushConsumer
This interface is used by a push supplier application and provides the connect_push_supplier method which is used to connect the supplier's PushSupplier-derived object to the EventChannel. An AlreadyConnected exception is raised if an attempt is made to connect the same proxy more than once.
IDL definition
module CosEventChannelAdmin {
exception AlreadyConnected();
interface
ProxyPushConsumer : CosEventComm::PushConsumer {
void connect_push_supplier(
in CosEventComm::PushSupplier push_supplier)
raises(AlreadyConnected);
};
};
ProxyPullSupplier
public interface ProxyPullSupplier
This interface is used by a pull consumer application and provides the connect_pull_consumer method which is used for connecting the consumer's PullConsumer-derived object to the EventChannel. An AlreadyConnected exception is raised if an attempt is made to connect the same PullConsumer more than once.
IDL definition
module CosEventChannelAdmin {
exception AlreadyConnected();
interface
ProxyPullSupplier : CosEventComm::PullSupplier {
void connect_pull_consumer(
in CosEventComm::PullConsumer pull_consumer)
raises(AlreadyConnected);
};
};
ProxyPushSupplier
public interface ProxyPushSupplier
This interface is used by a push consumer application and provides the connect_push_consumer method which is used to connect the consumer's PushConsumer-derived object to the EventChannel. An AlreadyConnected exception is raised if an attempt is made to connect the same PushConsumer more than once. It can also raise the TypeError exception if the proxy objects of an event channel implementation impose additional type constraints that are connected to them.
IDL definition
module CosEventChannelAdmin {
exception AlreadyConnected();
interface
ProxyPushSupplier : CosEventComm::PushSupplier {
void connect_push_consumer(
in CosEventComm::PushConsumer push_consumer)
raises(AlreadyConnected, TypeError);
};
};
PullConsumer
public interface PullConsumer
This interface is used to derive consumer objects that use the pull model of communication. The pull method is called by a consumer whenever it wants data from the supplier. A Disconnected exception is raised if the supplier has disconnected.
The disconnect_pull_consumer method is used to deactivate this consumer if the channel is destroyed.
IDL definition
module CosEventComm {
exception Disconnected {};
interface
PullConsumer {
void push(in any data) raises(Disconnected);
void disconnect_pull_consumer();
};
};
PushConsumer
public interface PushConsumer
This interface is used to derive consumer objects that use the push model of communication. The push method is used by a supplier whenever it has data for the consumer. A Disconnected exception is raised if the consumer has disconnected.
IDL definition
module CosEventComm {
exception Disconnected();
interface
PushConsumer {
void push(in any data) raises(Disconnected);
void disconnect_push_consumer();
};
};
PullSupplier
public interface PullSupplier
This interface is used to derive supplier objects that use the pull model of communication.
IDL definition
module CosEventComm {
interface
PullSupplier {
any pull() raises(Disconnected);
any try_pull(out boolean has_event) raises(Disconnected);
void disconnect_pull_supplier();
};
};
PullSupplier methods
any pull();
This method blocks until there is data available from the supplier. The data is returned an Any type. If the consumer has disconnected, this method raises a Disconnected exception.
any try_pull(out boolean has_event);
This non-blocking method attempts to retrieve data from the supplier. When this method returns, has_event is set to the valuetrue and the data is returned as an Any type if there was data available. If the value of has_event is false, then no data is available and the return value is NULL.
void disconnect_pull_supplier();
This method deactivates this pull server if the channel is destroyed.
PushSupplier
public interface PushSupplier
This interface is used to derive supplier objects that use the push model of communication. The disconnect_push_supplier method is used by the EventChannel to disconnect supplier when it is destroyed.
IDL definition
module CosEventComm {
exception AlreadyConnected();
interface
PushSupplier {
void disconnect_push_supplier();
};
};
SupplierAdmin
public interface SupplierAdmin
This interface is used by supplier applications to obtain a reference to the proxy consumer object. This is the second step in connecting a supplier application to an EventChannel.
IDL definition
module CosEventChannelAdmin {
interface
SupplierAdmin {
ProxyPushConsumer obtain_push_consumer();
ProxyPullConsumer obtain_pull_consumer();
};
};
public ProxyPushConsumer obtain_push_consumer();
The obtain_push_consumer method should be invoked if the supplier application is implemented using the push model. If the application is implemented using the pull model, the obtain_pull_consumer method should be invoked.
public ProxyPullConsumer obtain_pull_consumer();
The returned reference is used to invoke either the connect_push_supplier or the connect_pull_supplier method.