org.omg.CosNotifyComm
Interface SequencePullSupplierOperations
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, 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.
|
public 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.
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.
public
StructuredEvent[] try_pull_structured_events(int max_number, 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.
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.