org.omg.CosNotifyFilter
Interface FilterOperations
- All Known Subinterfaces:
- Filter
- All Known Implementing Classes:
- _FilterStub, FilterImpl, FilterPOA, FilterPOATie
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.
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.
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)
The attach_callback operation accepts as input the reference to an object supporting
the CosNotifyComm::NotifySubscribe interface, and returns a numeric value
assigned to this callback that is unique to all such callbacks currently associated with
the target 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. |
void |
destroy()
The destroy operation destroys the target filter object, invalidating its object
reference. |
void |
detach_callback(int callback)
The detach_callback operation accepts as input a numeric value which should be one
of the unique identifiers associated with one of the callback objects attached to the
target filter object. |
ConstraintInfo[] |
get_all_constraints()
The get_all_constraints operation returns all of the constraints currently encapsulated
by the target filter object. |
int[] |
get_callbacks()
The get_callbacks operation accepts no input parameters and returns the sequence of
all unique identifiers associated with callback objects attached to the target filter
object. |
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(org.omg.CORBA.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. |
constraint_grammar
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. The value of this attribute is set upon creation of a filter object
instance, based on the input provided to the factory creation operation for the filter
instance.
add_constraints
ConstraintInfo[] add_constraints(ConstraintExp[] constraint_list)
throws InvalidConstraint
- The add_constraints operation is invoked by a client in order to associate one or more
new constraints with the target filter object. The operation accepts as input a sequence
of constraint data structures, each element of which consists of a sequence of event
type structures (described in section 3.2.1) and a constraint expressed within the
constraint grammar supported by the target object. Upon processing each constraint,
the target object associates a numeric identifier with the constraint that is unique
among all constraints it encapsulates. If any of the constraints 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 expression
that was determined to be invalid. Upon successful processing of all input constraint
expressions, the add_constraints operation returns a sequence in which each element
will be a structure including one of the input constraint expressions, along with the
unique identifier assigned to it by the target filter object.
Note that the semantics of the add_constraints operation are such that its side-effects
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.
- Parameters:
constraint_list
- Constraint Expressions
- Returns:
- ConstraintInfo array. Each element contain constraint exp and ID associated
- Throws:
InvalidConstraint
- If an Constraint doesn't respect
grammar
modify_constraints
void modify_constraints(int[] del_list,
ConstraintInfo[] modify_list)
throws InvalidConstraint,
ConstraintNotFound
- The modify_constraints operation is invoked by a client in order to modify the
constraints associated with the target filter object. This operation can be used both to
remove constraints currently associated with the target filter object, and to modify the
constraint expressions of constraints which have previously been added to the target
filter object.
The operation accepts two input parameters. The first input parameter is 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 the target filter
object.
The second input parameter to this operation is 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 the 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.
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, 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 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.
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.
- Parameters:
del_list
- ID's of constraint exp to be deletemodify_list
- ConstraintInfo containing all constraint to be modified
- Throws:
InvalidConstraint
- If a constraint doesn't respect
grammar
ConstraintNotFound
- Invalid ID's
get_constraints
ConstraintInfo[] get_constraints(int[] id_list)
throws ConstraintNotFound
- The get_constraints operation is invoked to return a sequence of a subset of the
constraints associated with the target filter object. The operation accepts as input a
sequence of numeric values which should correspond to the unique identifiers of
constraints encapsulated by the target object. If one of the input values does not
correspond to the identifier of some encapsulated constraint, the ConstraintNotFound
exception is raised, containing as data the numeric value that did not correspond to
some constraint. 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.
- Parameters:
id_list
- Id of all constraints to get
- Returns:
- ConstraintInfo array
- Throws:
ConstraintNotFound
- If an ID is invalid. Exception
contains this ID
get_all_constraints
ConstraintInfo[] get_all_constraints()
- The get_all_constraints operation returns all of the constraints 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 unique identifier.
- Returns:
- ConstraintInfo array
remove_all_constraints
void remove_all_constraints()
- The remove_all_constraints operation is invoked to remove all of the constraints
currently encapsulated by the target filter object. Upon completion, the target filter
object will still exist but have no constraints associated with it.
destroy
void destroy()
- The destroy operation destroys the target filter object, invalidating its object
reference.
match
boolean match(org.omg.CORBA.Any filterable_data)
throws UnsupportedFilterableData
- 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. The operation accepts as input a CORBA::Any which contains an event
to be evaluated, and returns a boolean value which will be TRUE in cases where the
input event satisfies one of the filter constraints, and FALSE otherwise.
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.
- Parameters:
filterable_data
- Event
- Returns:
- True if event must be throw, false otherwise
- Throws:
UnsupportedFilterableData
- Event can't be evaluate
match_structured
boolean match_structured(StructuredEvent filterable_data)
throws UnsupportedFilterableData
- 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. The operation accepts as input a data structure of type
CosNotification::StructuredEvent which contains an event to be evaluated, and returns
a boolean value which will be TRUE in cases where the input event satisfies one of the
filter constraints, and FALSE otherwise. 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.
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.
- Parameters:
filterable_data
- Event
- Returns:
- True if event must be throw, false otherwise
- Throws:
UnsupportedFilterableData
- Event can't be evaluate
match_typed
boolean match_typed(Property[] filterable_data)
throws UnsupportedFilterableData
- 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. 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), and returns a boolean
value which will be TRUE in cases where the input event satisfies one of the filter
constraints, and FALSE otherwise. 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.
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.
- Parameters:
filterable_data
- Event
- Returns:
- True if event must be throw, false otherwise
- Throws:
UnsupportedFilterableData
- Event can't be evaluate
attach_callback
int attach_callback(NotifySubscribe callback)
- The attach_callback operation accepts as input the reference to an object supporting
the CosNotifyComm::NotifySubscribe interface, and returns a numeric value
assigned to this callback that is unique to all such callbacks currently associated with
the target object. This operation is invoked to associate with the target filter object
an object supporting the CosNotifyComm::NotifySubscribe interface. This interface is
inherited by all supplier interfaces (either those that are clients of a notification
channel, or those that are proxy objects within a notification channel) defined by the
Notification Service, and supports a subscription_change operation. After this
operation has been successfully invoked on a filter object, each time the set of
constraints associated with the target filter object is modified (either by an invocation
of its add_constraints or its modify_constraints operations), the filter object will
invoke the subscription_change object of all its associated callback objects in order to
inform suppliers to which the target filter object is attached of the change in the set
of event types to which clients of the filter object subscribe. This enables suppliers to
make intelligent decisions about which types of events it should actually produce, and
which it can suppress the production of. This mechanism is described in more detail in
section 2.6.
- Parameters:
callback
-
- Returns:
- CallBacK ID
detach_callback
void detach_callback(int callback)
throws CallbackNotFound
- The detach_callback operation accepts as input a numeric value which should be one
of the unique identifiers associated with one of the callback objects attached to the
target filter object. If the input value does not correspond to the unique identifier of
a callback object currently attached to the target filter object, the CallbackNotFound
exception is raised. Otherwise, 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.
- Parameters:
callback
- Callback ID
- Throws:
CallbackNotFound
- ID not exist
get_callbacks
int[] get_callbacks()
- The get_callbacks operation accepts no input parameters and returns the sequence of
all unique identifiers associated with callback objects attached to the target filter
object.