IRuntimeContext.java

/*
 * This program is free software; you can redistribute it and/or modify it under the 
 * terms of the GNU Lesser General Public License, version 2.1 as published by the Free Software 
 * Foundation.
 *
 * You should have received a copy of the GNU Lesser General Public License along with this 
 * program; if not, you can obtain a copy at http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html 
 * or from the Free Software Foundation, Inc., 
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 *
 * Copyright 2005 - 2008 Pentaho Corporation.  All rights reserved.
 *
 * Created on Jun 17, 2005
 *
 */
package org.pentaho.platform.api.engine;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.pentaho.actionsequence.dom.IActionResource;
import org.pentaho.commons.connection.IPentahoStreamSource;
import org.pentaho.platform.api.repository.IContentItem;
import org.pentaho.platform.api.repository.ISolutionRepository;

/**
 * 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
 */
public interface IRuntimeContext extends IAuditable, ILogger {
  /**
   * Unused
   */
  public static final String FEEDBACK_OUTPUT = "feedback-output"; //$NON-NLS-1$

  /**
   * Indicator of action validation failure
   */
  public static final int RUNTIME_CONTEXT_VALIDATE_FAIL = 0;

  /**
   * Indicator of action validation success
   */
  public static final int RUNTIME_CONTEXT_VALIDATE_OK = 1;

  /**
   * Indicates that the parameters for an action were
   * able to be resolved.
   */
  public static final int RUNTIME_CONTEXT_RESOLVE_OK = 2;

  /**
   * Indicates that parameters for an action could not
   * be resolved.
   */
  public static final int RUNTIME_CONTEXT_RESOLVE_FAIL = 9;

  /**
   * When beginning execution of an action sequence, the
   * status starts off as not started.
   */
  public static final int RUNTIME_STATUS_NOT_STARTED = 3;

  /**
   * Indicator that initialization happened successfully
   */
  public static final int RUNTIME_STATUS_INITIALIZE_OK = 4;

  /**
   * Indicator of initialization failure
   */
  public static final int RUNTIME_STATUS_INITIALIZE_FAIL = 8;

  /**
   * As an action sequence begins execution, the status is
   * set to running.
   */
  public static final int RUNTIME_STATUS_RUNNING = 5;

  /**
   * Indicates that the action executed successfully
   */
  public static final int RUNTIME_STATUS_SUCCESS = 6;

  /**
   * Indicator of action failure.
   */
  public static final int RUNTIME_STATUS_FAILURE = 7;

  /**
   * Indicates an invalid instance ID was passed into the execution of an action sequence
   */
  public static final int RUNTIME_STATUS_SETUP_FAIL = 10;

  /**
   * Currently only used as an indicator that BIRT report specification parameters
   * could not be read.
   */
  public static final int PARAMETERS_FAIL = 1;

  /**
   * Currently only used as an indicator that BIRT report specification parameters
   * could be read properly.
   */
  public static final int PARAMETERS_OK = 2;

  /**
   * Indicates that parameters are required by an action, and the parameters aren't
   * available so they need to be prompted for.
   */
  public static final int PARAMETERS_UI_NEEDED = 3;

  /**
   * Indicates that no parameter prompts are pending.
   */
  public static final int PROMPT_NO = 0;

  /**
   * Indicates that parameter prompts are pending.
   */
  public static final int PROMPT_WAITING = 1;

  /**
   * Indicates that we need to prompt immediately for parameters.
   */
  public static final int PROMPT_NOW = 2;

  /**
   * Returns the unique context identifier. The handle is created during
   * construction of the <code>RuntimeContext</code> object, and should be
   * unique down to the date/time of construction. The default form of this
   * as implemented in <tt>RuntimeContext</tt> includes context- plus the
   * hashcode and the date/time.
   * @return the unique handle.
   * @see RuntimeContext
   */
  public String getHandle();

  /**
   * During execution of an action sequence, returns the IActionSequence#getTitle().
   * @return Action sequence title
   * @see IActionSequence#getSequenceTitle()
   */
  public String getActionTitle();

  /** Forces the runtime to stop processing Actions and return to prompt */
  public void promptNow();

  /** Sets the prompt flag but continue processing Actions */
  public void promptNeeded();

  /**
   * Tells if a component is waiting for a prompt
   * 
   * @return true if a prompt is pending
   */
  public boolean isPromptPending();

  /**
   * 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.
   * @return unique instance Id
   */
  public String getInstanceId();

  /**
   * Sets the current action sequence 
   * @param actionSequence The action sequence to validate
   */
  public void setActionSequence(IActionSequence actionSequence);

  public IActionSequence getActionSequence();

  /**
   * Validates the action sequence for consistency
   * @param sequenceName The name of the sequence to validate
   * @throws IllegalStateException
   * @throws ActionSequenceException
   */
  public void validateSequence(String sequenceName, IExecutionListener execListener) throws ActionValidationException;

  /**
   * Executes the action sequence.
   * @param listener The listener to be notified when the sequence finishes
   * @param async Whether the action is synchronous or asynchronous.
   * @return <code>int</code> indicating success
   * @see IRuntimeContext#RUNTIME_STATUS_FAILURE
   * @see IRuntimeContext#RUNTIME_STATUS_SUCCESS
   */
  public void executeSequence(IActionCompleteListener listener, IExecutionListener execListener, boolean async) throws ActionSequenceException;

  /**
   * The Url Factory is used for building URL's that link to this or another application
   * @return the URL Factory
   */
  public IPentahoUrlFactory getUrlFactory();

  /**
   * @return The name of the solution holding the currently executing action sequence
   */
  public String getSolutionName();

  /**
   * @return The path within the solution holding the currently executing action sequence
   */
  public String getSolutionPath();

  /**
   * @return The component in the action seqeuence that's being executed
   */
  public String getCurrentComponentName();

  /**
   * @return The session that started execution of the current action sequence
   */
  public IPentahoSession getSession();

  /**
   * Writes a message to the audit log.
   * @param messageType Message type as defined in <tt>MessageTypes</tt>
   * @param message Message to appear in the log
   * @param value Value of an object to be logged.
   * @param duration For time-tracked execution paths, indicates the duration the task took
   * @see org.pentaho.platform.api.engine.IAuditEntry
   * @see IAuditable
   * @see org.pentaho.core.audit.MessageTypes
   */
  public void audit(String messageType, String message, String value, long duration);

  /**
   * Returns the named input parameter. This will search amongst all the input parameter providers
   * (<tt>IParameterProvider</tt>) in order until it finds the input parameter and returns it.
   * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
   * <code>null</code>
   * @param name The name of the parameter to get
   * @return The parameter
   * @see org.pentaho.platform.api.engine.services.IParameterProvider
   */
  public IActionParameter getInputParameter(String name);

  /**
   * Returns the named output parameter. This will search amongst all the output parameter providers
   * (<tt>IParameterProvider</tt>) in order until it finds the output parameter and returns it.
   * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
   * <code>null</code>
   * @param name The name of the parameter to get
   * @return The requested parameter
   * @see org.pentaho.platform.api.engine.services.IParameterProvider
   */
  public IActionParameter getOutputParameter(String name);

  /**
   * Gets the named resource definition from the executing action sequence.
   * Throws a <tt>NullPointerException</tt> if the resource is not found. This method never returns
   * <code>null</code>
   * @param name The named resource to get
   * @return The resource if it exists.
   * @see IActionSequenceResource
   */
  public IActionSequenceResource getResourceDefintion(String name);

  /**
   * Gets the value of the specified input parameter.
   * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
   * <code>null</code>
   * @param name The named parameter to retrieve
   * @return The <tt>IActionParameter#getValue()</tt>
   * @see IActionParameter
   */
  public Object getInputParameterValue(String name);

  /**
   * Gets the value of the specified input parameter as a <code>String</code>.
   * Throws a <tt>NullPointerException</tt> if the parameter is not found. This method never returns
   * <code>null</code>
   * @param name The named parameter to retrieve
   * @return The <tt>IActionParameter#getStringValue()</tt>
   * @see IActionParameter
   */
  public String getInputParameterStringValue(String name);

  /**
   * Gets the named resource as an <tt>InputStream</tt>. This is just a utility
   * method that interfaces to <tt>ISolutionRepository</tt>
   * @param actionResource The resource to get from the <code>SolutionRepository</code>
   * @return The <code>InputStream</code> that contains the resource.
   * @throws FileNotFoundException 
   * @see ISolutionRepository#getResourceInputStream(IActionResource)
   */
  public InputStream getResourceInputStream(IActionSequenceResource actionResource) throws FileNotFoundException;

  /**
   * Gets the named resource as a <tt>DataSource</tt>. This is just a utility
   * method that interfaces to <tt>ISolutionRepository</tt>
   * @param actionResource The resource to get from the <code>SolutionRepository</tt>
   * @return The <code>DataSource</code>
   * @throws FileNotFoundException 
   * @see ISolutionRepository#getResourceDataSource(IActionResource)
   */
  public IPentahoStreamSource getResourceDataSource(IActionSequenceResource actionResource)
      throws FileNotFoundException;

  /**
   * Gets the named resource as a <tt>Reader</tt>. This is just a utility
   * method that interfaces to <tt>ISolutionRepository</tt>
   * @param actionResource The resource to get from the <code>SolutionRepository</tt>
   * @return The <code>Reader</code>
   * @see ISolutionRepository#getResourceReader(IActionResource)
   */
  public Reader getResourceReader(IActionSequenceResource actionParameter) throws IOException;

  /**
   * Gets the named resource as a <tt>String</tt>. This is just a utility
   * method that interfaces to <tt>ISolutionRepository</tt>
   * @param actionResource The resource to get from the <code>SolutionRepository</tt>
   * @return The <code>String</code>
   * @see ISolutionRepository#getResourceAsString(IActionResource)
   */
  public String getResourceAsString(IActionSequenceResource actionParameter) throws IOException;

  /**
   * Gets the named resource as a <tt>Document</tt>. This is just a utility
   * method that interfaces to <tt>ISolutionRepository</tt>
   * @param actionResource The resource to get from the <code>SolutionRepository</tt>
   * @return The <code>DataSource</code>
   * @see ISolutionRepository#getResourceAsDocument(IActionResource)
   */
  public Document getResourceAsDocument(IActionSequenceResource actionParameter) throws IOException, DocumentException;

  /**
   * Sets the value of a named output parameter
   * @param name The name of the output parameter
   * @param output The value to set the output parameter to
   */
  public void setOutputValue(String name, Object output);

  /**
   * Adds a parameter to the current inputs.  A component can be use this to create parameters for internal use or for new outputs.
   * @param name The name of the temporary parameter
   * @param output The value to set the temporary parameter to
   */
  public void addTempParameter(String name, IActionParameter output);

  /**
   * Returns an output stream for writing. 
   * @param outputName The name of the output
   * @param mimeType The mime type of the output
   * @param extension The file extension of the output
   * @return OutputStream for writing to
   */
  public IContentItem getOutputItem(String outputName, String mimeType, String extension);

  /**
   * Returns an input stream from an input parameter, if the input parameter is
   * a content item.
   * @param parameterName The name of the parameter
   * @return An InputStream from the content item
   */
  public InputStream getInputStream(String parameterName);

  /**
   * Get's the content item associated with the parameter, and returns the content item's
   * datasource
   * @param parameterName The name of the parameter
   * @return The IPentahoStreamSource from the Content Item
   * @see IContentItem#getDataSource()
   */
  public IPentahoStreamSource getDataSource(String parameterName);

  /**
   * @return a <tt>Set</tt> containing all the inputs in the current action.
   */
  @SuppressWarnings("unchecked")
  public Set getInputNames();

  /**
   * @return a <tt>Set</tt> containing the resource names in the action
   */
  @SuppressWarnings("unchecked")
  public Set getResourceNames();

  /**
   * @return a <tt>Set</tt> containing the output names in the current action
   */
  @SuppressWarnings("unchecked")
  public Set getOutputNames();

  /**
   * 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.
   * @param format The string containing possible parameter references
   * @return String with parameters resolved.
   */
  public 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.
   * @param format The string containing possible parameter references
   * @param Resolver for parameters for overriding behavior
   * @return String with parameters resolved.
   */
  public String applyInputsToFormat(String format, IParameterResolver resolver);

  /**
   * Adds an input parameter to the list of all inputs for the action sequence
   * @param name The name of the parameter (the key to the parameter map)
   * @param param The parameter to add
   * @see IActionParameter
   */
  public void addInputParameter(String name, IActionParameter param);

  /**
   * @return true if the current output device allows 
   * user feedback (i.e. parameter input forms)
   */
  public boolean feedbackAllowed();

  /**
   * Interfaces to the current output handler to get the content item
   * that is handling feedback (i.e. parameter input forms)
   * @return the Content Item for user input
   * @see IContentItem
   * @see IOutputHandler
   */
  public IContentItem getFeedbackContentItem();

  /**
   * Interfaces to the current output handler to get the content item
   * that describes the output from this request's component execution.
   * @return The content item for output
   * @see IContentItem
   * @see IOutputHandler
   */
  public IContentItem getOutputContentItem(String mimeType);

  /**
   * Interfaces to the current output handler to get the named content item
   * from this request's component execution.
   * @param outputName the name of the output
   * @return The requested content item
   * @see IContentItem
   * @see IOutputHandler
   */
  public IContentItem getOutputContentItem(String outputName, String mimeType);
  
  /**
   * Returns a url to the passed in content item that can be used to retrieve
   * the content.
   * 
   * @param parameterName
   *            the parameter name of the content
   * @return a string representing the URL or null if the name is not a
   *         content item or is not a valid name.
   */
  public String getContentUrl(IContentItem contentItem);

  /**
   * Generates a parameter acquisition form for required
   * parameters. This writes directly to the output stream
   * provided by the output handler.
   * @throws ActionSequenceException
   * @see IOutputHandler
   */
  public void sendFeedbackForm() throws ActionSequencePromptException;

  public void setCreateFeedbackParameterCallback(ICreateFeedbackParameterCallback callback);
  
  /**
   * @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
   * 
   * @param actionParam
   *            The Action Parameter to use as the model for the prompt
   */
  @Deprecated
  public void createFeedbackParameter(IActionParameter actionParam);

  /**
   * Adds a feedback parameter (essentially a form input field) for a
   * required input. 
   * @param selMap Maps <code>IPentahoResultSet</code> objects to selection objects
   * @param fieldName Name of the form field
   * @param defaultValues default values for the input field
   * @see SelectionMapper
   */
  public void createFeedbackParameter(ISelectionMapper selMap, String fieldName, Object defaultValues);

  /**
   * Adds a feedback parameter (essentially a form input field) for a
   * required input. 
   * @param selMap Maps <code>IPentahoResultSet</code> objects to selection objects
   * @param fieldName Name of the form field
   * @param defaultValues default values for the input field
   * @param optional specifies if the feedback parameter is required or not
   * @see SelectionMapper
   */
  public void createFeedbackParameter(ISelectionMapper selMap, String fieldName, Object defaultValues, boolean optional);

  /**
   * Adds a scalar feedback parameter
   * @param fieldName Name of the input field
   * @param displayName display name of the input field
   * @param hint Fly-over hint for the input field
   * @param defaultValue Default value for the input field
   * @param visible Whether the input field is visible or not
   * @see XForm
   */
  public void createFeedbackParameter(String fieldName, String displayName, String hint, Object defaultValue,
      boolean visible);

  /**
   * Adds a scalar feedback parameter
   * @param fieldName Name of the input field
   * @param displayName display name of the input field
   * @param hint Fly-over hint for the input field
   * @param defaultValue Default value for the input field
   * @param visible Whether the input field is visible or not
   * @param optional specifies if the feedback parameter is required or not
   * @see XForm
   */
  public void createFeedbackParameter(String fieldName, String displayName, String hint, Object defaultValue,
      boolean visible, boolean optional);

  /**
   * Creates a feedback parameter that uses a list for the values
   * @param fieldName The name of the field
   * @param displayName Display name
   * @param hint Fly-over hint for the input field
   * @param defaultValues Default value of the input field
   * @param values List of values 
   * @param dispNames Map of display names
   * @param displayStyle how to display the control
   * @see XForm
   */
  @SuppressWarnings("unchecked")
  public 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
   * @param fieldName The name of the field
   * @param displayName Display name
   * @param hint Fly-over hint for the input field
   * @param defaultValues Default value of the input field
   * @param values List of values 
   * @param dispNames Map of display names
   * @param displayStyle how to display the control
   * @parm optional specifies if the feedback parameter is required or not
   * @see XForm
   */
  @SuppressWarnings("unchecked")
  public void createFeedbackParameter(String fieldName, String displayName, String hint, Object defaultValues,
      List values, Map dispNames, String displayStyle, boolean optional);

  /**
   * @return the current status of execution
   */
  public int getStatus();

  /**
   * @return List of messages saved up during execution. This is used to provide
   * failure feedback to the user.
   */
  @SuppressWarnings("unchecked")
  public List getMessages();

  /**
   * Creates a new runtime context that is a child of this instance
   * 
   * @param persisted
   *            Should the runtime data be persisted
   * @return Instance id of the new RuntimeContext
   */
  public String createNewInstance(boolean persisted);

  /**
   * Creates a new runtime context that is a child of this instance and sets
   * attributes of the runtime data from the parameter Map
   * 
   * @param persisted
   *            Should the runtime data be persisted
   * @param parameters
   *            parameters for the new instance
   * @return Instance id of the new RuntimeContext
   */
  @SuppressWarnings("unchecked")
  public 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, and can
   * optionally cause the new instance to be forcibly written to the
   * underlying persistence mechanism.
   * 
   * @param persisted
   *            Should the runtime data be persisted
   * @param parameters
   *            parameters for the new instance
   * @param forceImmediateWrite
   *            if true, will call the new runtime element's forceSave method
   *            before returning.
   * @return Instance id of the new RuntimeContext
   */
  @SuppressWarnings("unchecked")
  public String createNewInstance(boolean persisted, Map parameters, boolean forceImmediateWrite);

  public void dispose();

  @SuppressWarnings("unchecked")
  public void dispose(List exceptParameters);

  /**
   * 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.
   * 
   * @param xsl
   *            The name of the XSL file
   */
  public void setParameterXsl(String xsl);

  /**
   * 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.
   * 
   * @param target
   *            Window name
   */
  public void setParameterTarget(String target);

  /**
   * 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().
   */
  public void forceSaveRuntimeData();

  /**
   * 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
   * 
   * @return Output type
   */
  public int getOutputPreference();

  /**
   * Sets the output handler for the runtime context
   * 
   * @param outputHandler
   *            The output handler
   * 
   */
  public void setOutputHandler(IOutputHandler outputHandler);

  /**
   * Sets the default prompt status PROMPT_NO, PROMPT_WAITING, PROMPT_NOW
   * @param status
   */
  public void setPromptStatus(int status);

  public IParameterManager getParameterManager();

  @SuppressWarnings("unchecked")
  public Map getParameterProviders();

  
}