public interface IStep extends StepParameters
A Java? Plugin that needs to interact directly with Data Management DataFlow interfaces during the execution of a job.
As is the case with ISimpleStep
based plugins, the Full Feature plugin implementation
may define and receive configuration parameters as name/value pairs via the methods defined in the
base StepParameters
interface.
A Full Feature plugin may have a maximum of one parent step and one child step. Unlike an
ISimpleStep
based plugin, the Full Feature plugin is not required to have a parent
step.
If you do not require advanced capabilities such as generating multiple output rows for each input row,
inspecting the state of other steps in a job, or the ability to log or generate statistics,
you may want to implement ISimpleStep
instead.
The IStep
methods are called in the following order:
getParameterCount()
initialize()
prep()
preExec()
next()
release()
Note: The StepAdapter
abstract class provides an extendable implementation of the
IStep
interface.
Modifier and Type | Field and Description |
---|---|
static int |
PREP_FLAG_FULL
Indicates that a full preparation is required.
|
static int |
PREP_FLAG_QUICK
Indicates the plugin should try to prepare quickly.
|
Modifier and Type | Method and Description |
---|---|
long |
getNumRows()
Get total number of rows that will be output by the plugin.
|
StepStatus |
getStatus()
Return the status of a running step.
|
void |
initialize(PlugStep step)
Notify the plugin of its associated
PlugStep instance. |
StepReadState |
next()
Retrieve the next row.
|
void |
postExec()
Execution of the job is complete.
|
boolean |
preExec()
Prepare for execution.
|
PrepState |
prep(int flags)
Prepare input and output fields.
|
void |
release()
Release resources.
|
getParameterCount, getParameterName, setParameterValue
static final int PREP_FLAG_QUICK
Flag used by prep()
.
If the plugin cannot prepare quickly, it will return PrepState.FAILED
,
or one or more of the other prep states to indicate what was successfully prepped.
static final int PREP_FLAG_FULL
Flag used by prep()
.
If the plugin receives this flag, it can be guaranteed that all of the parent steps have successfully prepped with this flag.
void initialize(PlugStep step) throws StepException
PlugStep
instance.
Called immediately after the plugin is instantiated. The main purpose of this method is
to provide the plugin with the handle to the DataFlow step object (an instance of PlugStep
).
The plugin should cache this handle object locally and use it to interact with the DataFlow
engine.
IMPORTANT: The PlugStep
handle should never be used outside the context
and lifecycle of the instance of this plugin. Doing so could crash the DataFlow process.
This means that the handle should not be passed as an argument to any method nor stored in a
static location external to the plugin instance.
step
- The handle to the DataFlow step object.StepException
- If initialization fails.void release()
Called immediately before the plugin is released for garbage collection. This usually happens when the process running a job shuts down, although it can also happen in DataFlow when a node is deleted from a job. The plugin should release any resources, such as file handles, here.
PrepState prep(int flags)
This will be called before preExec()
(unless no paramSet values have changed since the
last call). It will also be called when the user is requesting input names that a plugin requires or output
information that a plugin provides. The plugin is expected to build the output items with
PlugStep.buildOutputItems()
and build input names with
PlugStep.addInputName()
. Once this has been called
a single time, it will not be called again unless paramSet values have changed. This is called caching the preparedness.
If the plugin returns anything other than PrepState.ALL_SUCCESS
from this method, it
will not be cached, and will be called again the next time it is required. In addition, it will only be cached if it has
been called with PREP_FLAG_FULL
.
flags
- This will be PREP_FLAG_FULL
if the parent and all its
parents were successfully prepped. This is to allow prep to be called when one of the parents
failed to prep in the event the plugin is still able to get input names without the parent
being fully prepared.PrepState.ALL_SUCCESS
.
If everything failed, return PrepState.FAILED
. If partially
successful, return one of the other PrepState
values. This allows the DataFlow engine
to still process certain requests. If PrepState.FAILED
is returned, the
plugin should also indicate the error with PlugStep.setError
.boolean preExec()
Called when execution of the job is desired. The plugin is expected to prepare itself for execution.
Call PlugStep.getExecutionType
to determine the type of execution
desired. When this method is called, it is guaranteed that prep
has been called
with PREP_FLAG_FULL
on this and all parent steps.
The plugin should calculate the number of rows it expects to produce at this point, if possible.
true
on success, or false
on failure. If false
is returned,
the plugin should also indicate the error with PlugStep.setError
.StepReadState next()
Called when the next row is desired. The plugin should fetch the row and make it available via
PlugStep.getExistingOutputItems()
.
If the plugin has a parent, parent rows may be retrieved by
PlugStep.parentOutputItems()
.
StepReadState
that indicates the status of the row processing.
This must always be non-null.void postExec()
Called after job execution is complete. This is used to notify the plugin that it should do any cleanup after execution. This may be called after the step generated an error.
StepStatus getStatus()
If the status is unknown, or if the step does not care to report the status, return null
.
StepStatus
that details the status of the plugin. This can
be null
if the status is unknown or unprovided.long getNumRows()
If a plugin knows how many rows it will return, it should return this number.
Otherwise, the plugin should -1
.
-1
.Copyright © 2012 SAS Institute Inc. All Rights Reserved.