xsmeral.pipe
Class AbstractObjectProcessor

java.lang.Object
  xsmeral.pipe.AbstractObjectProcessor

All Implemented Interfaces:

Runnable, ContextAware, ObjectProcessor

Direct Known Subclasses:

LocalObjectFilter, LocalObjectSink, LocalObjectSource

public abstract class AbstractObjectProcessor
extends Object
implements ObjectProcessor

Implements basic functionality common for all object processors.
Provides default (however, overloadable) implementation of the run method, which defines a specific life-cycle of the processor, with multiple initialization phases and life-cycle stages.
The complete cycle is as follows:

Initialization

The initialize method

1. initializes parameters using ParamInitializer
2. calls initializeInternal()
3. marks the processor as initialized, so that any following invocation of this method returns immediately

Therefore, in initializeInternal the processor can access the initialization parameters but not yet the context parameters.

Context initialization

The context-related methods accessible from outside should be called in the following order:

1. setContext(), which assigns the processor a context and in turn calls:
   1. initWithContext() which can be used to access context parameters already set by an external entity (not those set by other processors)
   2. initContextSet() which sets context parameter values from ToContext fields
2. initContext(), which initializes fields annotated with FromContext with values from context and in turn calls:
   1. initPostContext() at which time all context parameters and all context-dependent fields can be accessed

Running

After initialization (which is, however, not required), the processor can be started, using the run() method. The default run cycle is as follows:

1. the processor is in NOT_STARTED state
2. preRun() is called, where the processor can perform any preparatory operations
3. status is set to RUNNING
4. process() is called in loop, while the status is RUNNING. If a neighboring processor stops, this processor stops.
5. postRun() is called, which can be used for cleanup and releasing resources

Nested Class Summary

Nested classes/interfaces inherited from interface xsmeral.pipe.interfaces.ObjectProcessor

ObjectProcessor.Status

Field Summary

protected boolean	canStart Starting condition indicator (true by default)
protected ProcessingContext	context Associated context (might be null)
protected ObjectProcessor.Status	status Current status

Constructor Summary

AbstractObjectProcessor()
Sets the status to NOT_STARTED.

Method Summary

boolean	canStart() Indicates whether the processor is ready to start (is correctly initialized).
protected void	failStart() Called by the processor itself, indicates negative starting conditions.
void	failStart(String message) In addition to failStart(), logs a message indicating the reason for the inability to start
void	failStart(String message, Throwable thrown) In addition to failStart(String), logs a Throwable
ProcessingContext	getContext() Returns the associated processing context.
Class	getInType() Returns the input type of this processor.
Class	getOutType() Returns the output type of this processor.
Map<String,String>	getParams() Returns the parameter map that was used to initialize this processor.
ObjectProcessor.Status	getStatus() Returns current status of this processor.
void	initContext() Initializes (reflectively) the values of all fields annotated with FromContext with values taken from the context.
protected void	initContextSet() Initializes (reflectively) context parameters from fields annotated with ToContext.
ObjectProcessor	initialize(Map<String,String> params) Initializes the processor.
protected void	initializeInternal() Should initialize the processor for running, analogically to constructor.
protected void	initPostContext() Called after context-dependencies (FromContext fields) are resolved.
protected void	initWithContext() Called after a context is assigned.
protected void	postRun() Called as the last statement in run().
protected void	preRun() Called after initialization, as the first statement in run().
protected abstract void	process() Called by the processor itself from run().
void	requestStop() Requests the processor to stop and sets its status to STOPPING.
void	run() Starts the processing, putting the processor into running state.
void	setContext(ProcessingContext context) Associates the processor with the given context.
protected void	stop() Called by the processor itself, sets the status to STOPPED
String	toString() Returns simple class name of this processor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

status

protected ObjectProcessor.Status status

Current status

context

protected ProcessingContext context

Associated context (might be null)

canStart

protected boolean canStart

Starting condition indicator (true by default)

Constructor Detail

AbstractObjectProcessor

public AbstractObjectProcessor()

Sets the status to NOT_STARTED.

Method Detail

getStatus

public final ObjectProcessor.Status getStatus()

Description copied from interface: ObjectProcessor

Returns current status of this processor.

Specified by:

getStatus in interface ObjectProcessor

getParams

public Map<String,String> getParams()

Returns the parameter map that was used to initialize this processor.

canStart

public boolean canStart()

Description copied from interface: ObjectProcessor

Indicates whether the processor is ready to start (is correctly initialized).

Specified by:

canStart in interface ObjectProcessor

Returns:

True, if the processor is ready to start.

failStart

protected final void failStart()

Called by the processor itself, indicates negative starting conditions.

failStart

public final void failStart(String message)

In addition to failStart(), logs a message indicating the reason for the inability to start

failStart

public final void failStart(String message,
                            Throwable thrown)

In addition to failStart(String), logs a Throwable

requestStop

public void requestStop()

Description copied from interface: ObjectProcessor

Requests the processor to stop and sets its status to STOPPING. There is no limit to the time it takes the processor to stop, it should however stop as soon as possible.
Only the first processor in chain should be requested to stop.

Specified by:

requestStop in interface ObjectProcessor

run

public void run()

Starts the processing, putting the processor into running state. More information in description of AbstractObjectProcessor class, section "Running".

Specified by:

run in interface Runnable

Specified by:

run in interface ObjectProcessor

getOutType

public final Class getOutType()

Description copied from interface: ObjectProcessor

Returns the output type of this processor.

Specified by:

getOutType in interface ObjectProcessor

getInType

public final Class getInType()

Description copied from interface: ObjectProcessor

Returns the input type of this processor.

Specified by:

getInType in interface ObjectProcessor

stop

protected void stop()

Called by the processor itself, sets the status to STOPPED

getContext

public final ProcessingContext getContext()

Returns the associated processing context. Might return null.

Specified by:

getContext in interface ContextAware

setContext

public final void setContext(ProcessingContext context)
                      throws ObjectProcessorException

Associates the processor with the given context. Also, initializes context parameters from fields annotated with ToContext.

Specified by:

setContext in interface ContextAware

Throws:

ObjectProcessorException

initContextSet

protected final void initContextSet()
                             throws ObjectProcessorException

Initializes (reflectively) context parameters from fields annotated with ToContext.

Throws:

ObjectProcessorException - If a parameter already exists in the context.

initContext

public final void initContext()
                       throws ObjectProcessorException

Description copied from interface: ContextAware

Initializes (reflectively) the values of all fields annotated with FromContext with values taken from the context. The context parameter name is either the field name or a name specified as an argument of FromContext.

Specified by:

initContext in interface ContextAware

Throws:

ObjectProcessorException

initialize

public final ObjectProcessor initialize(Map<String,String> params)

Initializes the processor. Should only be called once per instance. After returning from this method, the processor should be ready to start (or indicate inability to start when queried by canStart).

More information is provided in description of AbstractObjectProcessor class, section "Initialization".

Specified by:

initialize in interface ObjectProcessor

Parameters:

params - Initialization parameters, substitute for constructor arguments

Returns:

Should return this, so that the processor can be instantiated and initialized in one command:

    new SomeProcessor().initialize(params);

toString

public String toString()

Returns simple class name of this processor.

Overrides:

toString in class Object

Returns:

getClass().getSimpleName()

initializeInternal

protected void initializeInternal()

Should initialize the processor for running, analogically to constructor. More information in description of AbstractObjectProcessor class, section "Initialization".

initWithContext

protected void initWithContext()

Called after a context is assigned. More information in description of AbstractObjectProcessor class, section "Context initialization".

initPostContext

protected void initPostContext()

Called after context-dependencies (FromContext fields) are resolved. More information in description of AbstractObjectProcessor class, section "Context initialization".

preRun

protected void preRun()
               throws ProcessorStoppedException

Called after initialization, as the first statement in run(). More information in description of AbstractObjectProcessor class, section "Running".

Throws:

ProcessorStoppedException

postRun

protected void postRun()

Called as the last statement in run(). More information in description of AbstractObjectProcessor class, section "Running".

Throws:

ProcessorStoppedException

process

protected abstract void process()
                         throws ProcessorStoppedException

Called by the processor itself from run(). Should process one object and return. More information in description of AbstractObjectProcessor class, section "Running".

Throws:

ProcessorStoppedException - If a neighboring processor has stopped.