org.omg.CosNotifyFilter
Interface MappingFilterOperations
public
interface
MappingFilterOperations
The MappingFilter interface defines the behaviors of objects which encapsulate a
sequence of constraint-value pairs, where each constraint is a structure of the same
type as that described in section 3.2.1, and each value represents a possible setting of a
particular property of an event. Note that setting of a particular property is not
intended to imply that any contents of the event will be altered as a result of applying
a mapping filter, but rather the way a proxy treats the event with respect to a particular
property (i.e., priority or lifetime) could change. Upon receiving each event, a proxy
object with an associated object supporting the MappingFilter interface will invoke
the appropriate match operation variant (depending upon whether the event is received
in the form of an untyped event, a Structured Event, or a typed event) on the mapping
filter object in order to determine how it should modify a particular property value
associated with the event to one of the values associated with one of the constraints
encapsulated by the mapping filter. Internally, the mapping filter object applies the
constraints it encapsulates to the event in order to determine whether or not the events
property should be modified to one of the values associated with a constraint, or else
the default value associated with the mapping filter.
Each instance of an object supporting the MappingFilter interface is typically
associated with a specific event property. For instance, in this specification
MappingFilter object instances are used to affect the properties of priority and
lifetime for events received by a proxy supplier object. Each event received by a proxy
object which has an object supporting the MappingFilter interface associated with it
must satisfy at least one of the constraints associated with the MappingFilter object in
order to have its property value modified, otherwise the property will remain
unchanged. A specific instance supporting the MappingFilter interface typically
applies its encapsulated constraints in an order which begins with the best possible
property setting (e.g., the highest priority or the longest lifetime), and ends with the
worst possible property setting. As soon as a matching constraint is encountered, the
associated value is returned as an output parameter and the proxy which invoked the
operation proceeds to modify the property of the event to the new value.
The constraint expressions associated with a particular object supporting the
MappingFilter interface are expressed as strings which obey the syntax of a particular
constraint grammar (i.e. a BNF). Every conformant implementation of this service
must support constraint expressions expressed in the default constraint grammar
described in section 2.4. In addition, implementations may support other constraint
grammars, and/or users of this service may implement their own filter objects which
allow constraints to be expressed in terms of an alternative constraint grammar. As
long as such user-defined filter objects support the MappingFilter interface, they can
be attached to proxy objects in the same fashion as the default MappingFilter objects
supported by the implementation of the service are, and the channel should be able to
use them to potentially affect the properties of events in the same fashion.
The MappingFilter interface supports the operations required to manage the
constraint-value pairs associated with an object instance which supports the interface.
In addition, the MappingFilter interface supports a readonly attribute which identifies
the particular constraint grammar in which the constraints encapsulated by this object
have meaning. The MappingFilter interface also supports a readonly attribute which
identifies the typecode associated with the datatype of the specific property value it is
intended to affect, and another readonly attribute which holds the default value which
will be returned as the result of a match operation in cases when the event in question
is found to satisfy none of the constraints encapsulated by the mapping filter. Lastly,
the MappingFilter interface supports three variants of the operation which will be
invoked by an associated proxy object upon receipt of an event, to determine how the
property of the event which the target mapping filter object was designed to affect
should be modified.
The operations supported by the MappingFilter object are described in more detail
within the following subsections.
Method Summary |
MappingConstraintInfo[] | add_mapping_constraints(MappingConstraintPair[] pair_list)
The add_mapping_constraints operation is invoked by a client in order to associate
specific mapping constraints with the target filter object. |
String | constraint_grammar()
The constraint_grammar attribute is a readonly attribute which identifies the particular
grammar within which the constraint expressions encapsulated by the target filter
object have meaning. |
Any | default_value()
The default_value attribute is a readonly attribute that will be the output parameter
returned as the result of any match operation during which the input event is found to
satisfy none of the constraints encapsulated by the mapping filter, within which the
constraints encapsulated by the target filter object have meaning. |
void | destroy()
The destroy operation destroys the target filter object, invalidating its object
reference. |
MappingConstraintInfo[] | get_all_mapping_constraints()
The get_all_mapping_constraints operation returns all of the constraint-value pairs
currently encapsulated by the target filter object. |
MappingConstraintInfo[] | get_mapping_constraints(int[] id_list)
The get_mapping_constraints operation is invoked to return a sequence of a subset of
the constraint-value pairs associated with the target filter object. |
boolean | match(Any filterable_data, AnyHolder result_to_set)
The match operation is invoked on an object supporting the MappingFilter interface
in order to determine how some property value of a particular event supplied to the
channel in the form of a CORBA::Any should be modified. |
boolean | match_structured(StructuredEvent filterable_data, AnyHolder result_to_set)
The match_structured operation is invoked on an object supporting the MappingFilter
interface in order to determine how some property value of a particular event supplied
to the channel in the form of a Structured Event should be modified. |
boolean | match_typed(Property[] filterable_data, AnyHolder result_to_set)
The match_typed operation is invoked on an object supporting the MappingFilter
interface in order to determine how some property value of a particular event supplied
to the channel in the form of a typed event should be modified. |
void | modify_mapping_constraints(int[] del_list, MappingConstraintInfo[] modify_list)
The modify_mapping_constraints operation is invoked by a client in order to modify
the constraint-value pairs associated with the target filter object. |
void | remove_all_mapping_constraints()
The remove_all_mapping_constraints operation is invoked to remove all of the
constraint-value pairs currently encapsulated by the target filter object. |
TypeCode | value_type()
The value_type attribute is a readonly attribute which identifies the datatype of the
property value which the target mapping filter object was designed to affect. |
The add_mapping_constraints operation is invoked by a client in order to associate
specific mapping constraints with the target filter object. Note that a mapping
constraint is comprised of a constraint structure paired with an associated value. The
operation accepts as input one parameter that is a sequence of constraint-value pairs.
Each constraint in this sequence must be expressed within the constraint grammar
supported by the target object, and each associated value must be of the data type
indicated by the value_type attribute of the target object.
Upon processing the each element in the input sequence, the target object associates a
numeric identifier with this constraint-value pair that is unique among all those that it
encapsulates. If any of the constraint expressions in the input sequence is not a valid
expression within the supported constraint grammar, the InvalidConstraint exception
is raised. This exception contains as data the specific constraint that was determined to
be invalid. If any of the values supplied in the input sequence is not of the same
datatype as that indicated by the value_type attribute associated with the target object,
the InvalidValue exception is raised. This exception contains as data both the invalid
value and its corresponding constraint in the first input sequence. Upon successful
processing of all input constraints, the add_mapping_constraints operation returns a
sequence in which each element will be a structure including one of the input
constraint expressions, its corresponding value, and the unique identifier assigned to
this constraint-value pair by the target filter object.
Note that the semantics of the add_mapping_constraints operation are such that its
side-effects are performed atomically upon the target filter object. Once
add_mapping_constraints is invoked by a client, the target filter object is temporarily
disabled from usage by any proxy object it may be associated with. The operation is
then carried out, either successfully adding all of the input constraint-value pairs to
the target object or none of them (in the case one of the input expressions or values was
invalid). Upon completion of the operation, the target filter object is effectively
re-enabled and can once again be used by associated filter objects in order to make event
property mapping decisions.
public String constraint_grammar()
The constraint_grammar attribute is a readonly attribute which identifies the particular
grammar within which the constraint expressions encapsulated by the target filter
object have meaning. The value of this attribute is set upon creation of a mapping filter
object instance, based on the input provided to the factory creation operation for the
mapping filter instance.
The dependency of a filter object on its constraints being expressed within a particular
constraint grammar manifests itself within the implementation of the match operations
described below, which must be able to parse the constraints to determine whether or
not a particular event satisfies one of them.
Every conformant implementation of the Notification Service must support an
implementation of the MappingFilter object which supports the default constraint
grammar described in section 2.4. The value which the constraint_grammar attribute is
set to in the case the target filter object supports this default grammar will be
EXTENDED_TCL. In addition, implementations and/or end users may provide
additional implementations of the MappingFilter interface which support different
constraint grammars, and thus would set the constraint_grammar attribute to a
different value upon creation of such a filter object.
public Any default_value()
The default_value attribute is a readonly attribute that will be the output parameter
returned as the result of any match operation during which the input event is found to
satisfy none of the constraints encapsulated by the mapping filter, within which the
constraints encapsulated by the target filter object have meaning. The value of this
attribute is set upon creation of a mapping filter object instance, based on the input
provided to the factory creation operation for the mapping filter instance.
public void destroy()
The destroy operation destroys the target filter object, invalidating its object
reference.
The get_all_mapping_constraints operation returns all of the constraint-value pairs
currently encapsulated by the target filter object. The return value of this operation is
a sequence of structures, each of which contains one of the constraints encapsulated by
the target object along with its associated value and unique identifier.
The get_mapping_constraints operation is invoked to return a sequence of a subset of
the constraint-value pairs associated with the target filter object. The operation
accepts as input a sequence of numeric values which should correspond to the unique
identifiers of constraint-value pairs encapsulated by the target object. If one of the
input values does not correspond to the identifier of some encapsulated constraint-value
pair, the ConstraintNotFound exception is raised, containing as data the
numeric value that did not correspond to some such pair. Upon successful completion,
this operation returns a sequence of data structures, each of which contains one of the
input identifiers along with its associated constraint structure and constraint value.
public boolean match(Any filterable_data, AnyHolder result_to_set)
The match operation is invoked on an object supporting the MappingFilter interface
in order to determine how some property value of a particular event supplied to the
channel in the form of a CORBA::Any should be modified. The operation accepts an
Any as input, which contains the event being evaluated. Upon invocation, the target
mapping filter object begins applying the constraints it encapsulates in order according
to each constraints associated value, starting with the constraint with the best
associated value for the specific property the mapping filter object was designed to
affect (e.g., the highest priority, the longest lifetime, etc.), and ending with the
constraint with the worst associated value. Upon encountering a constraint which the
input filterable data matches, the operation sets the output parameter contained in its
signature to the value associated with the constraint, and sets the return value of the
operation to TRUE. If the input filterable data satisfies none of the constraints
encapsulated by the target mapping filter object, the return value of the operation is
set to FALSE, and the output parameter is set to the value of the default_value attribute
associated with the target mapping filter object. The act of determining whether or not
a given filterable event data passes a given filter constraint is specific to the type of
grammar in which the filter constraint is specified. Thus, this operation will need to be
re-implemented for each supported grammar.
If the input parameter contains data that the match operation is not designed to handle,
the UnsupportedFilterableData exception will be raised. An example of this would
be if the filterable data contained a field whose name corresponds to a standard event
field that has a numeric value, but the actual value associated with this field name
within the event is a string.
public boolean match_structured(
StructuredEvent filterable_data, AnyHolder result_to_set)
The match_structured operation is invoked on an object supporting the MappingFilter
interface in order to determine how some property value of a particular event supplied
to the channel in the form of a Structured Event should be modified. The operation
accepts a CosNotification::StructuredEvent as input, which contains the event being
evaluated. Upon invocation, the target mapping filter object begins applying the
constraints it encapsulates in order according to each constraints associated value,
starting with the constraint with the best associated value for the specific property
the mapping filter object was designed to affect (e.g., the highest priority, the longest
lifetime, etc.), and ending with the constraint with the worst associated value. Upon
encountering a constraint which the input filterable data matches, the operation sets the
output parameter contained in its signature to the value associated with the constraint,
and sets the return value of the operation to TRUE. If the input filterable data
satisfies none of the constraints encapsulated by the target mapping filter object, the
return value of the operation is set to FALSE, and the output parameter is set to the
value of the default_value attribute associated with the target mapping filter object.
The act of determining whether or not a given filterable event data passes a given filter
constraint is specific to the type of grammar in which the filter constraint is
specified. Thus, this operation will need to be re-implemented for each supported
grammar. If the input parameter contains data that the match operation is not designed to
handle, the UnsupportedFilterableData exception will be raised. An example of this would
be if the filterable data contained a field whose name corresponds to a standard event
field that has a numeric value, but the actual value associated with this field name
within the event is a string.
public boolean match_typed(
Property[] filterable_data, AnyHolder result_to_set)
The match_typed operation is invoked on an object supporting the MappingFilter
interface in order to determine how some property value of a particular event supplied
to the channel in the form of a typed event should be modified. The operation accepts
as input a sequence of name-value pairs which contains the contents of the event to be
evaluated (how a typed event is converted to a sequence of name-value pairs by the
channel is described in section 2.7). Upon invocation, the target mapping filter object
begins applying the constraints it encapsulates in order according to each constraints
associated value, starting with the constraint with the best associated value for the
specific property the mapping filter object was designed to affect (e.g., the highest
priority, the longest lifetime, etc.), and ending with the constraint with the worst
associated value. Upon encountering a constraint which the input filterable data
matches, the operation sets the output parameter contained in its signature to the value
associated with the constraint, and sets the return value of the operation to TRUE. If
the input filterable data satisfies none of the constraints encapsulated by the target
mapping filter object, the return value of the operation is set to FALSE, and the output
parameter is set to the value of the default_value attribute associated with the target
mapping filter object. The act of determining whether or not a given filterable event
data passes a given filter constraint is specific to the type of grammar in which the
filter constraint is specified. Thus, this operation will need to be re-implemented for
each supported grammar.
If the input parameter contains data that the match operation is not designed to handle,
the UnsupportedFilterableData exception will be raised. An example of this would
be if the filterable data contained a field whose name corresponds to a standard event
field that has a numeric value, but the actual value associated with this field name
within the event is a string.
The modify_mapping_constraints operation is invoked by a client in order to modify
the constraint-value pairs associated with the target filter object. This operation can
be used both to remove constraint-value pairs currently associated with the target filter
object, and to modify the constraints and/or values of constraint-value pairs which
have previously been added to the target filter object.
The operation accepts two input paramaters. The first input parameter is a sequence of
numeric values which are each intended to be the unique identifier associated with one
of the constraint-value pairs currently encapsulated by the target filter object. If all
input values supplied within a particular invocation of this operation are valid, then
the specific constraint-value pairs identified by the values contained in the first input
parameter will be deleted from the list of those encapsulated by the target filter
object. The second input parameter to this operation is a sequence of structures, each of
which contains a constraint structure, an Any value, and a numeric identifier. The
numeric identifier contained by each element of the sequence is intended to be the unique
identifier associated with one of the constraint-value pairs currently encapsulated by
the target filter object. If all input values supplied within a particular invocation of
the operation are valid, then the constraint associated with the already encapsulated
constraint-value pair identified by the numeric identifier contained within each element
of the input sequence will be modified to the new constraint that is contained within
the same sequence element. Likewise, the data value associated with the already
encapsulated constraint-value pair identified by the numeric identifier contained within
each element of the input sequence will be modified to the new data value that is
contained in the same element of the sequence.
If any of the numeric identifiers supplied within either of the two input sequences does
not correspond to the unique identifier associated with some constraint-value pairs
currently encapsulated by the target filter object, the ConstraintNotFound exception
is raised. This exception contains as data the specific identifier which was supplied as
input but did not correspond to the identifier of some constraint-value pair
encapsulated by the target object. If any of the constraint expressions supplied within
an element of the second input sequence is not a valid expression in terms of the
constraint grammar supported by the target object, the InvalidConstraint exception is
raised. This exception contains as data the specific constraint that was determined to be
invalid. If any of the values supplied in the second input sequence is not of the same
datatype as that indicated by the value_type attribute associated with the target object,
the InvalidValue exception is raised. This exception contains as data both the invalid
value and its corresponding constraint expression.
Note that the semantics of the modify_mapping_constraints operation are such that its
side-effects are performed atomically upon the target filter object. Once
modify_mapping_constraints is invoked by a client, the target filter object is
temporarily disabled from usage by any proxy object it may be associated with. The
operation is then carried out, either successfully deleting all of the constraint-value
pairs identified in the first input sequence and modifying the constraints and values
associated with constraints identified in the second input sequence, or performing no
side effects to the target object (in the case one of the inputs was invalid). Upon
completion of the operation, the target filter object is effectively re-enabled and can
once again be used by associated filter objects in order to make event property
mapping decisions.
public void remove_all_mapping_constraints()
The remove_all_mapping_constraints operation is invoked to remove all of the
constraint-value pairs currently encapsulated by the target filter object. Upon
completion, the target filter object will still exist but have no constraint-value pairs
associated with it.
public TypeCode value_type()
The value_type attribute is a readonly attribute which identifies the datatype of the
property value which the target mapping filter object was designed to affect. Note that
the factory creation operation for mapping filter objects accepts as an input parameter
the default_value to associate with the mapping filter instance. This default_value is a
CORBA::Any. Upon creation of a mapping filter, the Typecode associated with the
default_value is extracted from the CORBA::Any, and its value is assigned to this
attribute. The value_type attribute thus serves mainly as a convenience for clients
attempting to examine the state of a mapping filter object.