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 Details

    • FEEDBACK_OUTPUT

      static final String FEEDBACK_OUTPUT
      Unused
      See Also:

    • RUNTIME_CONTEXT_VALIDATE_FAIL

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

    • RUNTIME_CONTEXT_VALIDATE_OK

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

    • 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:

    • RUNTIME_CONTEXT_RESOLVE_FAIL

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

    • 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:

    • RUNTIME_STATUS_INITIALIZE_OK

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

    • RUNTIME_STATUS_INITIALIZE_FAIL

      static final int RUNTIME_STATUS_INITIALIZE_FAIL
      Indicator of initialization failure
      See Also:

    • RUNTIME_STATUS_RUNNING

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

    • RUNTIME_STATUS_SUCCESS

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

    • RUNTIME_STATUS_FAILURE

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

    • 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:

    • PARAMETERS_FAIL

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

    • PARAMETERS_OK

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

    • 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:

    • PROMPT_NO

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

    • PROMPT_WAITING

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

    • PROMPT_NOW

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

  • Method Details

    • 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

    • getActionSequence

      IActionSequence getActionSequence()

    • validateSequence

      void validateSequence(String sequenceName, IExecutionListener execListener) throws ActionValidationException
      Validates the action sequence for consistency
      Parameters:
      sequenceName - The name of the sequence to validate
      Throws:
      IllegalStateException
      ActionSequenceException
      ActionValidationException

    • executeSequence

      void executeSequence(IActionCompleteListener listener, IExecutionListener execListener, boolean async) throws ActionSequenceException
      Executes the action sequence.
      Parameters:
      listener - The listener to be notified when the sequence finishes
      async - Whether the action is synchronous or asynchronous.
      Throws:
      ActionSequenceException
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • getResourceInputStream

      InputStream getResourceInputStream(IActionSequenceResource actionResource) throws FileNotFoundException
      Gets the named resource as an InputStream.
      Parameters:
      actionResource - The resource to get from the SolutionRepository
      Returns:
      The InputStream that contains the resource.
      Throws:
      FileNotFoundException

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • sendFeedbackForm

      void sendFeedbackForm() throws ActionSequencePromptException
      Generates a parameter acquisition form for required parameters. This writes directly to the output stream provided by the output handler.
      Throws:
      ActionSequenceException
      ActionSequencePromptException
      See Also:

    • setCreateFeedbackParameterCallback

      void setCreateFeedbackParameterCallback(ICreateFeedbackParameterCallback callback)

    • 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 -

    • getParameterManager

      IParameterManager getParameterManager()

    • getParameterProviders

      Map getParameterProviders()