|
VisiBroker for Java |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface MappingFilterOperations
The MappingFilter interface defines the behaviors of objects, which encapsulate a sequence of constraint-value pairs, where 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 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 event?s 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). 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.
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. |
java.lang.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. |
void |
destroy()
The destroy operation destroys the target filter object, invalidating its object reference. |
MappingConstraintInfo[] |
get_all_mapping_constraints()
|
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_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. |
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. |
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. |
Method Detail |
---|
boolean match_typed(Property[] filterable_data, AnyHolder result_to_set) throws UnsupportedFilterableData
filterable_data
- A sequence of name-value pairs which contains the contents of
the event to be 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.result_to_set
- An output parameter containing constraints
satisfied by filterable_data. If constraint exists, the resturn value
will be set to TRUE.
UnsupportedFilterableData
- If the input
parameter contains data that the match operation is not designed to
handle.
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.boolean match_structured(StructuredEvent filterable_data, AnyHolder result_to_set) throws UnsupportedFilterableData
filterable_data
- 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.result_to_set
- An output parameter containing constraints
satisfied by filterable_data.
If constraint exists, return value wil be set to TRUE.
UnsupportedFilterableData
- If the input
parameter contains data that this match operation is not designed to
handle.
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.boolean match(Any filterable_data, AnyHolder result_to_set) throws UnsupportedFilterableData
filterable_data
- 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.result_to_set
- An output parameter containing the values
associated with the constraints satisfied by filterable_data.
If constraint exists, return value will be set to TRUE.
UnsupportedFilterableData
- If the input
parameter contains data that this match operation is not designed to
handle.
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.void destroy()
void remove_all_mapping_constraints()
MappingConstraintInfo[] get_all_mapping_constraints()
MappingConstraintInfo[] get_mapping_constraints(int[] id_list) throws ConstraintNotFound
id_list
- A sequence of numeric values which should correspond to
the unique identifiers of constraint-value pairs encapsulated by the
target object.
ConstraintNotFound
- If one of the
input values does not correspond to the identifier of some
encapsulated constraintvalue pair.
This exception contains as data the numeric value that did not
correspond to some such pair.void modify_mapping_constraints(int[] del_list, MappingConstraintInfo[] modify_list) throws InvalidConstraint, InvalidValue, ConstraintNotFound
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.
del_list
- 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.modify_list
- 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 this
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.
ConstraintNotFound
- 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.
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.
InvalidConstraint
- 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.
This exception contains as data the specific constraint that was
determined to be invalid.
InvalidValue
- 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.
This exception contains as data both the invalid value and its
corresponding constraint expression.MappingConstraintInfo[] add_mapping_constraints(MappingConstraintPair[] pair_list) throws InvalidConstraint, InvalidValue
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 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.
pair_list
- 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 each element in the input sequence, this target object
associates a numeric identifier with this constraint-value pair that
is unique among all those that it encapsulates.
InvalidConstraint
- If any of the
constraint expressions in the input sequence is not a valid
expression within the supported constraint grammar.
This exception contains as data the specific constraint that was
determined to be invalid.
InvalidValue
- 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.
This exception contains as data both the invalid value and its
corresponding constraint in the first input sequence.Any default_value()
TypeCode value_type()
java.lang.String constraint_grammar()
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. The value which the constraint_grammar attribute is set to in 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 that support different constraint grammars, and thus would set the constraint_grammar attribute to a different value upon creation of such a filter object.
|
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |