Setting the Quality of Service and Filters

This chapter discusses how to set up the notification channel using event types and configuring with Filters and QoS properties.

Properties of the Quality of Service (QoS)

The policies set with QoS allow the application to dynamically adjust the service parameters of the channel during runtime. VisiNotify specifies its own QoS policies as well as supports a subset of the OMG-specified QoS. The following are the QoS properties that VisiNotify supports:

Priority

Setting/getting of Priority QoS is supported as per the OMG standard. Priority is represented as a short value, where -32,767 is the lowest priority and 32,767 the highest. The default priority for all events is 0 (zero). Priority can be set at message, proxy, admin, or channel levels. Note that setting this property on a per-ConsumerAdmin or per-proxy supplier basis has no meaning.

EventReliability

EventReliability QoS is supported as per the OMG standard. For performance reasons, each individual proxy supplier is not guaranteed to remember persistently what events it has sent to its associated consumer. Therefore, an event can be sent to a consumer more than once if the event channel crashes and restarts.

VBPersistentDbType

This property specifies the type of persistent storage being used for persisting events by the channel. VisiNotify stores persistent events either in memory mapped files or flat files depending on the value of this property. A value of (CORBA::Short)1 implies memory mapped persistency. A value of (CORBA::Short)2 implies flat file persistency.

The default is memory mapped persistency.

VBPersistentCommitSyncPolicy

The VBPersistentCommitSyncPolicy property specifies whether the channel should acknowledge a supplier only after successfully committing the event into persistent storage.

The constant values setting are:

•	True - a channel acknowledges a supplier only after successfully committing a event into persistent storage.

•	False (default) - a channel can acknowledge supplier (such as, return from a push() call) immediately before committing the event into persistent storage and perform a lazy commit, afterwards.

VBPersistentStorageOverflowBlockTimeout

There are times when a new event arrives in the channel and needs to be made persistent. However, there is a possibility that persistent storage is already full. To avoid this problem, the supplier can be blocked until space becomes available in persistent storage.

The VBPersistentStorageOverflowBlockTimeout property specifies how long the supplier should be blocked to wait for persistent storage to be freed up. Upon expiration of this time interval, the channel will attempt to downgrade one or more events to BestEffort to accommodate the new event (see “VBPersistentOverflowDowngradePolicy”).

The default value of this property is 0, meaning that the channel will not block, but instead it immediately attempts to downgrade queued events according to VBPersistentOverflowDowngradePolicy.

VBPersistentOverflowDowngradePolicy

The VBPersistentOverflowDowngradePolicy property controls how the channel will downgrade existing events to make way for a new (persistent) event if no space can be found in persistent storage despite waiting for VBPersistentStorageOverflowBlockTimeout seconds. If an event is downgraded, this means that its EventReliability is automatically set to BestEffort, regardless of the message/channel settings.

The constant values setting are:

•	AnyOrder (default) - Lifo is used.

•	FifoOrder - Events in the queue are downgraded in ascending order of the time of receipt of the event.

•	LifoOrder - The new event is downgraded.

Note

If an event by itself cannot fit into persistent storage, it is downgraded immediately.

ConnectionReliability

ConnectionReliability is supported as per the OMG standard.

If ConnectionReliability is set to Persistent (at the appropriate channel/admin/proxy), VisiNotify attempts to recover the following:

1	All persistent channels with original policies, ids, IOR (of the channel) and all included events.

2	All persistent admins with original policies, ids, and IOR.

3	All persistent proxies with original policies, ids, IOR, attached suppliers/consumers.

If the ConnectionReliability of a proxy is not specified explicitly through set_qos(), then the default value is used for active proxies. For example, for proxy pull consumers and proxy push suppliers default to a setting of Persistent and the default for passive proxies are described for vbroker.notify.channel.passiveProxyPersistenceMask.

MaxEventsPerConsumer

The MaxEventsPerConsumer is supported as per the OMG standard.

DiscardPolicy

To facilitate implementation, such as persistent storage management, only OMG's AnyOrder, FifoOrder and LifoOrder are supported.

OrderPolicy

This QoS property sets the policy used by a given proxy to order the events it has buffered for delivery (either to another proxy or a consumer). AnyOrder, FifoOrder (default) and PriorityOrder are supported.

Note

This property has no meaning if set on a per-message basis.

VBQueueLowWaterMark

After the number of pending events in a proxy supplier queue has breached the VBQueueHighWaterMark level, (this is when a number of pending events subsequently falls below this value), this proxy informs the channel(s) to take the necessary action of unblocking or speeding up pushing and pulling event into the channel. See section on Flow Control for more details.

The default value for VBQueueLowWaterMark is 32.

VBQueueHighWaterMark

When the number of pending events in a proxy supplier queue is higher than the set value, this proxy informs the channel accordingly so that the channel can take action if necessary to block or slow down the rate of pushing and pulling events into the channel. See section on Flow Control for more details.

The default value for VBQueueHighWaterMark is computed by VisiNotify and depends on the user defined setting of the channel queue size (the channel's admin property) and the VBQueueLowWaterMark setting.

VBProxyPushSupplierThreadModel

Each proxy push supplier needs a thread to push the events in its queue to the connected push consumer. This property specifies whether a proxy should use a dedicated thread or a thread pool to push events.

Valid values are “dedicated” or “pool” with “pool” being the default value. Any illegal value is silently ignored. For additional information, see the static property section on configuring the thread pool. Setting this property on the channel or consumer admin will make all sub objects inherit this value. Setting this property on the supplier admin or any other type of proxy has no meaning and will be silently ignored.

VBProxyPushSupplierQueuePreemptWaterMark

This property is used to fine-tune the thread pool behavior and is applicable only when the VBProxyPushSupplierThreadModel is set to “pool” and the thread pool is restricted to have a finite number of threads to serve the proxy push suppliers. A proxy push object picks up a thread from the thread pool to push events to the connected thread pool. If this proxy object has a lot of pending events, it may end up hogging the thread, leaving other proxies starved. To have a control over this situation, a watermark in the queue of each proxy object can be set, so that on hitting the watermark, the thread gets preempted to serve a different proxy push supplier object.

The default value is computed by VisiNotify and depends on the queue size.

VBReceivedEventsCount

Indicates the number of events received. Trying to set any value on this property by using the set_qos API resets the counter to 0. The actual value passed in will be ignored.

VBPendingEventsCount

This is a read-only property and indicates the number of events pending in the queue.

VBDiscardedEventsCount

Indicates the number of events discarded due to queue overflow. Trying to set any value on this property by using the set_qos API resets the counter to 0. The actual value passed in will be ignored.

VBForwardedEventsCount

Indicates the total number of events forwarded downstream. Trying to set any value on this property by using the set_qos API resets the counter to 0. The actual value passed in will be ignored.

VBFilteredEventsCount

Indicates the total number of events discarded due to failed filter match. Trying to set any value on this property by using the set_qos API resets the counter to 0. The actual value passed in will be ignored.

Administration and Validation of QoS properties

The following interfaces and methods are supported for administration of QoS properties:

Interface CosNotification::QoSAdmin

This interface is supported by channels, supplier/consumer admins and proxy suppliers/consumers and allows clients of these objects to obtain and set the QoS properties.

However, there are some limitations on the level of support:

•	If set_qos() is passed a VisiBroker-specific QoS, and the property value is bad, it is silently ignored and no exception is thrown. Exception is thrown for only OMG specified QoS.

•	The propagation of QoS changes is passed down the channel/admin/proxy hierarchy only for OMG specified QoS and not VisiBroker-specific QoS.

Validating QoS in the header of structured events

This is not currently supported.

QoS negotiation

The following QoS negotiation APIs are not currently supported, including:

•	CosNotification::QoSAdmin::validate_qos()

•	CosNotifyChannelAdmin::ProxySupplier::validate_event_qos()

•	CosNotifyChannelAdmin::ProxyConsumer::validate_event_qos()

Channel Admin Properties

The following interfaces are supported for the Channel Admin:

Interface CosNotification::AdminPropertiesAdmin

This interface is supported by the notification and typed notification event channels. It is used to retrieve and set the admin properties on the channel(s).

The following OMG defined properties are supported:

•	MaxQueueLength

•	MaxConsumers

•	MaxSuppliers

•	RejectNewEvents

VBPersistentStorageSize

A persistent event (for instance, a channel that has EventReliability set to persistent) needs to be stored in persistent storage. This admin property allows restriction on the size of the storage space to prevent VisiNotify from overrunning the disk space. VisiNotify stores persistent events in files. This admin property specifies the maximum size of this file in kilobytes.

The default value for VBPersistentStorageSize is 1024. Its type is CORBA::Ulong.

Static Properties

Unlike the QoS properties, the Static properties can be set only at startup time of the Notification Service and not during the execution of the service. The Static properties are specified just like any VisiBroker ORB properties such as, using -D<property_name>=<property_value>.

The following properties are supported:

vbroker.notify.console

vbroker.notify.console = <Boolean>

This property controls the Notification Service to display the message, “Notification Service is ready” in the VisiBroker Console.

The supported values for the vbroker.notify.console property are:

•	True (default) - prints the message.

•	False - does not print the message.

vbroker.notify.listener.port

vbroker.notify.listener.port = <ULong>

This is an alias for vbroker.se.iiop_tp.scm.iiop_tp.listener.port.

The default value of the vbroker.notify.listener.port property is 14100.

vbroker.notify.factory.name

vbroker.notify.factory.name = <string>

The vbroker.notify.factory.name property specifies the default factory name, which is created by the Notification Service. The application can do a _bind() to obtain a reference to the factory instead of doing a resolve_initial_references().

The default value of this property is VisiNotifyChannelFactory.

vbroker.notify.channel.name

vbroker.notify.channel.name = <string>

The vbroker.notify.channel.name property specifies the name of the default channel that is created by the Notification Service. The application can do a _bind() to obtain a reference to the default channel instead of having to explicitly create one.

The default value of this property is default_channel.

vbroker.notify.channel.threadMaxIdle

vbroker.notify.channel.threadMaxIdle = <ULong>

The vbroker.notify.channel.threadMaxIdle property specifies that if a channel/proxy push supplier has waited for threadMaxIdle seconds and no event arrives in the queue during this time, the channel will release the thread that waits for events. The channel will restart the thread when a new event arrives.

The default value of this property is three seconds.

vbroker.notify.enableEventQoS

vbroker.notify.enableEventQoS = <Boolean>

The vbroker.notify.enableEventQoS property specifies whether the channel should make use of event-level QoS to deliver an event. If set to True, the performance of the channel is significantly degraded.

The supported values are:

•	True - the channel will make use of event-level QoS when delivering event, such as EventReliability.

•	False (default) - the channel ignores event-level QoS when delivering an event. Instead, the QoS setting at the proxy/admin/channel is adopted.

vbroker.notify.dir

vbroker.notify.dir = <string>

The vbroker.notify.dir specifies the file directory or database table name of the VisiNotify persistent storage root. If the ConnectionPersistence QoS is set at the appropriate levels, VisiNotify will persist the following objects in the repository (depending on EventReliability and ConnectionReliability QoS policy):

•

events

•

channels

•	consumer and supplier admins

•

proxies

•	channel admin properties, QoS, filters

The default value of this property is ./visinotify.dir.

vbroker.notify.ir

vbroker.notify.ir = <string>

The vbroker.notify.ir property specifies the IR to be used by VisiNotify. The string that is specified can either be an IOR or a URL string (for example, corbaloc).

The default value of this property is null. In this case, VisiNotify tries to bind to the IR using osagent.

vbroker.notify.channel.persistentStorageSize

vbroker.notify.channel.persistentStorageSize = <ULong>

The vbroker.notify.channel.persistentStorageSize property is similar to the VBPersistentStorageSize channel admin property, except that it is used only for the first time the channel is started. Subsequently, VisiNotify will retrieve the current setting from persistent storage.

The default value of this property is VBPersistentStorageSize.

vbroker.notify.channel.persistentCommitPolicy

vbroker.notify.channel.persistentCommitPolicy = <Boolean>

The vbroker.notify.channel.persistentCommitPolicy property is similar to VBPersistentCommitSyncPolicy, except that it is used only the first time the channel is started. Subsequently, VisiNotify will retrieve the current setting from persistent storage.

The default value of this property is VBPersistentCommitSyncPolicy.

vbroker.notify.channel.persistentOverflowBlock
Timeout

vbroker.notify.channel.persistentOverflowBlockTimeout = <ULong>

The vbroker.notify.channel.persistentOverflowBlockTimeout property is similar to VBPersistentStorageOverflowBlockTimeout, with the exception that vbroker.notify.channel.persistentOverflowBlockTimeout is used only during the initial start up of the channel. Subsequently, VisiNotify will retrieve the current setting from persistent storage.

The default value of this property is VBPersistentStorageOverflowBlockTimeout.

vbroker.notify.channel.persistentDowngradePolicy

vbroker.notify.channel.persistentDowngradePolicy = <ULong>

The vbroker.notify.channel.persistentDowngradePolicy property is similar to VBPersistentOverflowDowngradePolicy, with the exception that vbroker.notify.channel.persistentDowngradePolicy is used only during the initial start up of the channel. Subsequently, VisiNotify will retrieve the current setting from persistent storage.

The valid values supported are:

•	AnyOrder (0)

•	FifoOrder (1)

•	LifoOrder (4)

If the value is set to anything else, the channel silently adopts a value of 0 (AnyOrder).

vbroker.notify.channel.persistentEvent

vbroker.notify.channel.persistentEvent = <Boolean>

The vbroker.notify.channel.persistentEvent property is similar to EventReliability, with the exception that it is used only during the initial start up of the channel. Subsequently, VisiNotify will retrieve the current setting from persistent storage.

A value of True sets the channel's EventReliability to Persistent, otherwise, it is set to BestEffort.

vbroker.notify.channel.iorFile

vbroker.notify.channel.iorFile = <string>

The vbroker.notify.channel.iorFile property specifies the filename where VisiNotify can dump the IOR of the default channel. It uses the same syntax as in 3.x version, -ior <filename> option.

The default value of this property is null.

vbroker.notify.channel.passiveProxyPersistenceMask

vbroker.notify.channel.passiveProxyPersistenceMask = <Boolean>

In general, it may not be necessary to persist a passive proxy (proxy push consumer or proxy pull supplier) because after a system crashes and restart, the user of such a proxy may no longer exist.

This property is used to derive the default ConnectionReliability setting of a passive proxy, using the following setting:

•	let admin's persistence setting = 1 if admin's ConnectionReliability = Persistent, else let it be 0.

•	default persistence of proxy = (this property setting) && (its admin's persistence setting)

If this default persistence has a value of True, the default ConnectionReliability setting of a passive proxy is set to Persistent, otherwise, it is set to BestEffort.

The default value of this property is False.

vbroker.notify.channel.maxDelay

vbroker.notify.channel.maxDelay = <ULong>

The vbroker.notify.channel.maxDelay property is a setting that controls the delay (in milliseconds) that a proxy push supplier conditionally applies when delivering an event to its consumer. It also can be used to tune the performance of the channel.

The default value of this property is 2000 milliseconds. The minimum and maximum values are 20 and 2000, respectively.

vbroker.notify.threadPool.threadMax

vbroker.notify.threadPool.threadMax = <ULong>

This property specifies the maximum number of threads that can be present at any one time in the thread pool.

The default value of this property is 0, indicating unlimited concurrency.

vbroker.notify.threadPool.threadMin

vbroker.notify.threadPool.threadMin = <ULong>

This property specifies the minimum number of threads that can be present at any time in the thread pool.

The default value of this property is 0.

vbroker.notify.threadPool.threadMaxIdle

vbroker.notify.threadPool.threadMaxIdle = <ULong>

This property specifies the time, in seconds, that a thread in the thread pool can idle. After the idle time, the thread is garbage collected.

The default value of this property is 300 seconds.

vbroker.log.enable

vbroker.log.enable = <Boolean>

To see the debug log statements from this service, set this property to true. For the various source names options for debug log filtering, see the “Debug Logging properties” section of the VisiBroker for C++ Developer's Guide.

Levels of Support

The following table shows the level of support for each QoS property:

Property	Supported Values	Per Msg	Per Proxy	Per Admin	Per Channel	Comment
1. General
Priority	A value of Short	Yes	Yes	Yes	Yes	The values range from -32767 to +32767.
2. Event Persistence
EventReliability	• BestEffort • Persistent	Yes	No	No	Yes	For Persistent events, the same event can be delivered to a consumer more than once.
VBPersistentDbType	Value of Short	No	No	No	Yes	Value of 1 (default) implies Memory mapped persistency Value of 2 implies flat file persistency
VBPersistentCommitSync Policy (extension)	• False (default) • True	No	No	No	Yes
VBPersistentStorage OverflowBlock Timeout (extension)	Any value of ULong	No	No	No	Yes	In seconds
VBPersistentStorage Overflow DowngradePolicy (extension)	• AnyOrder (0) • FifoOrder (1) • LifoOrder (4)	No	No	No	Yes
3. Connection Persistent
ConnectionReliability	• BestEffort • Persistent	No	Yes	Yes	Yes
4. Queue Overflow Handling
MaxEventsPerConsumer	Per OMG specification	No	Yes (proxy supplier only)	Yes (consumer admin only)	Yes
DiscardPolicy	• AnyOrder (default) • FifoOrder • LifoOrder	No	Yes (proxy supplier only)	Yes (consumer admin only)	Yes
5. Event Expiry
StopTime	Not supported	Yes	No	No	No
Timeout	Not supported	Yes	Yes	Yes	Yes
StopTimeSupported	Not supported	No	Yes	Yes	Yes
6. Event Delivery
StartTime	Not supported	Yes
StartTimeSupported	Not supported	No	Yes	Yes	Yes
OrderPolicy	• AnyOrder • FifoOrder (default) • PriorityOrder	No	Yes	Yes	Yes
MaximumBatchSize	Not supported	No	Yes	Yes	Yes
PacingInterval	Not supported	No	Yes	Yes	Yes
7. Flow Control
VBQueueLowWaterMark (extension)	A ULong value	No	Yes (proxy supplier only)	Yes (consumer admin only)	Yes
VBQueueHighWaterMark (extension)	A ULong value	No	Yes (proxy supplier only)	Yes (consumer admin only)	Yes

Event Filtering using Filter Objects

The OMG Notification Service specification defines two kinds of filters.

•	Forwarding Filter

•	Mapping Filter

The Forwarding filter allows events to be forwarded if it satisfies a constraint set by the clients. Thus, consumers can use forwarding filters to receive only events that interest them. The forwarding filter objects implement the CosNotifyFilter::Filter interface.

The Mapping filter enables consumers to change the priority and lifetime properties of events which satisfies a constraint. Mapping filter objects implements the CosNotifyFilter::MappingFilter interface. However, VisiNotify currently does not support mapping filters.

Filtering Events

The VisiNotify event filtering is performed on structured events, typed events and sequence of events. There is no filtering support for untyped events. For a sequence of events, VisiNotify only filters the first event in the sequence. If the first event in the sequence does not satisfy the filter then the entire sequence is discarded.

Note

Refer to the OMG Notification Service specification, Section 2, for more information on each event (structured, typed, and sequence).

Forwarding Filter Evaluation

A filter object can be attached to a target object such as consumer/supplier proxy or consumer/supplier admin objects. Any given filter object can have a set of constraints and each constraint is expressed in the Extended Trader Constraint Language (TCL). A constraint expression either evaluates to TRUE (indicating that an event satisfies the constraint) or FALSE (indicating otherwise).

As long as one of the constraints is set to TRUE, the filter object will forward the event immediately. An event is discarded if the target object has its attached filters set to FALSE. For more information about writing constraint expressions see “Writing Filter Constraint Expressions”, and for more information about Extended TCL see “Extended Trader Constraint Language (Extended TCL)”.

When a forwarding filter object is attached to an admin object, then all proxy objects associated with the admin object apply the forwarding filter. If there are no filters applied to a proxy or admin object then all events received are forwarded to the next delivery point.

When filters are attached to an admin object along with its proxies, then event forwarding depends on whether the admin object was created with AND or OR semantics. An admin object created with AND semantics implies that an event must pass both admin and its proxy filters. An admin object created with OR semantics implies that events must pass either admin or its proxy filters.

You can create a consumer admin by invoking new_for_consumers() on the channel and pass the value AND_OP (for AND semantics) or OR_OP (for OR semantics) to set the inter-filter group operator semantics on the consumer admin object. Likewise, you can create a supplier admin by invoking new_for_suppliers(). Calling default_consumer_admin() or default_supplier_admin() on the channel will return the default consumer admin or supplier admin, respectively, with AND semantics.

Note

Refer to the OMG Notification Service specification (Section 3.4 - The CosNotifyChannelAdmin Module) for more information on the methods used with the AND or OR semantics.

Using Forwarding Filters

Use the following steps to apply a forwarding filter:

1	Obtain a Forwarding Filter Factory. VisiNotify provides a default filter factory. To obtain a reference to it simply invoke the method default_filter_factory() on the following channel:

CosNotifyFilter::FilterFactory_var ffact = channel->default_filter_factory();

2	Create a Forwarding Filter object. VisiNotify only supports the Extended Trader Constraint Language as specified by the OMG Notification Service. To create a filter that specifies the constraints, simply invoke the method create_filter(EXTENDED_TCL) on the filter factory object obtained in Step 1.

CosNotifyFilter::Filter_var filter = ffact->create_filter( "EXTENDED_TCL" );

3	Creating constraints. For any given filter object a set of constraints can be associated with it. The constraint expression is written in Extended TCL.

The following shows how to create a set of constraints and simple constraint expression.

CosNotifyFilter::ConstraintExpSeq constraints;
constraints.length(1); // contains 1 constraint
constraints[0].constraint_expr = CORBA::string_dup( "$balance == 123.45");

Note

To learn more about the Extended TCL see “Extended Trader Constraint Language (Extended TCL)” and refer to the OMG Notification Service specification (Section 2.4 - The Default Filter Constraint Language).

4	Adding constraints to a filter object. To add a set of constraints simply invoke the method add_constraints on the filter object obtained in Step 2 passing in the set of constraints created in Step 3.

filter->add_constraints( constraints );

Note

Refer to the OMG Notification Service specification (Section 3.2.1 - The Filter Interface) to learn more about other operations such as modifying or obtaining constraints from a filter object.

5	Adding a filter to a target object. The target object can be an admin object or a proxy object. The creation of the target object is required before the filter object is attached to it. This example shows a structured push supplier proxy:

// create a structured push supplier proxy
CosNotifyChannelAdmin::ProxyID proxy_id;
CosNotifyChannelAdmin::ProxySupplier_var proxy
= admin->obtain_notification_push_supplier
CosNotifyChannelAdmin::STRUCTURED_EVENT, proxy_id);
CosNotifyChannelAdmin::StructuredProxyPushSupplier_var
supplier =
CosNotifyChannelAdmin::StructuredProxyPushSupplier::
_narrow(proxy);

To attach the filter object to a target object simply invoke add_filter on the target object. The add_filter operation accepts a filter object and returns a filter id unique to the particular target object. This example shows add_filter being invoked on a structured push supplier proxy and is passed a filter object created in Step 2.

CORBA::Long filter_id;
Filter_id = supplier->add_filter( filter );

Note

Refer to the OMG Notification Service specification (Section 3.2.4 - The FilterAdmin Interface) to learn more about other operations such as modifying or obtaining filters from a target object.

Forwarding Filter Limitation

VisiNotify currently does not support the following filter object methods:

•	attach_callback

•	detach_callback

•	get_callbacks

Note

Refer to the OMG Notification Service specification (Section 2.6 - Sharing Subscriptions and Section 2.6.5 - Obligations on Filter Objects) to learn more about these methods and sharing subscriptions.

Writing Filter Constraint Expressions

A constraint expression is a boolean expression (that is, it evaluates with either TRUE or FALSE). A constraint expression typically refers to event data, which also includes filterable data that the application is most likely to base filtering decisions.

Contents of a structured event

A structured event is defined in CosNotification.idl as follows:

...
typedef string Istring;
typedef Istring PropertyName;
typedef any PropertyValue;

struct Property {
PropertyName name;
PropertyValue value;
};
typedef sequence<Property> PropertySeq;

typedef PropertySeq OptionalHeaderFields;
typedef PropertySeq FilterableEventBody;

struct EventType {
string domain_name;
string type_name;
};
struct FixedEventHeader {
EventType event_type;
string event_name;
};

struct EventHeader {
FixedEventHeader fixed_header;
OptionalHeaderFields variable_header;
};

struct StructuredEvent {
EventHeader header;
FilterableEventBody filterable_data;
any remainder_of_body;
};
...

Contents of a typed event

A typed event contains a sequence of name-value pairs in which the first item in the sequence refers to a CosNotification::EventType that contains domain_name referring to the name of the typed interface and type_name referring to the name of the operation in that interface. The remaining items in the sequence of name-value pairs are filterable data in which each item contains a name referring to an input parameter for the operation within the typed interface and the value refers to the parameter value for that operation.

For example, an application may use the following IDL for a typed event:

interface foo {
void bar( in string first, in long second );
};

In this example, the typed event foo::bar is received and the second item in the sequence of name-value pairs will be named first paired with a string value and the third item in the sequence will be named second paired with a long value.

Note

For details on structured events and typed events please refer to the OMG Notification Service V1.0 specification, Section 2.2, "Structured Events," and Section 2.7, "Filtering Typed Events."

Extended Trader Constraint Language (Extended TCL)

The OMG Notification Service V1.0 specifies the Extended Constraint Language as the default filter constraint language. Extended TCL is based on the Trader Constraint Language (TCL) from the OMG Trading Service and in addition, has a few extensions and changes made.

Note

See the OMG Notification Service V1.0 specification, Section 2.4.1 for details on the changes made to TCL.

A constraint expression written in Extended TCL evaluates to either a TRUE or FALSE value. These two values are reserved words in TCL. The value of TRUE in Extended TCL is 1 and the value of FALSE is 0 (zero). Hence, we can have an expression like the following:

TRUE + TRUE

that will yield a result of 2. Sub-expressions can be specified by surrounding the sub-expression with brackets like the following:

(TRUE + TRUE) == 2

Accessing event data

Extended TCL supports the means of referring to complex data types (that is, the IDL types of struct, enum, union and any) within an event. An event is represented by a $ (dollar sign) symbol and attributes within an event are referenced by using a . (period) symbol similar to the C++ or Java programming constructs used today.

For example, in order to refer to a structured event's fixed header event_name attribute, we would write:

$.header.fixed_header.event_name

In a typed event, if the application has an interface named foo that has an operation named bar that takes in its first parameter a string called first, we would refer to it by writing:

$.first

Note

When the event data does not exist or if the data types of both operands for an operation do not match (for example 'A String' == 3.14) then the constraint will evaluate to FALSE.

Short-hand notation

It is possible to refer to specific reserved attributes in an event as well as filterable data by using run-time variables in Extended TCL. A run-time variable is represented by prefixing a $ (dollar sign) symbol before the identifier name. For example, $event_name would actually be the same as writing $.header.fixed_header.event_name. When run-time variables are used, the identifier is matched with reserved attributes within an event. If the identifier is not a reserved attribute within an event then it is matched with the filterable data.

Note

Please refer to OMG Notification Service V1.0 specification, Section 2.4.5 for further details on Short-hand Notation for Filtering a Generic Event.

Positional notation

The current version of VisiNotify does not support positional notation.

Equality, relational and logical operators

Extended TCL uses the same operators as those used in normal TCL plus additional operators added by the OMG Notification Service V1.0 specification.

Note

The operators in the following table evaluate to either TRUE or FALSE

Operator	Description	Example
==	Equality	($.one + $.two) == 3
!=	Inequality	($.one + $.two) != 4
<	Less than	($.one + $.two) < 3
<=	Less than or equals	($.one + $.two) <= 3
>	Greater than	($.one + $.two) > 1
>=	Greater than or equals	($.one + $.two) >= 2
in	Checks if the left operand is a simple primitive type and is contained in right operand which is a sequence of the same primitive type	$.one in $.list_of_nums
~	Substring operator to check if the left operand string is contained in the right operand string	'Notify' ~ 'VisiNotify'
exist	Test to see if an identifier exists	exist $.one
and	Logical AND	($.one == 1) and ($.two == 2)
or	Logical OR	($.one == 1) or ($.two == 2)
not	Logical NOT	not exist $.one
default	Applies to discriminated union data only. Checks if a discriminated union has a default member	Default $.myUnion

Arithmetic operators

The result type of the operators in the following table depends on the type of the operands. The strongly typed operand dictates the resultant data type.

Note

Character data can be used in arithmetic operations. A string with a length of one is also considered as a character.

Operator	Description	Example
+	Addition	$.one + $.two
-	Subtraction	$.one - $.two
*	Multiplication	$.one * $.two
/	Division	$.two / $.one

Subscript operator

Arrays and sequences can be accessed via the subscript operator [n]. For example, in order to access the second element of an array we would write:

$myArray[1]

Lookup for name-value pairs

Name-value pair sequences are often found in events, especially the filterable data that is a name-value pair sequence. As an example, we can access the filterable data by writing an expression such as the following:

$.filterable_data[2].name = = "balance" and $.filterable_data[2].value > 100)

Expressions like these can be lengthy, hence Extended TCL allows short-form notation like the following:

$.filterable_data(balance) > 100

Reserved implicit members

Extended TCL makes use of reserved member attributes for the event as well as complex data. Below is a table of the reserved member attribute names and their purpose.

Attribute	Description	Example
_length	Length for an array or sequence	$.mySequence._length
_d	Discriminator for a discriminated union	$.myUnion._d
_type_id	Unscoped IDL type name	$.myData._type_id
_repos_id	Repository ID	$.myData._repository_id