03. Handling Resources

getResource()

It is important to call isDefinedResource() or getResourceNames() before asking for access to an output as an error will occur if you ask for an output that has not been defined in the action sequence.

getResourceAsString()

Returns the contents of the specific resource as a String. It is important to call isDefinedResource() or getResourceNames() before asking for access to an output as an error will occur if you ask for an output that has not been defined in the action sequence.

if( isDefinedResource("message-template") ) {
    String template = getResourceAsString("message-template" );
}

getResourceDataSource()

Returns the contents of the specified resource as a DataSource object. It is important to call isDefinedResource() or getResourceNames() before asking for access to an output as an error will occur if you ask for an output that has not been defined in the action sequence.

if( isDefinedResource("message-template") ) {
    DataSource source = getResourceDataSource("message-template" );
}

getResourceInputStream()

Returns an input stream to the contents of the specified resource. It is important to call isDefinedResource() or getResourceNames() before asking for access to an output as an error will occur if you ask for an output that has not been defined in the action sequence.

if( isDefinedResource("message-template") ) {
    InputStream stream = getResourceInputStream("message-template" );
}

getResourceNames()

Returns the names of all the available resources defined in the action sequence. This is useful for examining the names of the available resources so the component does not request resources that are not available.

isDefinedResource()

Returns whether the specified resource has been defined in the action sequence.

Handling User Interaction
These methods are used to create prompts that will be shown to the user. They are useful for automatically generating parameter pages. The template that is used to create the layout of the page is specified by the action sequence and can be either an HTML template or an XSLT template. If a template is not specified a default XSLT (system/custom/xsl/DefaultParameterForm.xsl in the solution folders) is used.

createFeedbackParameter()

See same method (different signature below).

createFeedbackParameter()

This creates a parameter prompt that presents a text box to the user.

fieldname: specifies the id of the form element for this prompt. This id will appear on the request when the user clicks to submit their selections. If the action sequence does not define an input from the request that matches this id, the component will never receive the value selected by the user, and an infinite loop can occur where the user is continually prompted for the same thing without end.

displayName: the text that the user will see as the label for the parameter.

hint: a help tip that the user will see next to the parameter.

defaultValues: the default value that will be automatically displayed for the user when they see the prompt page.

visible: an flag that determines whether the user can see the form control. If this is set to 'false' a hidden form field is created.

dispNames: a Map that stores a user-friendly description for each value. If the map does not store a description for a given value, the value will be shown to the user. If there are no user-friendly descriptions for any values, you can pass a null for this parameter.

createFeedbackParameter()

This creates a parameter prompt that will be present the user with a collection of items to choose from. The component has to specify the list of options. A good example of this is the print component (org.pentaho.plugin.print.PrintComponent) which creates a list of printers available to the component and then calls createFeedbackParameter() to let the user select a printer.

fieldname: specifies the id of the form element for this prompt. This id will appear on the request when the user clicks to submit their selections. If the action sequence does not define an input from the request that matches this id, the component will never receive the value selected by the user, and an infinite loop can occur where the user is continually prompted for the same thing without end.

displayName: the text that the user will see as the label for the parameter.

hint: a help tip that the user will see next to the parameter.

defaultValues: an object that stores the default value(s) that will be automatically selected for the user when they see the prompt page. This object can be a String, or String array. If the control type specified in displayStyle is not capable of selecting multiple items but a String array is provided for the defaultValues, the single item selected cannot be predicted.

values: an ordered list of values that the user will select from. This collection stores the values that you want the component to receive back when the user selects something. If you want the user to see the items described with different names to the ones in this list the component must supply a dispNames map.

dispNames: a Map that stores a user-friendly description for each value. If the map does not store a description for a given value the value will be shown to the user. If there are no user-friendly descriptions for any values you can pass a null for this parameter.

displayStyle: specifies the control that should be used to present the choices to the user. The allowed values are:
radio:                 Radio buttons
select:             A dropdown select / combo box
list:                 A single select list box
list-multi:             A multi-select list box
check-multi:             A multi-select collection of check-boxes
check-multi-scroll:         A scrolling, multi-select set of check boxes
check-multi-scroll-2-column:    A scrolling, two-column, multi-select set of check boxes
check-multi-scroll-3-column:    A scrolling, three-column, multi-select set of check boxes
check-multi-scroll-4-column:     A scrolling, four-column, multi-select set of check boxes

Example
The printer component creates a list of printer names for the user to select from. It uses the last printer used as the default selection. It does not provide a hint to the user or provide a mapping of display names for the printer names. It specifies that a select list (combo box) should be used to get the users input.

ArrayList values = new ArrayList();
for (int i = 0; i < services.length; i++) {
    String value = services\[i\].getName();
    values.add(value);
}

createFeedbackParameter("printer-name", "Printer Name", "",
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; lastPrinterName, values, null, "select");
promptNeeded();

feedbackAllowed()

This returns true if the component is allowed to ask the use for parameters. If the request to execute an action sequence originated from a web application, this will return 'true'. If the request comes from a web service client, a scheduler, or a workflow engine there is no user to request anything from, and this method will return 'false';

getFeedbackOutputStream()

This is used in cases where a component needs to provide feedback to the user about a problem other than needing input. For example, the email component uses this method when the email server settings have not been defined to present an informative message to the user about how to fix the problem.

getOutputPreference()

A component can use this method to find out what kind of output the Runtime Context is most interested in. The valid values are stored in org.pentaho.core.solution.IOutputHandler and are
OUTPUT_TYPE_PARAMETERS
OUTPUT_TYPE_CONTENT
OUTPUT_TYPE_DEFAULT

isPromptPending()

This enables the component to find out if other components have requested parameters from the user. If this method returns true a component should not attempt to execute or create content but should only determine if it needs to prompt for parameters itself.

promptNeeded()

This informs the Runtime Context that the user needs to be prompted for parameters that the component needs. Other components in the action sequence will be executed to see if they also have parameters to for which to prompt. This enables the system to generate a single input form for users instead of presenting the user with a succession of input forms. For example, if the first component in an action sequence is a report component that needs a department id and the second component in the sequence is a print component that needs a printer name, the user will be presented with a single form that lets them select a department and a printer.

promptNow()

[java/io/OutputStream.html@java|java/io/OutputStream.html@java]

This informs the Runtime Context that the user needs to be prompted for parameters that the component needs and that components later in the action sequence should not be given the opportunity to provide parameters. This can be used for security purposes and can be used to prevent needless processing. For example consider an action sequence with two action definitions. The first is a Web Service business rule that needs to prompt for a customer id if it is not provided on the request, and the second is a report component that takes the result of the first component as its input. If the customer id has not been provided, the first component needs to prompt for it. In this case, there is no point executing the report component (causing the report definition to be parsed) to see if it needs to prompt for any parameters because the context of the action sequence tells us it does not.

setFeedbackMimeType()

This sets the mime type of the feedback page. Currently this needs to be set to 'text/html'. In the future mime types for other devices could be supported.