org.omg.CosNotifyComm
Interface SequencePullSupplierOperations

All Superinterfaces:
NotifySubscribeOperations
All Known Subinterfaces:
SequenceProxyPullSupplier, SequenceProxyPullSupplierOperations, SequencePullSupplier
All Known Implementing Classes:
_SequenceProxyPullSupplierStub, _SequencePullSupplierStub, SequenceProxyPullSupplierImpl, SequenceProxyPullSupplierPOA, SequenceProxyPullSupplierPOATie, SequencePullSupplierPOA, SequencePullSupplierPOATie

public interface SequencePullSupplierOperations
extends NotifySubscribeOperations

The SequencePullSupplier interface supports operations which enable suppliers to transmit sequences of 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 SequencePullSupplier 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 SequencePullSupplier 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 sequence of Structured Events. How events supplied to the channel in the form of a sequence of Structured Events are internally mapped into different forms for delivery to consumers which receive events in a form other than the a sequence of Structured Events is summarized in Table 2-2.


Method Summary
 void disconnect_sequence_pull_supplier()
          The disconnect_sequence_pull_supplier operation is invoked to terminate a connection between the target SequencePullSupplier, and its associated consumer.
 StructuredEvent[] pull_structured_events(int max_number)
          The pull_structured_events operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the CosNotification module.
 StructuredEvent[] try_pull_structured_events(int max_number, org.omg.CORBA.BooleanHolder has_event)
          The try_pull_structured_events operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the CosNotification module.
 
Methods inherited from interface org.omg.CosNotifyComm.NotifySubscribeOperations
subscription_change
 

Method Detail

pull_structured_events

StructuredEvent[] pull_structured_events(int max_number)
                                         throws Disconnected
The pull_structured_events operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the CosNotification module. This data type is the same as a sequence of Structured Events. Upon invocation, the operation will block until a sequence of Structured Events is available for transmission, at which time it will return the sequence containing events being delivered to its connected consumer. If invoked upon a SequencePullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised. Note that the maximum length of the sequence returned will never exceed the value of the input parameter. In addition, the amount of time the supplier will accumulate events into the sequence before transmitting it, along with the maximum size of any sequence it will transmit (regardless of the input parameter), are controlled by QoS property settings as described in section 2.5.5. In reality there are two types of objects that will support the SequencePullSupplier interface: an object representing an application which transmits sequences of Structured Events, and a SequenceProxyPullSupplier (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_events operation is application specific, and is intended to be supplied by application developers. The application specific implementation of this operation should construct a sequence of Structured Events, and return it within a EventBatch 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 sequence of Structured Events, within an EventBatch data structure, as the return value to the consumer it is connected to upon the availability of events which pass the filter(s) associated with the SequenceProxyPullSupplier. Note that the operation will block until there is a sequence available to return.

Throws:
Disconnected

try_pull_structured_events

StructuredEvent[] try_pull_structured_events(int max_number,
                                             org.omg.CORBA.BooleanHolder has_event)
                                             throws Disconnected
The try_pull_structured_events operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the CosNotification module. This data type is the same as a sequence of Structured Events. The operation also returns an output parameter of type boolean which indicates whether or not the return value actually contains a sequence of events. Upon invocation, the operation will return a sequence of a Structured Events which contains events being delivered to its connected consumer, if such a sequence is available for delivery at the time the operation was invoked. If an event sequence is available for delivery and thus returned as the result, the output parameter of the operation will be set to TRUE. If no event sequence 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 sequence. If invoked upon a SequencePullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised. Note that the maximum length of the sequence returned will never exceed the value of the input parameter. In reality there are two types of objects that will support the SequencePullSupplier interface: an object representing an application which transmits sequences of Structured Events, and a SequenceProxyPullSupplier (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_events operation is application specific, and is intended to be supplied by application developers. If an event sequence is available to be returned upon invocation of this operation, the application specific implementation of this operation should construct an EventBatch instance, and return it 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 sequence is available to be returned upon invocation of this operation, it is responsible for forwarding it, within an EventBatch 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 sequence 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.

Throws:
Disconnected

disconnect_sequence_pull_supplier

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