...
Actions are the lightweight alternative to Pentaho BI Components. For an understanding of how and why they are different, let's take a step back and examine what a BI Component is and how it is used. A BI Component is historically a Java class that does some work, yielding some output, when it is provided certain inputs and resources. The work done as well as the inputs and resources required are entirely up to the component developer. It's purpose is to perform some work in a sequential success-based workflow (action sequence). A saavy BI Platform user with a bit of inclination for Java coding can implement his or her own custom component to do just about anything. However, this is not an easy endevour endeavour since developing your own BI Component requires intimate knowledge of internal Pentaho APIs. When you are done writing your custom component, the code you have written will be tightly coupled to the Pentaho BI Platform, so much so, that it will be difficult to unit test and may be difficult to maintain.
These are some of the problems that the Action API seeks to solve. As we mentioned earlier, Actions are the lightweight alternative to developing Components. So, what do we mean by "lightweight"? Well, we have taken the complex set of APIs required to implement a Component and reduced it to a handful of concise APIs. Moreover, with IAction and thus the "execute()" API at the heart of it all. With the new Action framework, we allow you to write a Java bean that performs the action you desire, and simply decorate it with the appropriate API for the desired interaction with the platform. These platform interaction APIs will discussed in more detail later, but they are essentially:
...
Sometimes your Action bean will need to pass inputs through to another subsystem and not act on them directly. For these inputs, it is cumbersome and sometimes impossible to create setter methods for each possible input. If this is the case for you, then have your Action bean implement the IVarArgsAction interface. This will allow you to receive a map containing all the inputs that were specified in the action definition but had no setter method counterpart in your Action bean.
Outputs
Normal Outputs
At the end of a step in an action sequence, the Action framework will attempt to retrieve data from your Action bean (per the action-outputs section of the action definition) by calling various getter methods. The framework will loop through the listed outputs and set them to the appropriate context. A discussion about the "appropriate" context is out of scope here, but suffice it to say the output data will be stored in a session-like structure and will be made accessible if you should chose to bind it to the input of a subsequent step, or bound in a way that will direct the data to the user for viewing or to a data sync such as a file. You will notice that the type attribute is not required for action outputs, other than the special case "content" type which behaves very differently from other outputs.
xaction output | Java type | expected Action bean method (Java) |
|---|---|---|
<myOutput> (no type specified) | user specified | public SomeType getMyOutput() { ... |
Streaming Outputs
The content type output is treated like an input since the presence of a content type output implies that your Action bean intends to write to a pre-existing data stream. This Prior to the invocation of your Action's execute method, this pre-existing stream is retrieved by the Action framework and passed to your Action bean as a java.io.OuputStream prior to your Action bean executing. If you intend your Action bean to be able to handle content type outputs, and thus writing to an output stream, then your Action bean is required to implement IStreamingAction. This API provides the Action framework with information about the type of data you are writing to the stream.
xaction output | Java type | expected Action bean method (Java) |
|---|---|---|
<myOutput> (no type specified) | user specified | public SomeType getMyOutput() { ... |
<myOutput type="content"/> | java.io.OutputStream | public void setMyOutputStream(OutputStream o) |
...
xaction resource | Java type | expected Action bean method (Java) |
|---|---|---|
<myResource type="resource"/> | java.io.InputStream | setMyResource(InputStream o) { ... |
|
|
The Execute API
As we mentioned earlier, the heart of the Action framework is it's ability to do some work, thus, the IAction.execute() API. The only interface your Action bean is required to implement is the IAction interface which specifies only a single method, "execute()". All the other interfaces listed in intro section above are just there to provide either your Action bean or the Action framework with additional context about this execution.