AbstractFilter (JacORB Services 3.5 API)

java.lang.Object
- org.jacorb.notification.filter.AbstractFilter

All Implemented Interfaces:

AbstractFilterMBean, GCDisposable, JMXManageable, NotifyingDisposable, IServantLifecyle, FilterOperations, org.picocontainer.Disposable

Direct Known Subclasses:

BSHFilter, ETCLFilter
```
public abstract class AbstractFilter
extends Object
implements GCDisposable, IServantLifecyle, FilterOperations, JMXManageable, AbstractFilterMBean
```
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). Every conformant implementation of this service must support constraint expressions expressed in the default constraint grammar described in Section 2.4, "The Default Filter Constraint Language," on page 2-23. 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 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.

Author:

Alphonse Bendt, John Farrell

Nested Class Summary
- Nested classes/interfaces inherited from interface org.jacorb.notification.interfaces.JMXManageable
  JMXManageable.JMXCallback

Field Summary

Fields
Modifier and Type	Field and Description
`protected Map`	`constraints_` contains the associated constraints.
`static int`	`CONSTRAINTS_EMPTY`
`protected ReadWriteLock`	`constraintsLock_`
`protected MessageFactory`	`messageFactory_`
`static int`	`NO_CONSTRAINTS_MATCH`
`protected WildcardMap`	`wildcardMap_`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractFilter(Configuration config, EvaluationContextFactory evaluationContextFactory, MessageFactory messageFactory, POA poa)`

Method Summary

Methods
Modifier and Type	Method and Description
`Object`	`activate()`
`ConstraintInfo[]`	`add_constraints(ConstraintExp[] constraintExp)` 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 notifySubscribe)`
`void`	`attemptDispose()`
`void`	`deactivate()`
`void`	`destroy()`
`void`	`detach_callback(int id)`
`void`	`dispose()`
`ConstraintInfo[]`	`get_all_constraints()`
`int[]`	`get_callbacks()`
`ConstraintInfo[]`	`get_constraints(int[] ids)`
`Date`	`getCreationDate()`
`Iterator`	`getIterator(Object key)`
`String[]`	`getJMXNotificationTypes()`
`String`	`getJMXObjectName()`
`Date`	`getLastUsage()`
`long`	`getMatchCount()`
`long`	`getMatchStructuredCount()`
`long`	`getMatchTypedCount()`
`POA`	`getPOA()`
`String`	`listContraints()`
`protected int`	`match_internal(Any anyEvent)` match Any to associated constraints.
`protected int`	`match_structured_internal(StructuredEvent structuredEvent)` match the StructuredEvent to the associated constraints.
`boolean`	`match_structured(StructuredEvent structuredevent)`
`protected int`	`match_typed_internal(Property[] typedEvent)` match the TypedEvent to the associated constraints.
`boolean`	`match_typed(Property[] properties)`
`boolean`	`match(Any anyEvent)`
`void`	`modify_constraints(int[] deleteIds, ConstraintInfo[] constraintInfo)`
`protected int`	`newConstraintId()`
`protected abstract FilterConstraint`	`newFilterConstraint(ConstraintExp constraintExp)` create a new FilterConstraint based on the provided ConstraintExp
`Servant`	`newServant()`
`void`	`registerDisposable(Disposable disposeHook)` the hooks registered by this method will be run when dispose is called.
`void`	`remove_all_constraints()`
`void`	`setJMXCallback(JMXManageable.JMXCallback callback)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.omg.CosNotifyFilter.FilterOperations
constraint_grammar

- Field Detail
  - NO_CONSTRAINTS_MATCH
```
public static final int NO_CONSTRAINTS_MATCH
```
    See Also:
    Constant Field Values
  - CONSTRAINTS_EMPTY
```
public static final int CONSTRAINTS_EMPTY
```
    See Also:
    Constant Field Values
  - constraints_
```
protected final Map constraints_
```
    contains the associated constraints. as access to constraints_ is controlled by constraintsLock_ its safe to use unsynchronized HashMap here
  - wildcardMap_
```
protected final WildcardMap wildcardMap_
```
  - constraintsLock_
```
protected final ReadWriteLock constraintsLock_
```
  - messageFactory_
```
protected final MessageFactory messageFactory_
```
- Constructor Detail
  - AbstractFilter
```
protected AbstractFilter(Configuration config,
              EvaluationContextFactory evaluationContextFactory,
              MessageFactory messageFactory,
              POA poa)
                  throws ConfigurationException
```
    Throws:
    
    ConfigurationException
- Method Detail
  - newServant
```
public final Servant newServant()
```
    Specified by:
    
    newServant in interface IServantLifecyle
  - getPOA
```
public final POA getPOA()
```
    Specified by:
    
    getPOA in interface IServantLifecyle
  - activate
```
public final Object activate()
```
  - deactivate
```
public final void deactivate()
```
  - newConstraintId
```
protected int newConstraintId()
```
  - add_constraints
```
public ConstraintInfo[] add_constraints(ConstraintExp[] constraintExp)
                                 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, "The Filter Interface," on page 3-14) 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 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.
    
    Specified by:
    
    add_constraints in interface FilterOperations
    
    Throws:
    
    InvalidConstraint
  - newFilterConstraint
```
protected abstract FilterConstraint newFilterConstraint(ConstraintExp constraintExp)
                                                 throws InvalidConstraint
```
    create a new FilterConstraint based on the provided ConstraintExp
    
    Throws:
    
    InvalidConstraint
  - modify_constraints
```
public void modify_constraints(int[] deleteIds,
                      ConstraintInfo[] constraintInfo)
                        throws ConstraintNotFound,
                               InvalidConstraint
```
    Specified by:
    
    modify_constraints in interface FilterOperations
    
    Throws:
    
    ConstraintNotFound
    
    InvalidConstraint
  - get_constraints
```
public ConstraintInfo[] get_constraints(int[] ids)
                                 throws ConstraintNotFound
```
    Specified by:
    
    get_constraints in interface FilterOperations
    
    Throws:
    
    ConstraintNotFound
  - get_all_constraints
```
public ConstraintInfo[] get_all_constraints()
```
    Specified by:
    
    get_all_constraints in interface FilterOperations
  - remove_all_constraints
```
public void remove_all_constraints()
```
    Specified by:
    
    remove_all_constraints in interface FilterOperations
  - destroy
```
public void destroy()
```
    Specified by:
    
    destroy in interface AbstractFilterMBean
    
    Specified by:
    
    destroy in interface FilterOperations
  - getIterator
```
public Iterator getIterator(Object key)
```
  - match
```
public boolean match(Any anyEvent)
              throws UnsupportedFilterableData
```
    Specified by:
    
    match in interface FilterOperations
    
    Throws:
    
    UnsupportedFilterableData
  - match_internal
```
protected int match_internal(Any anyEvent)
                      throws UnsupportedFilterableData
```
    match Any to associated constraints. return the id of the first matching filter or NO_CONSTRAINT.
    
    Throws:
    
    UnsupportedFilterableData
  - match_structured
```
public boolean match_structured(StructuredEvent structuredevent)
                         throws UnsupportedFilterableData
```
    Specified by:
    
    match_structured in interface FilterOperations
    
    Throws:
    
    UnsupportedFilterableData
  - match_structured_internal
```
protected int match_structured_internal(StructuredEvent structuredEvent)
                                 throws UnsupportedFilterableData
```
    match the StructuredEvent to the associated constraints. return the id of the first matching filter or NO_CONSTRAINT.
    
    Throws:
    
    UnsupportedFilterableData
  - match_typed_internal
```
protected int match_typed_internal(Property[] typedEvent)
                            throws UnsupportedFilterableData
```
    match the TypedEvent to the associated constraints. return the id of the first matching filter or NO_CONSTRAINT.
    
    Throws:
    
    UnsupportedFilterableData
  - match_typed
```
public boolean match_typed(Property[] properties)
                    throws UnsupportedFilterableData
```
    Specified by:
    
    match_typed in interface FilterOperations
    
    Throws:
    
    UnsupportedFilterableData
  - attach_callback
```
public int attach_callback(NotifySubscribe notifySubscribe)
```
    Specified by:
    
    attach_callback in interface FilterOperations
  - detach_callback
```
public void detach_callback(int id)
```
    Specified by:
    
    detach_callback in interface FilterOperations
  - get_callbacks
```
public int[] get_callbacks()
```
    Specified by:
    
    get_callbacks in interface FilterOperations
  - dispose
```
public void dispose()
```
    Specified by:
    
    dispose in interface org.picocontainer.Disposable
  - registerDisposable
```
public void registerDisposable(Disposable disposeHook)
```
    Description copied from interface: NotifyingDisposable
    
    the hooks registered by this method will be run when dispose is called.
    
    Specified by:
    
    registerDisposable in interface NotifyingDisposable
  - getLastUsage
```
public Date getLastUsage()
```
    Specified by:
    
    getLastUsage in interface AbstractFilterMBean
  - getCreationDate
```
public Date getCreationDate()
```
    Specified by:
    
    getCreationDate in interface AbstractFilterMBean
  - getMatchCount
```
public long getMatchCount()
```
    Specified by:
    
    getMatchCount in interface AbstractFilterMBean
  - getMatchStructuredCount
```
public long getMatchStructuredCount()
```
    Specified by:
    
    getMatchStructuredCount in interface AbstractFilterMBean
  - getMatchTypedCount
```
public long getMatchTypedCount()
```
    Specified by:
    
    getMatchTypedCount in interface AbstractFilterMBean
  - listContraints
```
public String listContraints()
```
    Specified by:
    
    listContraints in interface AbstractFilterMBean
  - getJMXObjectName
```
public final String getJMXObjectName()
```
    Specified by:
    
    getJMXObjectName in interface JMXManageable
  - getJMXNotificationTypes
```
public String[] getJMXNotificationTypes()
```
    Specified by:
    
    getJMXNotificationTypes in interface JMXManageable
  - setJMXCallback
```
public void setJMXCallback(JMXManageable.JMXCallback callback)
```
    Specified by:
    
    setJMXCallback in interface JMXManageable
  - attemptDispose
```
public void attemptDispose()
```
    Specified by:
    
    attemptDispose in interface GCDisposable

Class AbstractFilter

Nested Class Summary

Nested classes/interfaces inherited from interface org.jacorb.notification.interfaces.JMXManageable

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.omg.CosNotifyFilter.FilterOperations

Field Detail

NO_CONSTRAINTS_MATCH

CONSTRAINTS_EMPTY

constraints_

wildcardMap_

constraintsLock_

messageFactory_

Constructor Detail

AbstractFilter

Method Detail

newServant

getPOA

activate

deactivate

newConstraintId

add_constraints

newFilterConstraint

modify_constraints

get_constraints

get_all_constraints

remove_all_constraints

destroy

getIterator

match

match_internal

match_structured

match_structured_internal

match_typed_internal

match_typed

attach_callback

detach_callback

get_callbacks

dispose

registerDisposable

getLastUsage

getCreationDate

getMatchCount

getMatchStructuredCount

getMatchTypedCount

listContraints

getJMXObjectName

getJMXNotificationTypes

setJMXCallback

attemptDispose