com.j_spaces.core.filters

Interface ISpaceFilter

All Known Implementing Classes:

ExecutorSpaceFilter, FilterOperationDelegate, JSpaceStatistics, NotifyAcknowledgeFilter

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:

• BEFORE filters - filters with lower priorities will be activated first.
• AFTER filters - filters with higher priorities will be activated first.
• ON_INIT filters - filters with lower priorities will be activated first.

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.

Version:

1.0

Author:

Asaf Kariv

See Also:

FilterOperationCodes

Method Summary

Modifier and Type	Method and Description
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 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 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.