Package org.pentaho.platform.api.engine

Interface IRuntimeContext

  • All Superinterfaces:
    IAuditable, ILogger
    public interface IRuntimeContext
extends IAuditable, ILogger
    This interface defines methods and constants that are used during action execution to resolve parameters, inputs and outputs, resources, and persist the runtime data. Think of the runtime context as working storage for the execution of an action.
    Author:
    James Dixon

    • Field Detail

      • RUNTIME_CONTEXT_VALIDATE_FAIL

        static final int RUNTIME_CONTEXT_VALIDATE_FAIL
        Indicator of action validation failure
        See Also:
        Constant Field Values

      • RUNTIME_CONTEXT_VALIDATE_OK

        static final int RUNTIME_CONTEXT_VALIDATE_OK
        Indicator of action validation success
        See Also:
        Constant Field Values

      • RUNTIME_CONTEXT_RESOLVE_OK

        static final int RUNTIME_CONTEXT_RESOLVE_OK
        Indicates that the parameters for an action were able to be resolved.
        See Also:
        Constant Field Values

      • RUNTIME_CONTEXT_RESOLVE_FAIL

        static final int RUNTIME_CONTEXT_RESOLVE_FAIL
        Indicates that parameters for an action could not be resolved.
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_NOT_STARTED

        static final int RUNTIME_STATUS_NOT_STARTED
        When beginning execution of an action sequence, the status starts off as not started.
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_INITIALIZE_OK

        static final int RUNTIME_STATUS_INITIALIZE_OK
        Indicator that initialization happened successfully
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_INITIALIZE_FAIL

        static final int RUNTIME_STATUS_INITIALIZE_FAIL
        Indicator of initialization failure
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_RUNNING

        static final int RUNTIME_STATUS_RUNNING
        As an action sequence begins execution, the status is set to running.
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_SUCCESS

        static final int RUNTIME_STATUS_SUCCESS
        Indicates that the action executed successfully
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_FAILURE

        static final int RUNTIME_STATUS_FAILURE
        Indicator of action failure.
        See Also:
        Constant Field Values

      • RUNTIME_STATUS_SETUP_FAIL

        static final int RUNTIME_STATUS_SETUP_FAIL
        Indicates an invalid instance ID was passed into the execution of an action sequence
        See Also:
        Constant Field Values

      • PARAMETERS_FAIL

        static final int PARAMETERS_FAIL
        Currently only used as an indicator that BIRT report specification parameters could not be read.
        See Also:
        Constant Field Values

      • PARAMETERS_OK

        static final int PARAMETERS_OK
        Currently only used as an indicator that BIRT report specification parameters could be read properly.
        See Also:
        Constant Field Values

      • PARAMETERS_UI_NEEDED

        static final int PARAMETERS_UI_NEEDED
        Indicates that parameters are required by an action, and the parameters aren't available so they need to be prompted for.
        See Also:
        Constant Field Values

      • PROMPT_NO

        static final int PROMPT_NO
        Indicates that no parameter prompts are pending.
        See Also:
        Constant Field Values

      • PROMPT_WAITING

        static final int PROMPT_WAITING
        Indicates that parameter prompts are pending.
        See Also:
        Constant Field Values

      • PROMPT_NOW

        static final int PROMPT_NOW
        Indicates that we need to prompt immediately for parameters.
        See Also:
        Constant Field Values

    • Method Detail

      • getHandle

        String getHandle()
        Returns the unique context identifier. The handle is created during construction of the RuntimeContext object, and should be unique down to the date/time of construction. The default form of this as implemented in RuntimeContext includes context- plus the hashcode and the date/time.
        Returns:
        the unique handle.
        See Also:
        RuntimeContext

      • getActionTitle

        String getActionTitle()
        During execution of an action sequence, returns the IActionSequence#getTitle().
        Returns:
        Action sequence title
        See Also:
        IActionSequence#getSequenceTitle()

      • promptNow

        void promptNow()
        Forces the runtime to stop processing Actions and return to prompt

      • promptNeeded

        void promptNeeded()
        Sets the prompt flag but continue processing Actions

      • isPromptPending

        boolean isPromptPending()
        Tells if a component is waiting for a prompt
        Returns:
        true if a prompt is pending

      • getInstanceId

        String getInstanceId()
        Returns the unique execution instance. This is typically a GUID that can be used to track the entire execution of an action sequence all the way from beginning to end.
        Returns:
        unique instance Id

      • setActionSequence

        void setActionSequence​(IActionSequence actionSequence)
        Sets the current action sequence
        Parameters:
        actionSequence - The action sequence to validate

      • getUrlFactory

        IPentahoUrlFactory getUrlFactory()
        The Url Factory is used for building URL's that link to this or another application
        Returns:
        the URL Factory

      • getSolutionPath

        String getSolutionPath()
        Returns:
        The path within the solution holding the currently executing action sequence

      • getCurrentComponentName

        String getCurrentComponentName()
        Returns:
        The component in the action seqeuence that's being executed

      • getSession

        IPentahoSession getSession()
        Returns:
        The session that started execution of the current action sequence

      • audit

        void audit​(String messageType,
           String message,
           String value,
           long duration)
        Writes a message to the audit log.
        Parameters:
        messageType - Message type as defined in MessageTypes
        message - Message to appear in the log
        value - Value of an object to be logged.
        duration - For time-tracked execution paths, indicates the duration the task took
        See Also:
        IAuditEntry, IAuditable, org.pentaho.core.audit.MessageTypes

      • getInputParameter

        IActionParameter getInputParameter​(String name)
        Returns the named input parameter. This will search amongst all the input parameter providers ( IParameterProvider) in order until it finds the input parameter and returns it. Throws a NullPointerException if the parameter is not found. This method never returns null
        Parameters:
        name - The name of the parameter to get
        Returns:
        The parameter
        See Also:
        org.pentaho.platform.api.engine.services.IParameterProvider

      • getOutputParameter

        IActionParameter getOutputParameter​(String name)
        Returns the named output parameter. This will search amongst all the output parameter providers ( IParameterProvider) in order until it finds the output parameter and returns it. Throws a NullPointerException if the parameter is not found. This method never returns null
        Parameters:
        name - The name of the parameter to get
        Returns:
        The requested parameter
        See Also:
        org.pentaho.platform.api.engine.services.IParameterProvider

      • getResourceDefintion

        IActionSequenceResource getResourceDefintion​(String name)
        Gets the named resource definition from the executing action sequence. Throws a NullPointerException if the resource is not found. This method never returns null
        Parameters:
        name - The named resource to get
        Returns:
        The resource if it exists.
        See Also:
        IActionSequenceResource

      • getInputParameterValue

        Object getInputParameterValue​(String name)
        Gets the value of the specified input parameter. Throws a NullPointerException if the parameter is not found. This method never returns null
        Parameters:
        name - The named parameter to retrieve
        Returns:
        The IActionParameter#getValue()
        See Also:
        IActionParameter

      • getInputParameterStringValue

        String getInputParameterStringValue​(String name)
        Gets the value of the specified input parameter as a String. Throws a NullPointerException if the parameter is not found. This method never returns null
        Parameters:
        name - The named parameter to retrieve
        Returns:
        The IActionParameter#getStringValue()
        See Also:
        IActionParameter

      • getResourceDataSource

        org.pentaho.commons.connection.IPentahoStreamSource getResourceDataSource​(IActionSequenceResource actionResource)
                                                                   throws FileNotFoundException
        Gets the named resource as a DataSource.
        Parameters:
        actionResource - The resource to get from the SolutionRepository
        Returns:
        The DataSource
        Throws:
        FileNotFoundException

      • getResourceAsString

        String getResourceAsString​(IActionSequenceResource actionParameter)
                    throws IOException
        Gets the named resource as a String.
        Parameters:
        actionResource - The resource to get from the SolutionRepository
        Returns:
        The String
        Throws:
        IOException

      • getResourceAsDocument

        org.dom4j.Document getResourceAsDocument​(IActionSequenceResource actionParameter)
                                  throws IOException,
                                         org.dom4j.DocumentException
        Gets the named resource as a Document.
        Parameters:
        actionResource - The resource to get from the SolutionRepository
        Returns:
        The DataSource
        Throws:
        IOException
        org.dom4j.DocumentException

      • setOutputValue

        void setOutputValue​(String name,
                    Object output)
        Sets the value of a named output parameter
        Parameters:
        name - The name of the output parameter
        output - The value to set the output parameter to

      • addTempParameter

        void addTempParameter​(String name,
                      IActionParameter output)
        Adds a parameter to the current inputs. A component can be use this to create parameters for internal use or for new outputs.
        Parameters:
        name - The name of the temporary parameter
        output - The value to set the temporary parameter to

      • getOutputItem

        IContentItem getOutputItem​(String outputName,
                           String mimeType,
                           String extension)
        Returns an output stream for writing.
        Parameters:
        outputName - The name of the output
        mimeType - The mime type of the output
        extension - The file extension of the output
        Returns:
        OutputStream for writing to

      • getInputStream

        InputStream getInputStream​(String parameterName)
        Returns an input stream from an input parameter, if the input parameter is a content item.
        Parameters:
        parameterName - The name of the parameter
        Returns:
        An InputStream from the content item

      • getDataSource

        org.pentaho.commons.connection.IPentahoStreamSource getDataSource​(String parameterName)
        Get's the content item associated with the parameter, and returns the content item's datasource
        Parameters:
        parameterName - The name of the parameter
        Returns:
        The IPentahoStreamSource from the Content Item
        See Also:
        IContentItem.getDataSource()

      • getInputNames

        Set getInputNames()
        Returns:
        a Set containing all the inputs in the current action.

      • getResourceNames

        Set getResourceNames()
        Returns:
        a Set containing the resource names in the action

      • getOutputNames

        Set getOutputNames()
        Returns:
        a Set containing the output names in the current action

      • applyInputsToFormat

        String applyInputsToFormat​(String format)
        Does parameter substitution on the input string, searching for all parameter declarations in the input string, and substituting the value from the matching input parameter. In other words, it replaces {REGION} with the value of the input parameter called REGION.
        Parameters:
        format - The string containing possible parameter references
        Returns:
        String with parameters resolved.

      • applyInputsToFormat

        String applyInputsToFormat​(String format,
                           IParameterResolver resolver)
        Does parameter substitution on the input string, searching for all parameter declarations in the input string, and substituting the value from the matching input parameter. In other words, it replaces {REGION} with the value of the input parameter called REGION.
        Parameters:
        format - The string containing possible parameter references
        Resolver - for parameters for overriding behavior
        Returns:
        String with parameters resolved.

      • addInputParameter

        void addInputParameter​(String name,
                       IActionParameter param)
        Adds an input parameter to the list of all inputs for the action sequence
        Parameters:
        name - The name of the parameter (the key to the parameter map)
        param - The parameter to add
        See Also:
        IActionParameter

      • feedbackAllowed

        boolean feedbackAllowed()
        Returns:
        true if the current output device allows user feedback (i.e. parameter input forms)

      • getFeedbackContentItem

        IContentItem getFeedbackContentItem()
        Interfaces to the current output handler to get the content item that is handling feedback (i.e. parameter input forms)
        Returns:
        the Content Item for user input
        See Also:
        IContentItem, IOutputHandler

      • getOutputContentItems

        List<IContentItem> getOutputContentItems()
        Interfaces to the current context to get the content items which was generated
        Returns:
        The content item for output
        See Also:
        IContentItem

      • getOutputContentItem

        IContentItem getOutputContentItem​(String mimeType)
        Interfaces to the current output handler to get the content item that describes the output from this request's component execution.
        Returns:
        The content item for output
        See Also:
        IContentItem, IOutputHandler

      • getOutputContentItem

        IContentItem getOutputContentItem​(String outputName,
                                  String mimeType)
        Interfaces to the current output handler to get the named content item from this request's component execution.
        Parameters:
        outputName - the name of the output
        Returns:
        The requested content item
        See Also:
        IContentItem, IOutputHandler

      • createFeedbackParameter

        @Deprecated
void createFeedbackParameter​(IActionParameter actionParam)
        Deprecated.
        Adds a feedback parameter for prompts based on an Action Parameter. Uses the Selections defined in the Action Parameter for the options and sets the default to the current value
        Parameters:
        actionParam - The Action Parameter to use as the model for the prompt

      • createFeedbackParameter

        void createFeedbackParameter​(ISelectionMapper selMap,
                             String fieldName,
                             Object defaultValues)
        Adds a feedback parameter (essentially a form input field) for a required input.
        Parameters:
        selMap - Maps IPentahoResultSet objects to selection objects
        fieldName - Name of the form field
        defaultValues - default values for the input field
        See Also:
        SelectionMapper

      • createFeedbackParameter

        void createFeedbackParameter​(ISelectionMapper selMap,
                             String fieldName,
                             Object defaults,
                             boolean optional)
        Adds a feedback parameter (essentially a form input field) for a required input.
        Parameters:
        selMap - Maps IPentahoResultSet objects to selection objects
        fieldName - Name of the form field
        defaults - default values for the input field
        optional - specifies if the feedback parameter is required or not
        See Also:
        SelectionMapper

      • createFeedbackParameter

        void createFeedbackParameter​(String fieldName,
                             String displayName,
                             String hint,
                             Object defaultValue,
                             boolean visible)
        Adds a scalar feedback parameter
        Parameters:
        fieldName - Name of the input field
        displayName - display name of the input field
        hint - Fly-over hint for the input field
        defaultValue - Default value for the input field
        visible - Whether the input field is visible or not
        See Also:
        XForm

      • createFeedbackParameter

        void createFeedbackParameter​(String fieldName,
                             String displayName,
                             String hint,
                             Object defaultValue,
                             boolean visible,
                             boolean optional)
        Adds a scalar feedback parameter
        Parameters:
        fieldName - Name of the input field
        displayName - display name of the input field
        hint - Fly-over hint for the input field
        defaultValue - Default value for the input field
        visible - Whether the input field is visible or not
        optional - specifies if the feedback parameter is required or not
        See Also:
        XForm

      • createFeedbackParameter

        void createFeedbackParameter​(String fieldName,
                             String displayName,
                             String hint,
                             Object defaultValues,
                             List values,
                             Map dispNames,
                             String displayStyle)
        Creates a feedback parameter that uses a list for the values
        Parameters:
        fieldName - The name of the field
        displayName - Display name
        hint - Fly-over hint for the input field
        defaultValues - Default value of the input field
        values - List of values
        dispNames - Map of display names
        displayStyle - how to display the control
        See Also:
        XForm

      • createFeedbackParameter

        void createFeedbackParameter​(String fieldName,
                             String displayName,
                             String hint,
                             Object defaultValues,
                             List values,
                             Map dispNames,
                             String displayStyle,
                             boolean optional)
        Creates a feedback parameter that uses a list for the values
        Parameters:
        fieldName - The name of the field
        displayName - Display name
        hint - Fly-over hint for the input field
        defaultValues - Default value of the input field
        values - List of values
        dispNames - Map of display names
        displayStyle - how to display the control
        See Also:
        XForm

      • getStatus

        int getStatus()
        Returns:
        the current status of execution

      • getMessages

        List getMessages()
        Returns:
        List of messages saved up during execution. This is used to provide failure feedback to the user.

      • createNewInstance

        String createNewInstance​(boolean persisted)
        Creates a new runtime context that is a child of this instance
        Parameters:
        persisted - Should the runtime data be persisted
        Returns:
        Instance id of the new RuntimeContext

      • createNewInstance

        String createNewInstance​(boolean persisted,
                         Map parameters)
        Creates a new runtime context that is a child of this instance and sets attributes of the runtime data from the parameter Map
        Parameters:
        persisted - Should the runtime data be persisted
        parameters - parameters for the new instance
        Returns:
        Instance id of the new RuntimeContext

      • createNewInstance

        String createNewInstance​(boolean persisted,
                         Map parameters,
                         boolean forceImmediateWrite)
        Creates a new runtime context that is a child of this instance and sets attributes of the runtime data from the parameter Map, and can optionally cause the new instance to be forcibly written to the underlying persistence mechanism.
        Parameters:
        persisted - Should the runtime data be persisted
        parameters - parameters for the new instance
        forceImmediateWrite - if true, will call the new runtime element's forceSave method before returning.
        Returns:
        Instance id of the new RuntimeContext

      • dispose

        void dispose()

      • dispose

        void dispose​(List exceptParameters)

      • setParameterXsl

        void setParameterXsl​(String xsl)
        Sets the xsl file to be used to generate the parameter page for the current component. The parameter should be a full path from the solution root starting with a /, or it should be a path relative to the directory of the current action sequence.
        Parameters:
        xsl - The name of the XSL file

      • setParameterTarget

        void setParameterTarget​(String target)
        Sets the target window that the content will be displayed in. This name is used at the target in an Window.open() javascript call made when the submit button on the parameter page is clicked.
        Parameters:
        target - Window name

      • forceSaveRuntimeData

        void forceSaveRuntimeData()
        Forces the immediate write of runtime data to underlying persistence mechanism. In the case of using Hibernate for the runtime data persistence, this works out to a call to HibernateUtil.flush().

      • getOutputPreference

        int getOutputPreference()
        Gets the output type prefered by the handler. Values are defined in org.pentaho.platform.api.engine.IOutputHandler and are OUTPUT_TYPE_PARAMETERS, OUTPUT_TYPE_CONTENT, or OUTPUT_TYPE_DEFAULT
        Returns:
        Output type

      • setOutputHandler

        void setOutputHandler​(IOutputHandler outputHandler)
        Sets the output handler for the runtime context
        Parameters:
        outputHandler - The output handler

      • setPromptStatus

        void setPromptStatus​(int status)
        Sets the default prompt status PROMPT_NO, PROMPT_WAITING, PROMPT_NOW
        Parameters:
        status -

      • getParameterProviders

        Map getParameterProviders()