/*
* 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();
}