IPreparedComponent.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 Oct 12, 2005 
 * @author James Dixon
 */

package org.pentaho.platform.api.data;

import java.util.Map;

import org.pentaho.commons.connection.IDisposable;
import org.pentaho.commons.connection.IPentahoConnection;
import org.pentaho.commons.connection.IPentahoResultSet;
import org.pentaho.platform.api.engine.IComponent;

/**
 * The prepared component interface extends component, 
 * allowing components to go into a prepared state vs. execute
 * state.  These components may place themselves as an output
 * parameter, and then be used later in the action-sequence
 * for execution of prepared statements / etc.
 * 
 * @author Will Gorman
 * 
 * @see MDXBaseComponent
 * @see SQLBaseComponent
 * @see IPentahoResultSet
 * 
 */
public interface IPreparedComponent extends IComponent, IDisposable {

  /** 
   * this term may appear when resolving parameters 
   * "{PREPARELATER:PARAM_NAME}"
   */
  public static final String PREPARE_LATER_PREFIX = "PREPARELATER"; //$NON-NLS-1$

  /**
   * this is an intermediate term used when resolving parameters 
   * in the executePrepared call
   */
  public static final String PREPARE_LATER_INTER_PREFIX = "PREPARELATER_INTER"; //$NON-NLS-1$

  /**
   * The name of the output.  If this appears as an output of
   * an IPreparedComponent the component should alter its 
   * behavior and go into prepared mode.
   */
  public static final String PREPARED_COMPONENT_NAME = "prepared_component"; //$NON-NLS-1$

  /**
   * The type of the output.  If this appears in an output of an
   * IPreparedComponent the component should alter its behavior
   * and go into prepared mode. 
   */
  public static final String PREPARED_OUTPUT_TYPE = "prepared_component"; //$NON-NLS-1$

  /**
   * A placeholder for template strings and potential prepared lists, so
   * template fields can be replaced on the fly vs. during initial setup
   * of a prepared statement
   */
  public static final String PREPARE_LATER_PLACEHOLDER = "prepare-later-placeholder"; //$NON-NLS-1$

  /**
   * executes a prepared method that returns a result set
   * executePrepared looks up any "PREPARELATER" params
   * in the preparedParams map.
   *
   * @param preparedParams a map of possible parameters.
   * @return result set
   */
  @SuppressWarnings("unchecked")
  public IPentahoResultSet executePrepared(Map preparedParams);

  /**
   * exposes the connection object for others to use.  The connection object in a prepared
   * component is not closed until parameters are disposed at the end of an action sequence
   * execution.
   * 
   * Note:  getConnection was already in use when naming this method.
   * 
   * @return connection object
   */
  public IPentahoConnection shareConnection();

  /**
   * Disposes of resources held by the prepared component
   */
  public void dispose();

}