|
VisiBroker for Java |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface FilterOperations
The Filter interface defines the behaviors supported by objects which encapsulate constraints used by the proxy objects associated with an event channel in order to determine which events they receive will be forwarded, and which will be discarded.
Each object supporting the Filter interface can encapsulate a sequence of any number of constraints. Each event received by a proxy object which has one or more objects supporting the Filter interface associated with it must satisfy at least one of the constraints associated with one of its associated Filter objects in order to be forwarded (either to another proxy object or to the consumer, depending on the type of proxy the filter is associated with), otherwise it will be discarded.
Each constraint encapsulated by a filter object is a structure comprised of two main components. The first component is a sequence of data structures, each of which indicates an event type comprised of a domain and a type name. The second component is a boolean expression over the properties of an event, expressed in some constraint grammar (more on this below). For a given constraint, the sequence of event type structures in the first component nominates a set of event types to which the constraint expression in the second component applies. Each element of the sequence can contain strings which will be matched for equality against the domain_name and type_name fields of each event being evaluated by the filter object, or it could contain strings with wildcard symbols (*), indicating a pattern match should be performed against the type contained in each event, rather than a comparison for equality when determining if the boolean expression should be applied to the event, or the event should simply be discarded without even attempting to apply the boolean expression. Note that an empty sequence included as the first component of a constraint implies that the associated expression applies to all types of events, as does a sequence comprised of a single element whose domain and type name are both set to either the empty string or else the wildcard symbol alone contained in quotes.
The constraint expressions associated with a particular object supporting the Filter 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 Filter interface, they can be attached to Proxy or Admin objects in the same fashion as the default Filter objects supported by the implementation of the service are, and the channel should be able to use them to filter events in the same fashion.
The Filter interface supports the operations required to manage the constraints associated with an object instance which supports the interface, along with a readonly attribute which identifies the particular constraint grammar in which the constraints encapsulated by this object have meaning. In addition, the Filter interface supports three variants of the match operation which can be invoked by an associated proxy object upon receipt of an event (the specific variant selected depends upon whether the event is received in the form of an Any, a Structured Event, or a Typed Event), to determine if the event should be forwarded or discarded, based on whether or not the event satisfies at least one criteria encapsulated by the filter object.
The Filter interface also supports operations which enable a client to associate with the target filter object any number of callbacks, which are notified each time there is a change to the list of event types, which the constraints encapsulated by the filter object could potentially cause proxies to which the filter is attached to receive. Operations are also defined to support administration of this callback list by unique identifier.
The operations supported by the Filter interface are described in more detail within the following subsections.
Method Summary | |
---|---|
ConstraintInfo[] |
add_constraints(ConstraintExp[] constraint_list)
The add_constraints operation is invoked by a client in order to associate one or more new constraints with the target filter object. |
int |
attach_callback(NotifySubscribe callback)
This operation is invoked to associate with the target filter object an object supporting the CosNotifyComm::NotifySubscribe interface. |
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. |
void |
destroy()
The destroy operation destroys the target filter object, invalidating its object reference. |
void |
detach_callback(int callback)
After this method is called, the callback object to which the input value corresponds is removed from the list of those associated with the target filter object, so that subsequent changes to the event type subscription list encapsulated by the target filter object will not be propagated to the callback object which is being detached. |
ConstraintInfo[] |
get_all_constraints()
|
int[] |
get_callbacks()
|
ConstraintInfo[] |
get_constraints(int[] id_list)
The get_constraints operation is invoked to return a sequence of a subset of the constraints associated with the target filter object. |
boolean |
match_structured(StructuredEvent filterable_data)
The match_structured operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a Structured Event. |
boolean |
match_typed(Property[] filterable_data)
The match operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a typed event. |
boolean |
match(Any filterable_data)
The match operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a CORBA::Any. |
void |
modify_constraints(int[] del_list,
ConstraintInfo[] modify_list)
The modify_constraints operation is invoked by a client in order to modify the constraints associated with the target filter object. |
void |
remove_all_constraints()
The remove_all_constraints operation is invoked to remove all of the constraints currently encapsulated by the target filter object. |
Method Detail |
---|
int[] get_callbacks()
void detach_callback(int callback) throws CallbackNotFound
A
- numeric value which should be one of the unique identifiers
associated with one of the callback objects attached to the target
filter object.
CallbackNotFound
- If the input value
does not correspond to the unique identifier of a callback object
currently attached to the target filter object.int attach_callback(NotifySubscribe callback)
callback
- The reference to an object supporting the
CosNotifyComm::NotifySubscribe interface.
boolean match_typed(Property[] filterable_data) throws UnsupportedFilterableData
The act of determining whether or not a given event 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.
filterable_data
- A sequence of name-value pairs which contains
the contents of the event to be evaluated.
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) throws UnsupportedFilterableData
The act of determining whether or not a given event 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 reimplemented for each supported grammar.
filterable_data
- A data structure of type
CosNotification::StructuredEvent, which contains an event to be
evaluated.
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(Any filterable_data) throws UnsupportedFilterableData
The act of determining whether or not a given event 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.
filterable_data
- A CORBA::Any which contains an event to be
evaluated.
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.void destroy()
void remove_all_constraints()
ConstraintInfo[] get_all_constraints()
ConstraintInfo[] get_constraints(int[] id_list) throws ConstraintNotFound
id_list
- A sequence of numeric values, which should correspond
to the unique identifiers of constraints encapsulated by the target
object.
ConstraintNotFound
- If one of the
input values does not correspond to the identifier of some
encapsulated constraint.
This exception contains as data the numeric value that did not
correspond to some constraint.void modify_constraints(int[] del_list, ConstraintInfo[] modify_list) throws InvalidConstraint, ConstraintNotFound
Note that the semantics of the modify_constraints operation are such that its side effects are performed atomically upon the target filter object. Once modify_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 constraints identified in the first input sequence and modifying those 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 forwarding decisions.
del_list
- A sequence of numeric values which are each intended
to be the unique identifier associated with one of the constraints
currently encapsulated by the target filter object.
If all input values supplied within a particular invocation of this
operation are valid, then the specific constraints identified by the
values contained in the first input parameter will be deleted from
the list of those encapsulated by this target filter object.modify_list
- A sequence of structures, each of which contains
a constraint structure and a numeric value.
The numeric value contained by each element of the sequence is
intended to be the unique identifier associated with one of the
constraints currently encapsulated by this target filter object.
If all input values supplied within a particular invocation of this
operation are valid, then the constraint expression associated with
the already encapsulated constraint identified by the numeric value
contained within each element of the input sequence will be
modified to the new constraint expression that is contained within
the same sequence element.
ConstraintNotFound
- If any of the
numeric values supplied within either of the two input sequences
does not correspond to the unique identifier associated with some
constraint 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 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.ConstraintInfo[] add_constraints(ConstraintExp[] constraint_list) throws InvalidConstraint
Note that the semantics of the add_constraints operation are such that its sideeffects are performed atomically upon the target filter object. Once add_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 constraints to the target object or none of them (in the case one of the input expressions 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 forwarding decisions.
constraint_list
- A sequence of constraint data structures,
each element of which consists of a sequence of event type structures
and a constraint expressed within the constraint grammar supported by
the target object.
InvalidConstraint
- If any of the
constraints in the input sequence is not a valid expression within
the supported constraint grammar.
This exception contains as data the specific constraint expression
that was determined to be invalid.java.lang.String constraint_grammar()
|
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |