The SequencePullSupplier Interface

TheSequencePullSupplierinterface supports operations that enable suppliers to transmit sequences of Structured Events by the pull model. It also defines an operation that can be invoked to disconnect the pull supplier from its associated consumer. In addition, theSequencePullSupplierinterface inherits theNotifySubscribe

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 theSequencePullSupplierinterface can transmit events that can potentially be received by any consumer connected to the channel, including those that 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 a sequence of Structured Events is summarized in Table 2-2 on page 2-9.

3.3.13.1 pull_structured_events

Thepull_structured_eventsoperation takes as an input parameter a numeric value, and returns a value of typeEventBatchas defined in theCosNotificationmodule. 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 aSequencePullSupplierthat is not currently connected to the consumer of the event, theDisconnectedexception will be raised. Note that the condition that a proxy consumer believes it is actively connected to a supplier, while the supplier believes it is disconnected is an invalid state. Thus, if the invocation ofpull_structured_eventsupon aSequencePullSupplierinstance by aSequenceProxyPullConsumerinstance results in theDisconnectedexception being raised, theSequenceProxyPullConsumerwill invoke its own

disconnect_sequence_pull_consumeroperation, resulting in the destruction of thatSequenceProxyPullConsumerinstance.

Note that the maximum length of the sequence returned will never exceed the value of the input parameter. In addition, when this operation is invoked upon a

SequenceProxyPullSupplier, the amount of time the supplier will accumulate events into the sequence before transmitting it is controlled by the PacingInterval QoS property described in Section 2.5.5, “Notification QoS Properties,” on page 2-37. In this case, the proxy will never return a sequence of less thanMaximumBatchSize

events until at leastPacingIntervalamount of time has elapsed after the request was received by the proxy. However if no events arrived at the proxy during a particular

PacingInterval, the request will block until at least one event arrives at the proxy. Also note thatMaximumBatchSizeplaces an upper boundary on the total number of events the proxy will return within an invocation. If the input parameter indicates more thanMaximumBatchSizeevents are being requested, the request will be treated as though the input parameter was equivalent toMaximumBatchSize.

In reality there are two types of objects that will support theSequencePullSupplier

interface: an object representing an application which transmits sequences of Structured Events, and aSequenceProxyPullSupplier(defined in the

CosNotifyChannelAdminmodule) 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 thepull_structured_eventsoperation 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 aEventBatchdata 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

EventBatchdata 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.

3.3.13.2 try_pull_structured_events

Thetry_pull_structured_eventsoperation takes as an input parameter a numeric value, and returns a value of typeEventBatchas defined in theCosNotification

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 aSequencePullSupplierthat is not currently connected to the consumer of the event, theDisconnectedexception will be raised. Note that the condition that a proxy consumer believes it is actively connected to a supplier, while the supplier believes it is disconnected is an invalid state. Thus, if the invocation oftry_pull_structured_eventsupon a

SequencePullSupplierinstance by aSequenceProxyPullConsumerinstance results in theDisconnectedexception being raised, the

SequenceProxyPullConsumerwill invoke its own

disconnect_sequence_pull_consumeroperation, resulting in the destruction of thatSequenceProxyPullConsumerinstance.

Note that the maximum length of the sequence returned will never exceed the value of the input parameter. Also note thatMaximumBatchSizeplaces an upper boundary on the total number of events the proxy will return within an invocation. If the input parameter indicates more thanMaximumBatchSizeevents are being requested, the request will be treated as though the input parameter was equivalent to

MaximumBatchSize.

In reality there are two types of objects that will support theSequencePullSupplier

interface: an object representing an application which transmits sequences of Structured Events, and aSequenceProxyPullSupplier(defined within the

CosNotifyChannelAdminmodule) associated with an event channel which transmits events to aPullConsumeron behalf of the channel. For the first type of object, the implementation of thetry_pull_structured_eventsoperation 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 anEventBatchinstance, 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 anEventBatchdata 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.

3.3.13.3 disconnect_sequence_pull_supplier

Thedisconnect_sequence_pull_supplieroperation is invoked to terminate a connection between the targetSequencePullSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the targetSequencePullSupplierwill release all resources it had allocated to support the connection, and dispose its own object reference.