The ProxySupplier Interface

TheProxySupplierinterface is intended to be an abstract interface that is inherited by the different varieties of proxy suppliers that can be instantiated within a

notification channel. It encapsulates the behaviors common to all Notification Service proxy suppliers. In particular, theProxySupplierinterface inherits theQoSAdmin

interface defined within theCosNotificationmodule, and theFilterAdmininterface defined within theCosNotifyFiltermodule. The former inheritance enables all proxy suppliers to administer a list of associated QoS properties, while the latter inheritance enables all proxy suppliers to administer a list of associated filter objects. Locally, the

ProxySupplierinterface defines a readonly attribute that should be set upon creation of each proxy supplier instance to indicate the specific type of proxy supplier the instance represents, and a readonly attribute which maintains a reference to the

ConsumerAdminobject that created it. In addition, theProxySupplierinterface defines attributes that associate with each proxy supplier two mapping filter objects, one for priority and one for lifetime. As described in Section 2.3.1, “Mapping Filter Objects,” on page 2-21, these mapping filter objects enable proxy suppliers to be configured to alter the way they treat events with respect to their priority and lifetime based on the type and contents of each individual event. Lastly, theProxySupplier

interface defines an operation that returns the list of event types that a given proxy supplier could potentially forward to its associated consumer, and an operation which can be queried to determine which message level QoS properties can be set on a per- event basis.

3.4.2.1 MyType

TheMyTypeattribute is a readonly attribute that should be set upon creation of each proxy supplier instance to indicate the specific type of proxy supplier the instance represents. Enumerations are possible to distinguish the type of proxy supplier among the following possibilities:ProxyPushSupplier,ProxyPullSupplier,

StructuredProxyPushSupplier,StructuredProxyPullSupplier,

SequenceProxyPushSupplier,SequenceProxyPullSupplier,

TypedProxyPushSupplier, andTypedProxyPullSupplier.

3.4.2.2 MyAdmin

TheMyAdminattribute is a readonly attribute that should be set upon creation of each proxy supplier instance to maintain the reference of the instance supporting the

3.4.2.3 priority_filter

Thepriority_filterattribute contains a reference to an object supporting the

MappingFilterinterface defined in theCosNotifyFiltermodule. Such an object encapsulates a list of constraint-value pairs, where each constraint is a boolean expression based on the type and contents of an event, and the value is a possible priority setting for the event. Upon receipt of each event by a proxy supplier object whosepriority_filterattribute contains a non-nil reference, the proxy supplier will invoke the appropriate variant of thematchoperation supported by the mapping filter object. The mapping filter object will proceed to apply its encapsulated constraints to the event, and return the one with the highest associated priority setting that evaluates to TRUE, or else its associateddefault_valueif no constraints evaluate to TRUE. Upon return from thematchoperation, if the output parameter is TRUE, the proxy supplier treats the event with respect to its priority according to the return value, as opposed to a priority setting contained within the event. If the output parameter is FALSE, the proxy supplier will treat the event with respect to its priority according to the value set for the priority property in the event header if this property is present, otherwise it will use the output parameter returned from thematchoperation (i.e., the default value of the mapping filter object).

3.4.2.4 lifetime_filter

Thelifetime_filterattribute contains a reference to an object supporting the

MappingFilterinterface defined in theCosNotifyFiltermodule. Such an object encapsulates a list of constraint-value pairs, where each constraint is a boolean expression based on the type and contents of an event, and the value is a possible lifetime setting for the event. Upon receipt of each event by a proxy supplier object whoselifetime_filterattribute contains a non-nil reference, the proxy supplier will invoke the appropriate variant of the match operation supported by the mapping filter object. The mapping filter object will proceed to apply its encapsulated constraints to the event, and return the one with the highest associated lifetime setting which evaluates to TRUE, or else its associateddefault_valueif no constraints evaluate to TRUE. Upon return from thematchoperation, if the output parameter is TRUE, the proxy supplier treats the event with respect to its lifetime according to the return value, as opposed to a lifetime setting contained within the event. If the output parameter is FALSE, the proxy supplier will treat the event with respect to its lifetime according to the value set for the lifetime property in the event header if this property is present, otherwise it will use the output parameter returned from thematchoperation (i.e., the default value of the mapping filter object).

3.4.2.5 obtain_offered_types

Theobtain_offered_typesoperation returns a list of event type names. Each element of the returned list names a type of event that the target proxy supplier object could potentially forward to its associated consumer. Note that through inheritance, all proxy consumer objects will support theNotifyPublishinterface defined in the

CosNotifyCommmodule. This interface supports theoffer_changeoperation, which can be invoked by suppliers each time there is a change to the list of event types they plan to supply to their associated consumer. Thus, this mechanism relies on event

suppliers keeping the channel informed of the types of events they plan to supply by invoking theoffer_changeoperation on their associated proxy consumer object. Internally to the channel, the proxy consumers will share the information about event types that will be supplied to the channel with the proxy supplier objects associated with the channel. This enables consumers to discover the types of events that could be supplied to them by the channel by invoking theobtain_offered_typesoperation on their associated proxy supplier.

Note that as mentioned above, consumers can also receive updates to offer information automatically by enabling the channel to invoke theoffer_changeoperation they support through inheritence of theCosNotifyComm::NotifyPublishinterface each time a supplier informs the channel of a change to the types of events they plan to supply. Theobtain_offered_typesoperation accepts as input a flag that enables synchronization between the offer information obtained through these automatic updates, and that obtained through invocation ofobtain_offered_types. The possible values and associated meanings this flag can take on are similar to those summarized in Table 3-1 on page 3-52, except that the information being shared is “offer” information instead of “subscription” information.

3.4.2.6 validate_event_qos

Thevalidate_event_qosoperation accepts as input a sequence of QoS property name-value pairs which specify a set of QoS settings that a client is interested in setting on a per-event basis. Note that the QoS property settings contained in the optional header fields of a Structured Event may differ from those that are configured on a given proxy object. This operation is essentially a check to see if the target proxy object will honor the setting of a set of QoS properties on a per-event basis to values that may conflict with those set on the proxy itself. If any of the requested settings would not be honored by the target object on a per-event basis, the operation raises the UnsupportedQoSexception. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-5 on page 2-46.

If all requested QoS property value settings could be satisfied by the target object, the operation returns successfully with an output parameter that contains a sequence of

PropertyRangedata structures. Each element in this sequence includes the name of an additional QoS property whose setting is supported by the target object on a per- event basis and which could have been included on the input list while still resulting in a successful return from the operation. Each element also includes the range of values that would have been acceptable for each such property.