org.omg.CosNotifyComm

Interface StructuredPullSupplierOperations

public interface StructuredPullSupplierOperations extends NotifySubscribeOperations

The StructuredPullSupplier interface supports operations which enable suppliers to transmit Structured Events by the pull model. It also defines an operation which can be invoked to disconnect the pull supplier from its associated consumer. In addition, the StructuredPullSupplier interface inherits the NotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving. Note that an object supporting the StructuredPullSupplier interface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a Structured Event. How events supplied to the channel in the form of a Structured Event are internally mapped into different forms for delivery to consumers which receive events in a form other than the Structured Event is summarized in Table 2-2.
Method Summary
voiddisconnect_structured_pull_supplier()
The disconnect_structured_pull_supplier operation is invoked to terminate a connection between the target StructuredPullSupplier, and its associated consumer.
StructuredEventpull_structured_event()
The pull_structured_event operation takes no input parameters, and returns a value of type Structured Event as defined in the CosNotification module.
StructuredEventtry_pull_structured_event(BooleanHolder has_event)
The try_pull_structured_event operation takes no input parameters, and returns a value of type StructuredEvent as defined in the CosNotification module.

Method Detail

disconnect_structured_pull_supplier

public void disconnect_structured_pull_supplier()
The disconnect_structured_pull_supplier operation is invoked to terminate a connection between the target StructuredPullSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPullSupplier will release all resources it had allocated to support the connection, and dispose its own object reference.

pull_structured_event

public StructuredEvent pull_structured_event()
The pull_structured_event operation takes no input parameters, and returns a value of type Structured Event as defined in the CosNotification module. Upon invocation, the operation will block until an event is available for transmission, at which time it will return an instance of a Structured Event which contains the event being delivered to its connected consumer. If invoked upon a StructuredPullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised. In reality there are two types of objects that will support the StructuredPullSupplier interface: an object representing an application which transmits Structured Events, and a StructuredProxyPullSupplier (defined in the CosNotifyChannelAdmin module) associated with an event channel which transmits events to a pull style consumer on behalf of the channel. For the first type of object, the implementation of the pull_structured_event operation is application specific, and is intended to be supplied by application developers. The application specific implementation of this operation should construct a structured event, and return it within a StructuredEvent data structure. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for forwarding a structured event, within an StructuredEvent data structure, as the return value to the consumer it is connected to upon the availability of an event which passes the filter(s) associated with the StructuredProxyPullSupplier. Note that the operation will block until such an event is available to return.

try_pull_structured_event

public StructuredEvent try_pull_structured_event(BooleanHolder has_event)
The try_pull_structured_event operation takes no input parameters, and returns a value of type StructuredEvent as defined in the CosNotification module. It also returns an output parameter of type boolean which indicates whether or not the return value actually contains an event. Upon invocation, the operation will return an instance of a Structured Event which contains the event being delivered to its connected consumer, if such an event is available for delivery at the time the operation was invoked. If an event is available for delivery and thus returned as the result, the output parameter of the operation will be set to TRUE. If no event is available to return upon invocation, the operation will return immediately with the value of the output parameter set to FALSE. In this case, the return value will not contain a valid event. If invoked upon a StructuredPullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised. In reality there are two types of objects that will support the StructuredPullSupplier interface: an object representing an application which transmits Structured Events, and a StructuredProxyPullSupplier (defined within the CosNotifyChannelAdmin module) associated with an event channel which transmits events to a PullConsumer on behalf of the channel. For the first type of object, the implementation of the try_pull_structured_event operation is application specific, and is intended to be supplied by application developers. If an event is available to be returned upon invocation of this operation, the application specific implementation of this operation should construct a Structured Event, and return it within a StructuredEvent data structure along with setting the value of the output parameter to TRUE. Otherwise, the operation should return immediately after setting the value of the output parameter to FALSE. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, if an event is available to be returned upon invocation of this operation, it is responsible for forwarding it, within a StructuredEvent data structure, as the return value to the consumer it is connected to, in addition to setting the output parameter to FALSE. If no event is available to return to the consumer upon invocation of this operation, it will immediately return with the output parameter to set to FALSE, and the return value not containing a valid event.