/*******************************************************************************
 * Copyright (c) 2004 Actuate Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *  Actuate Corporation  - initial API and implementation
 *******************************************************************************/

package org.eclipse.birt.report.engine.api;

import java.io.InputStream;

import org.eclipse.birt.report.engine.api.impl.ReportEngineHelper;
import org.eclipse.birt.report.model.api.DesignElementHandle;

/**
 * A report engine provides an entry point for reporting functionalities. It is
 * where the report generation and rendering process are globally customized. 
 * It is also the place where engine statistics are collected. Through report 
 * engine, reports can be generated and rendered to different output formats.
 * Queries can also be executed for preview purpose without involving a full 
 * report generation. 
 * <p>
 * Engine supports running different types of tasks. Example tasks include running 
 * a report design to generate a report instance file, rendering a report instance to 
 * output format, running a report directly to output, running a dataset for preview,
 * seaching a report, etc.
 */

public class ReportEngine {

	/**
	 * engine configuration object
	 */
	protected EngineConfig config;

	/**
	 * A helper object to carry out most ReportEngine jobs
	 */
	protected ReportEngineHelper helper;
	
	/**
	 * Constructor. If config is null, engine derives BIRT_HOME from the location of
	 * the engine jar file, and derives data driver directory as $BIRT_HOME/drivers.
	 * For a simple report with no images and links, engine will run without complaining.
	 * If the report has image/chart defined, the engine has to be configured with 
	 * relevant image and chart handlers.  
	 * 
	 * @param config an engine configuration object used to configure the engine 
	 */
	public ReportEngine(EngineConfig config)
	{	
		this.config = config;	
		this.helper = new ReportEngineHelper(this);
	}
	
	/**
	 * returns the engine configuration object
	 * 
	 * @return the engine configuration object
	 */
	public EngineConfig getConfig()
	{
		return config;
	}

	/**
	 * opens a report design file and creates a report design runnable. From the ReportRunnable
	 * object, embedded images and parameter definitions can be retrieved. Constructing
	 * an engine task requires a report design runnable object.  
	 * 
	 * @param designName the full path of the report design file
	 * @return a report design runnable object
	 * @throws EngineException throwed when the input file does not exist, or the 
	 * file is invalid
	 */
	public IReportRunnable openReportDesign(String designName) throws EngineException
	{
		return helper.openReportDesign(designName);
	}
	
	/**
	 * opens a report design stream and creates a report design runnable. From the ReportRunnable
	 * object, embedded images and parameter definitions can be retrieved. Constructing
	 * an engine task requires a report design runnableobject. 
	 * 
	 * @param designStream the report design input stream  
	 * @return a report design runnable object
	 * @throws EngineException throwed when the input stream is null, or the 
	 * stream does not yield a valid report design
	 */
	public IReportRunnable openReportDesign(InputStream designStream) throws EngineException
	{
		return helper.openReportDesign(designStream);
	}

	/**
	 * creates a report design runnable based on a report design handle, from ehich
	 * embedded images and parameter definitions can be retrieved.
	 * 
	 * @param designHandle the report design handle created by the design engine  
	 * @return a report design runnable object
	 * @throws EngineException throwed when the input stream is null, or the 
	 * stream does not yield a valid report design
	 */
	public IReportRunnable openReportDesign(DesignElementHandle designHandle) throws EngineException
	{
		return helper.openReportDesign(designHandle);
	}
	
	/**
	 * creates an engine task for running and rendering report directly to
	 * output format 
	 * 
	 * @param reportRunnable the runnable report design object
	 * @return a run and render report task 
	 */
	public IRunAndRenderTask createRunAndRenderTask(IReportRunnable reportRunnable)
	{
		return helper.createRunAndRenderTask(reportRunnable);
	}
	
	/**
	 * creates an engine task for obtaining report parameter definitions 
	 * 
	 * @param reportRunnable the runnable report design object
	 * @return a run and render report task 
	 */
	public IGetParameterDefinitionTask createGetParameterDefinitionTask(IReportRunnable reportRunnable)
	{
		return helper.createGetParameterDefinitionTask(reportRunnable);
	}
	/**
	 * returns all supported output formats through BIRT engine emitter extensions
	 * 
	 * @return all supported output formats through BIRT engine emitter extensions  
	 */
	public String[] getSupportedFormats()
	{
		return helper.getSupportedFormats();
	}
	
	/**
	 * the MIME type for the specific formatted supported by the extension. 
	 * 
	 * @param format the output format
	 * @param extensionID the extension ID, which could be null if only one plugin supports
	 * the output format
	 * @return the MIME type for the specific formatted supported by the extension. 
	 */
	public String getMIMEType(String format)
	{
		return helper.getMIMEType(format);
	}
	
	/**
	 * opens a report document file and creates a report instance handle. From the report instance
	 * object, report can be exported to different output formats.  
	 * 
	 * @param reportDocName report document file name
	 * @return a report instance handle
	 * @throws EngineException throwed when the file does not exist or the file is not a valid 
	 * report document 
	 */
	/*public ReportDocument openReportDocument(String reportDocName) throws EngineException
	{
		return null;
	}*/
	
	/**
	 * shuts down the report engine
	 */
	public void destroy() throws EngineException
	{
	}
}

@@ -4028,32 +4028,34 @@
 rt design%0A%09 */%0A%09
+/*
 public IReportRu
@@ -4184,24 +4184,26 @@
 nHandle);%0A%09%7D
+*/
 %0A%09%0A%09/**%0A%09 * 

Remove the function that opens report based on a report design handle to avoid viewer problems.