com.j_spaces.core.filters
Interface ISpaceFilter

All Known Implementing Classes:
DefaultSecurityFilter

public interface ISpaceFilter

A filter is a special hook point inside the engine that enables integration with external systems or implementation of user defined logic. The filter has a simple life-cycle: it initializes itself in the init() method, processes events in its process() method and finally cleans resources on close(). The process() method is called by the engine when an event that matches the filter's Operation Code. The possible codes are specified by the FilterOperationCodes class. Filters are grouped by priorities. The priority should be between 0 and 4. Filters with higher priorities are activated closer to the hook point. This means:

Since filters are activated in sensitive hook points in the engine, they should be careful with performing long blocking calls, such as connecting to databases.

See Also:
FilterOperationCodes

Method Summary
 void close()
          Closes this filter, enabling the developer to clean open resources.
 void init(IJSpace space, String filterId, String url, int priority)
          Initializes this filter.
 void process(SpaceContext context, ISpaceFilterEntry[] entries, int operationCode)
          This method is called by the engine when an event matching this filter's operation code occurs in the engine.
 void process(SpaceContext context, ISpaceFilterEntry entry, int operationCode)
           This method is called by the engine when an event matching this filter's operation code occurs in the space engine.
 

Method Detail

init

void init(IJSpace space,
          String filterId,
          String url,
          int priority)
          throws RuntimeException
Initializes this filter.

Parameters:
space - an embedded proxy to the space that contain this filter.
filterId - the name of this filter.
url - The URL that was passed when this filter was created.
priority - defines the order in which filters are activated.
Throws:
RuntimeException - if this exception is raised, the filter will be discarded by the engine for the current engine execution ,unless defined otherwise in space configuration.

process

void process(SpaceContext context,
             ISpaceFilterEntry entry,
             int operationCode)
             throws RuntimeException
 This method is called by the engine when an event matching this filter's
  operation code occurs in the space engine.

 Only for SecurityFilter implementation: On SET_SECURITY operation code call SpaceContext.setSecurityContext().
 

Parameters:
context - the Context passed by the caller, contains security context. some of the filters (like ON_INIT) will always receive a null context.
entry - the event that occurred.
operationCode - the operation that defines when this filter is activated. The operation codes are defined in FilterOperationCodes.
Throws:
RuntimeException - if this exception is raised for BEFORE filters, it aborts the execution of the operation.

process

void process(SpaceContext context,
             ISpaceFilterEntry[] entries,
             int operationCode)
             throws RuntimeException
This method is called by the engine when an event matching this filter's operation code occurs in the engine.

Notice: This is a special case that is called only on replace() BEFORE_UPDATE and AFTER_UPDATE and on update() only on AFTER_UPDATE.
Also on BEFORE_NOTIFY_TRIGGER and AFTER_NOTIFY_TRIGGER.

Parameters:
context - the Context passed by the caller, contains security context. some of the filters (like ON_INIT) will always receive a null context.
entries - an array of two elements:

On BEFORE_UPDATE: the first element represents the template and the second is the new entry (can only happen when replace is called).

On AFTER_UPDATE: the first element represents the old entry while the second is the new entry.

On BEFORE_NOTIFY_TRIGGER and AFTER_NOTIFY_TRIGGER: the first element represents the entry while the second is the template.

operationCode - the operation that defines when this filter is activated. The operation codes are defined in FilterOperationCodes.
Throws:
RuntimeException - if this exception is raised for BEFORE filters,

close

void close()
           throws RuntimeException
Closes this filter, enabling the developer to clean open resources.

Throws:
RuntimeException - if this exception is raised it will be logged. This should be used as away to report a filter internal error.