deploy/engine.html - gerrit/www.eclipse.org/birt - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
 <html>

 <head>
 <title>Deploying BIRT</title>
 <link rel="stylesheet" href="../style/compose.css" type="text/css"/>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </head>

 <body>

 <p class="head">Integrating BIRT</p>
 <p class="subhead">Using the Report Engine</p>

 <h1>Background</h1>

 The BIRT Report Engine API allows you to integrate the run-time part of BIRT
 into your application. The Release 1.0.1 engine supports the following operations:

 <ul>
 <li>Discover the set of parameters defined for a report.
 <li>Get the default values for parameters.<li>Run a report to produce an HTML or PDF output.
 <li>Fetch an image or chart for a report.
 </ul>

 <p>The report engine supports extensions for custom report items, and for custom
 output formats. Extensions are discussed elsewhere. This article focus on how
 your application integrates with the report engine.
 </p>

 <h1>Installing the API</h1>

 The first step is to download, install, and configure the BIRT engine. The
 engine is more than just a simple JAR file; it also includes a set of extensions
 (plugins), and a set of data drivers.

 <h2>Engine Download</h2>
 <p> The standalone <a href="http://download.eclipse.org/birt/downloads/">BIRT engine</a> is now available for download.
 Within this download are several examples on how to use the Report Engine, Chart Engine and
 the Viewer.<br>
 In addition the Engine is still available as part of the full BIRT install and
 is located in the <code>eclipse/plugins/org.eclipse.birt.report.viewer_1.0.1/birt</code>
 directory.</p>

 <h2>Engine Source</h2>
 <p>If you prefer to work directly with the BIRT source code, the Engine API is
 in the <code>org.eclipse.birt.report.engine project</code> within Eclipse CVS in
 <code><a href="http://dev.eclipse.org/viewcvs/index.cgi/source/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/api/?cvsroot=BIRT_Project">
 source/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/api</a></code>.</p>

 <h2>Javadoc</h2>

 <p>This article provides an overview of the engine. To do actual development,
 consult the Engine Javadoc.</p>

 <h2>Installing the Engine</h2>

 <h2>Configuring JDBC Drivers</h2>
 <p>You must configure the engine to include any JDBC drivers that you need.</p>

 <p class="caution"><span class="caution-head">Note:</span> If you use
 the engine installed as part of the viewer plugin, then you can skip this step
 if you've already installed the driver using the BIRT Report Designer. Follow
 these steps only if you install a new copy of the engine.</p>

 <p>The report engine uses the Eclipse plugin mechanism for managing extensions.
 One of those extensions is a bridge between BIRT and JDBC implemented using the
 BIRT Open Data Access (ODA) framework. JDBC drivers are defined in the <code>plugin.xml</code>
 file for the JDBC extension: <code><i>ENGINE-ROOT</i>/plugins/org.eclipse.birt.report.data.oda.jdbc_1.0.1/plugin.xml</code>.
 Use any text editor to edit the configuration file. Add an entry such as the one
 shown in bold below.</p>

 <pre class="code-block">&lt;runtime&gt;
   &lt;library name=&quot;oda-jdbc.jar&quot;&gt;
     &lt;export name=&quot;*&quot;/&gt;
   &lt;/library&gt;
   <b>&lt;library name=&quot;lib/<i>driver_name</i>.jar&quot;&gt;
     &lt;export name=&quot;*&quot;/&gt;
   &lt;/library&gt;</b>
 &lt;/runtime&gt;
 </pre>

   <p>Where <i>driver_name</i> is the name of your JDBC driver JAR. Add another <code>&lt;LibraryName></code> element for each
 additional JDBC driver JAR file that might be needed. Put the library itself
   into the lib directory: <code><i>ENGINE-ROOT</i>/plugins/org.eclipse.birt.report.data.oda.jdbc_1.0.1/lib.</code></p>
   <p>More information about the ODA runtime driver extension point schema can be
   found in CVS BIRT source tree: <code>org.eclipse.birt.data.oda/schema/odaDriverRuntime.exsd</code>.
   Use the Eclipse PDE Tools to see its reference document.</p>

 <h1>API Overview</h1>

 <p>The following are the key steps to use the API, identifying the classes and
 interfaces you use for each step.</p>

 <ol>
   <li>Create an instance of <code>EngineConfig</code> to set options for the report engine.</li>
   <li>Create an instance of the <code>ReportEngine</code> class. You can use this object to
   perform multiple tasks.</li>
   <li>Open a report design using one of the <code>openReport(&nbsp;)</code> methods of <code>ReportEngine</code>.</li>
   <li>Obtain information about report parameters using
   <code>IGetParameterDefinitionTask</code>.</li>
   <li>Run and render a report using <code>IRunAndRenderReportTask</code>.</li>
   <li>Repeat steps 3-5 for the next report.</li>
   <li>When done, call <code>destroy(&nbsp;)</code> on your engine instance.</li>
 </ol>

 <p>The following sections describe the primary Engine classes in detail. The
 Engine API includes a number of secondary helper classes referenced within each
 description.</p>

 <h1><code>EngineConfig</code> Class</h1>

 <p>Use the <code>EngineConfig</code> class to set global options for the report engine as a
 whole. Use it to specify the location of engine plugins, the location of data
 drivers, and to add application-wide scriptable objects. At a minimum, you'll
 want to set the location of the engine installation using the <code>setEngineHome(&nbsp;)</code>
 method.</p>
 <pre class="code-block">EngineConfig config = new EngineConfig( );
 config.setEngineHome( &quot;put engine path here&quot; );</pre>


 <p class="caution"><span class="caution-head">Note:</span> If you are using
 the engine located in the full BIRT install:
 /eclipse/plugins/org.eclipse.birt.report.viewer_1.0.1/birt.</p>

 <p class="caution"><span class="caution-head">Release 2.0 M3  Note:</span> Please use the
 birt-runtime download when setting the engine home.  The engine home should be set to
 installedlocation/birt-runtime-x_y_z/Report Engine
 </p>

 <h2>Emitter Configuration</h2>

 <p>An &quot;emitter&quot; is the component of the report engine that produces output. BIRT provides two emitters: HTML and PDF. You'll want to configure the HTML
 emitter to manage images and links. BIRT supports three kinds of images:</p>

 <ul>
   <li>Images referenced using a URL</li>
   <li>Embedded images</li>
   <li>Images created to represent charts</li>
 </ul>

 <p>Your application must have a policy for handling images in HTML. URL-based
 images are usually no problem. However, you'll need to handle the other two. The
 <code>IHTMLImageHandler</code> interface defines the policy. The BIRT Engine provides two
 default implementations:</p>

 <ul>
   <li><code>HTMLCompleteImageHandler</code>: used to write images to disk when rendering a
   report to produce an HTML file on disk.</li>
   <li><code>HTMLServerImageHandler</code>: used to handle images for an engine running in an
   app server. This class is used by the BIRT web app.</li>
 </ul>

 <p>You can also create your own implementation of <code>IHTMLImageHandler</code> if the above
 don't meet your needs.</p>

 <p>Here's how to create an emitter configuration and set the image handler:</p>

 <pre class="code-block">EngineConfig config = new EngineConfig( );

 // Create the emitter configuration.

 HTMLEmitterConfig hc = new HTMLEmitterConfig( );

 // Use the &quot;HTML complete&quot; image handler to write the files to disk.

 HTMLCompleteImageHandler imageHandler = new HTMLCompleteImageHandler( );
 hc.setImageHandler( imageHandler );

 // Associate the configuration with the HTML output format.

 config.setEmitterConfiguration( HTMLRenderOption.OUTPUT_FORMAT_HTML, hc );</pre>


 <h1><code>ReportEngine</code> Class</h1>

 <p>The <code>ReportEngine</code>&nbsp; class represents the BIRT Report Engine. There is a significant cost associated with creating an engine instance, due
 primarily to the cost of loading extensions. Therefore, each application should
 create create just one <code>ReportEngine</code> instance and use it to run multiple reports.</p>
 <p>The report engine is created through its constructor that takes an
 <code>EngineConfig</code> object as argument. The configuration object can be null, which
 means to use the default engine configuration. After using the engine, call
 <code>destroy(&nbsp;)</code> to do clean up work, which includes unloading the extensions.</p>

 <pre class="code-block">EngineConfig config = new EngineConfig( );
 ...
 ReportEngine engine = new ReportEngine( config );

 // Run reports, etc.
 ...

 // Shut down the engine.

 try
 {
     engine.destroy( );
 }
 catch ( EngineException e1 )
 {
     // Ignore
 }</pre>


 <h1><code>IReportRunnable</code> Class</h1>


 <p>BIRT reports are stored as an XML file. To work with the report in the
 engine, you must first load the report using one of the <code>openDesign(&nbsp;)</code> methods in
 the <code>ReportEngine</code> class. These methods return an
 <code>IReportRunnable</code> instance that represents the engine's view of the
 report design. </p>

 <pre class="code-block">IReportRunnable report = engine.openReportDesign( name );</pre>

 <p>Use this object to obtain parameter data or run the report. The class
 provides methods for getting report properties such as the title, author and so
 on. It also provides methods for getting images embedded (stored) within the
 report design. If your application requires more information about the design, you can
 obtain a Design Engine report handle, then use the BIRT <a href="de-api.html">
 Design Engine API</a> to traverse though the report design.</p>

 <h1><code>IEngineTask</code> Abstract Base Class</h1>

 <p>BIRT reports support scripting. Operations that execute scripts require a
 scripting context. Report operations also require a locale. BIRT Engine tasks
 provide the framework for managing the scripting context, report locales and so
 on. In general, if an operation requires neither a script context nor a locale,
 it will appear as a method on the engine or the report design. However, if the
 operation does
 require these items; then the operation is represented by a task class.</p>

 <p>For example, opening a design file or retrieving an image in the design file
 do not require setting up a scripting context. Other operations, such as
 retrieving default parameters, retrieving a dynamic selection list, and running
 and rendering a report, all support scripting, require a scripting context, and
 are represented as tasks.</p>

 <p>Create tasks using the factory methods on the <code>ReportEngine</code> class. Each task
 takes a report runnable (design), a scripting context, a locale, and other
 information.</p>

 <h1><code>IGetParameterDefinitionTask</code> Class</h1>

 <p>Use this task to obtain information about parameters. Parameter default
 values are expressions, and so a scripting context (represented by the task) is
 required. Parameter definitions provide access to the parameter
 definition information that the report designer entered at design time. If a
 parameter has custom XML or user-defined properties defined, then these are also
 available. Applications typically use the standard and custom properties to
 create a parameter UI that prompts the user for parameter values. Parameters can
 be organized into groups. Your application has the choice of retrieving the
 parameters organized by group (as they should be displayed to the user), or in
 ungrouped form (useful for creating a programmatic interface.)</p>

 <p>The <code>IParameterGroupDefn</code> and <code>IScalarParameterDefn</code>
 interfaces provide
 information about parameter groups and individual parameters.</p>

 <pre class="code-block">// Get the parameter definitions

 IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( report );
 Collection params = task.getParameterDefns( true );

 // The collection contains parameters and parameter groups.

 Iterator iter = params.iterator( );
 while ( iter.hasNext( ) )
 {
     IParameterDefnBase param = (IParameterDefnBase) iter.next( );
     if ( param instanceof IParameterGroupDefn )
     {
         IParameterGroupDefn group = (IParameterGroupDefn) param;

         // Do something with the parameter group.
         // Iterate over group contents.

         Iterator i2 = group.getContents( ).iterator( );
         while ( iter.hasNext( ) )
         {
             IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );

             // Do something with a parameter within a group.
     }
     else
     {
         IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );

         // Do something with a top-level parameter.
     }
 }</pre>

 <p>Use the <code>IGetParameterDefinitionTask</code> class to evaluate the default value for a parameter. The parameter
 default value is an expression, and the task provides the required execution
 context.</p>

 <pre class="code-block">IScalarParameterDefn param = ...;
 IGetParameterDefinitionTask task = ...;
 Object value = task.getDefaultValue( param );</pre>

 <h1><code>IRunAndRenderReportTask</code> Class</h1>
 <p>Use this task to run a report and
 convert it to either HTML or PDF. This task does not save the report document
 itself to disk. Create a new task for each report that you run.</p>

 <p class="caution"><span class="caution-head">Release 1.0.1  Note:</span> BIRT 1.0
 supports the ability to run a report and to directly produce HTML or PDF. Later
 versions will allow the ability to save the report document to disk for later
 use. At that time, BIRT will provide other tasks to run the report, then later
 to render a saved report document.
 </p>

 <p>Reports may take parameters. The <code>IRunAndRenderReportTask</code> takes parameter
 values as a <code>HashMap</code>. The <code>IRunAndRenderReportTask</code> provides
 the <code>validateParameters(&nbsp;)</code> method to validate the parameter values before you run
 the report.</p>

 <p>You can produce HTML or PDF output. Each format offers a distinct set of
 options. These options are set through the <code>HTMLRenderOption</code> and
 <code>PDFRenderOption</code>
 classes. Create the one for the output format you desire, set the options you
 need, and pass the instance to <code>IRunAndRenderReportTask</code> before running the
 report.</p>

 <pre class="code-block">// Create the task

 IRunAndRenderTask task = engine.createRunAndRenderTask( report );

 // Set up options for HTML output.

 HTMLRenderOption options = new HTMLRenderOption( );
 options.setOutputFormat( HTMLRenderOption.OUTPUT_FORMAT_HTML );
 options.setOutputFileName( outputName );
 task.setRenderOption( options );

 // Set parameter values using a HashMap. Parameters are name/value pairs.
 // The values must be Java objects of the correct type.

 HashMap params = new HashMap( );
 ...
 task.setParameterValues( params );

 // Run the report.

 task.run( );</pre>

 <h1>Example Application</h1>

 The best way to learn about the engine API is to look at a sample application.
 This sample is a command-line application that takes a report design and can
 either print parameter information about the design (-i option), or run and render the
 report (-h option for HTML, -p option for PDF). When running, the utility takes a set of parameter values, and accepts
 an output format. The application illustrates the major steps you should follow
 in your own application.<p><a href="RunReport.java">Download the sample
 application</a>.</p>
 <a href="birtengine.zip">Download the sample
 application Ant project</a>.
 The Ant project has a readme.txt explaining which files need to be copied.
 <p>To run a <a href="test.rptdesign">sample report </a>to HTML, setting the
 &quot;sample&quot; parameter to the value &quot;Hello&quot;:</p>
 <pre class="code-block">java RunReport test.rptdesign -h sample=Hello</pre>
 <p>To get information about the report properties and parameter definitions:</p>
 <pre class="code-block">java RunReport test.rptdesign -i</pre>


 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
	<html>

	<head>
	<title>Deploying BIRT</title>
	<link rel="stylesheet" href="../style/compose.css" type="text/css"/>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	</head>

	<body>

	<p class="head">Integrating BIRT</p>
	<p class="subhead">Using the Report Engine</p>

	<h1>Background</h1>

	The BIRT Report Engine API allows you to integrate the run-time part of BIRT
	into your application. The Release 1.0.1 engine supports the following operations:

	<ul>
	<li>Discover the set of parameters defined for a report.
	<li>Get the default values for parameters.<li>Run a report to produce an HTML or PDF output.
	<li>Fetch an image or chart for a report.
	</ul>

	<p>The report engine supports extensions for custom report items, and for custom
	output formats. Extensions are discussed elsewhere. This article focus on how
	your application integrates with the report engine.
	</p>

	<h1>Installing the API</h1>

	The first step is to download, install, and configure the BIRT engine. The
	engine is more than just a simple JAR file; it also includes a set of extensions
	(plugins), and a set of data drivers.

	<h2>Engine Download</h2>
	<p> The standalone <a href="http://download.eclipse.org/birt/downloads/">BIRT engine</a> is now available for download.
	Within this download are several examples on how to use the Report Engine, Chart Engine and
	the Viewer.<br>
	In addition the Engine is still available as part of the full BIRT install and
	is located in the <code>eclipse/plugins/org.eclipse.birt.report.viewer_1.0.1/birt</code>
	directory.</p>

	<h2>Engine Source</h2>
	<p>If you prefer to work directly with the BIRT source code, the Engine API is
	in the <code>org.eclipse.birt.report.engine project</code> within Eclipse CVS in
	<code><a href="http://dev.eclipse.org/viewcvs/index.cgi/source/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/api/?cvsroot=BIRT_Project">
	source/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/api</a></code>.</p>

	<h2>Javadoc</h2>

	<p>This article provides an overview of the engine. To do actual development,
	consult the Engine Javadoc.</p>

	<h2>Installing the Engine</h2>

	<h2>Configuring JDBC Drivers</h2>
	<p>You must configure the engine to include any JDBC drivers that you need.</p>

	<p class="caution"><span class="caution-head">Note:</span> If you use
	the engine installed as part of the viewer plugin, then you can skip this step
	if you've already installed the driver using the BIRT Report Designer. Follow
	these steps only if you install a new copy of the engine.</p>

	<p>The report engine uses the Eclipse plugin mechanism for managing extensions.
	One of those extensions is a bridge between BIRT and JDBC implemented using the
	BIRT Open Data Access (ODA) framework. JDBC drivers are defined in the <code>plugin.xml</code>
	file for the JDBC extension: <code><i>ENGINE-ROOT</i>/plugins/org.eclipse.birt.report.data.oda.jdbc_1.0.1/plugin.xml</code>.
	Use any text editor to edit the configuration file. Add an entry such as the one
	shown in bold below.</p>

	<pre class="code-block"><runtime>
	<library name="oda-jdbc.jar">
	<export name="*"/>
	</library>
	<b><library name="lib/<i>driver_name</i>.jar">
	<export name="*"/>
	</library></b>
	</runtime>
	</pre>

	<p>Where <i>driver_name</i> is the name of your JDBC driver JAR. Add another <code><LibraryName></code> element for each
	additional JDBC driver JAR file that might be needed. Put the library itself
	into the lib directory: <code><i>ENGINE-ROOT</i>/plugins/org.eclipse.birt.report.data.oda.jdbc_1.0.1/lib.</code></p>
	<p>More information about the ODA runtime driver extension point schema can be
	found in CVS BIRT source tree: <code>org.eclipse.birt.data.oda/schema/odaDriverRuntime.exsd</code>.
	Use the Eclipse PDE Tools to see its reference document.</p>

	<h1>API Overview</h1>

	<p>The following are the key steps to use the API, identifying the classes and
	interfaces you use for each step.</p>

	<ol>
	<li>Create an instance of <code>EngineConfig</code> to set options for the report engine.</li>
	<li>Create an instance of the <code>ReportEngine</code> class. You can use this object to
	perform multiple tasks.</li>
	<li>Open a report design using one of the <code>openReport( )</code> methods of <code>ReportEngine</code>.</li>
	<li>Obtain information about report parameters using
	<code>IGetParameterDefinitionTask</code>.</li>
	<li>Run and render a report using <code>IRunAndRenderReportTask</code>.</li>
	<li>Repeat steps 3-5 for the next report.</li>
	<li>When done, call <code>destroy( )</code> on your engine instance.</li>
	</ol>

	<p>The following sections describe the primary Engine classes in detail. The
	Engine API includes a number of secondary helper classes referenced within each
	description.</p>

	<h1><code>EngineConfig</code> Class</h1>

	<p>Use the <code>EngineConfig</code> class to set global options for the report engine as a
	whole. Use it to specify the location of engine plugins, the location of data
	drivers, and to add application-wide scriptable objects. At a minimum, you'll
	want to set the location of the engine installation using the <code>setEngineHome( )</code>
	method.</p>
	<pre class="code-block">EngineConfig config = new EngineConfig( );
	config.setEngineHome( "put engine path here" );</pre>


	<p class="caution"><span class="caution-head">Note:</span> If you are using
	the engine located in the full BIRT install:
	/eclipse/plugins/org.eclipse.birt.report.viewer_1.0.1/birt.</p>

	<p class="caution"><span class="caution-head">Release 2.0 M3 Note:</span> Please use the
	birt-runtime download when setting the engine home. The engine home should be set to
	installedlocation/birt-runtime-x_y_z/Report Engine
	</p>

	<h2>Emitter Configuration</h2>

	<p>An "emitter" is the component of the report engine that produces output. BIRT provides two emitters: HTML and PDF. You'll want to configure the HTML
	emitter to manage images and links. BIRT supports three kinds of images:</p>

	<ul>
	<li>Images referenced using a URL</li>
	<li>Embedded images</li>
	<li>Images created to represent charts</li>
	</ul>

	<p>Your application must have a policy for handling images in HTML. URL-based
	images are usually no problem. However, you'll need to handle the other two. The
	<code>IHTMLImageHandler</code> interface defines the policy. The BIRT Engine provides two
	default implementations:</p>

	<ul>
	<li><code>HTMLCompleteImageHandler</code>: used to write images to disk when rendering a
	report to produce an HTML file on disk.</li>
	<li><code>HTMLServerImageHandler</code>: used to handle images for an engine running in an
	app server. This class is used by the BIRT web app.</li>
	</ul>

	<p>You can also create your own implementation of <code>IHTMLImageHandler</code> if the above
	don't meet your needs.</p>

	<p>Here's how to create an emitter configuration and set the image handler:</p>

	<pre class="code-block">EngineConfig config = new EngineConfig( );

	// Create the emitter configuration.

	HTMLEmitterConfig hc = new HTMLEmitterConfig( );

	// Use the "HTML complete" image handler to write the files to disk.

	HTMLCompleteImageHandler imageHandler = new HTMLCompleteImageHandler( );
	hc.setImageHandler( imageHandler );

	// Associate the configuration with the HTML output format.

	config.setEmitterConfiguration( HTMLRenderOption.OUTPUT_FORMAT_HTML, hc );</pre>


	<h1><code>ReportEngine</code> Class</h1>

	<p>The <code>ReportEngine</code>  class represents the BIRT Report Engine. There is a significant cost associated with creating an engine instance, due
	primarily to the cost of loading extensions. Therefore, each application should
	create create just one <code>ReportEngine</code> instance and use it to run multiple reports.</p>
	<p>The report engine is created through its constructor that takes an
	<code>EngineConfig</code> object as argument. The configuration object can be null, which
	means to use the default engine configuration. After using the engine, call
	<code>destroy( )</code> to do clean up work, which includes unloading the extensions.</p>

	<pre class="code-block">EngineConfig config = new EngineConfig( );
	...
	ReportEngine engine = new ReportEngine( config );

	// Run reports, etc.
	...

	// Shut down the engine.

	try
	{
	engine.destroy( );
	}
	catch ( EngineException e1 )
	{
	// Ignore
	}</pre>


	<h1><code>IReportRunnable</code> Class</h1>


	<p>BIRT reports are stored as an XML file. To work with the report in the
	engine, you must first load the report using one of the <code>openDesign( )</code> methods in
	the <code>ReportEngine</code> class. These methods return an
	<code>IReportRunnable</code> instance that represents the engine's view of the
	report design. </p>

	<pre class="code-block">IReportRunnable report = engine.openReportDesign( name );</pre>

	<p>Use this object to obtain parameter data or run the report. The class
	provides methods for getting report properties such as the title, author and so
	on. It also provides methods for getting images embedded (stored) within the
	report design. If your application requires more information about the design, you can
	obtain a Design Engine report handle, then use the BIRT <a href="de-api.html">
	Design Engine API</a> to traverse though the report design.</p>

	<h1><code>IEngineTask</code> Abstract Base Class</h1>

	<p>BIRT reports support scripting. Operations that execute scripts require a
	scripting context. Report operations also require a locale. BIRT Engine tasks
	provide the framework for managing the scripting context, report locales and so
	on. In general, if an operation requires neither a script context nor a locale,
	it will appear as a method on the engine or the report design. However, if the
	operation does
	require these items; then the operation is represented by a task class.</p>

	<p>For example, opening a design file or retrieving an image in the design file
	do not require setting up a scripting context. Other operations, such as
	retrieving default parameters, retrieving a dynamic selection list, and running
	and rendering a report, all support scripting, require a scripting context, and
	are represented as tasks.</p>

	<p>Create tasks using the factory methods on the <code>ReportEngine</code> class. Each task
	takes a report runnable (design), a scripting context, a locale, and other
	information.</p>

	<h1><code>IGetParameterDefinitionTask</code> Class</h1>

	<p>Use this task to obtain information about parameters. Parameter default
	values are expressions, and so a scripting context (represented by the task) is
	required. Parameter definitions provide access to the parameter
	definition information that the report designer entered at design time. If a
	parameter has custom XML or user-defined properties defined, then these are also
	available. Applications typically use the standard and custom properties to
	create a parameter UI that prompts the user for parameter values. Parameters can
	be organized into groups. Your application has the choice of retrieving the
	parameters organized by group (as they should be displayed to the user), or in
	ungrouped form (useful for creating a programmatic interface.)</p>

	<p>The <code>IParameterGroupDefn</code> and <code>IScalarParameterDefn</code>
	interfaces provide
	information about parameter groups and individual parameters.</p>

	<pre class="code-block">// Get the parameter definitions

	IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( report );
	Collection params = task.getParameterDefns( true );

	// The collection contains parameters and parameter groups.

	Iterator iter = params.iterator( );
	while ( iter.hasNext( ) )
	{
	IParameterDefnBase param = (IParameterDefnBase) iter.next( );
	if ( param instanceof IParameterGroupDefn )
	{
	IParameterGroupDefn group = (IParameterGroupDefn) param;

	// Do something with the parameter group.
	// Iterate over group contents.

	Iterator i2 = group.getContents( ).iterator( );
	while ( iter.hasNext( ) )
	{
	IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );

	// Do something with a parameter within a group.
	}
	else
	{
	IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );

	// Do something with a top-level parameter.
	}
	}</pre>

	<p>Use the <code>IGetParameterDefinitionTask</code> class to evaluate the default value for a parameter. The parameter
	default value is an expression, and the task provides the required execution
	context.</p>

	<pre class="code-block">IScalarParameterDefn param = ...;
	IGetParameterDefinitionTask task = ...;
	Object value = task.getDefaultValue( param );</pre>

	<h1><code>IRunAndRenderReportTask</code> Class</h1>
	<p>Use this task to run a report and
	convert it to either HTML or PDF. This task does not save the report document
	itself to disk. Create a new task for each report that you run.</p>

	<p class="caution"><span class="caution-head">Release 1.0.1 Note:</span> BIRT 1.0
	supports the ability to run a report and to directly produce HTML or PDF. Later
	versions will allow the ability to save the report document to disk for later
	use. At that time, BIRT will provide other tasks to run the report, then later
	to render a saved report document.
	</p>

	<p>Reports may take parameters. The <code>IRunAndRenderReportTask</code> takes parameter
	values as a <code>HashMap</code>. The <code>IRunAndRenderReportTask</code> provides
	the <code>validateParameters( )</code> method to validate the parameter values before you run
	the report.</p>

	<p>You can produce HTML or PDF output. Each format offers a distinct set of
	options. These options are set through the <code>HTMLRenderOption</code> and
	<code>PDFRenderOption</code>
	classes. Create the one for the output format you desire, set the options you
	need, and pass the instance to <code>IRunAndRenderReportTask</code> before running the
	report.</p>

	<pre class="code-block">// Create the task

	IRunAndRenderTask task = engine.createRunAndRenderTask( report );

	// Set up options for HTML output.

	HTMLRenderOption options = new HTMLRenderOption( );
	options.setOutputFormat( HTMLRenderOption.OUTPUT_FORMAT_HTML );
	options.setOutputFileName( outputName );
	task.setRenderOption( options );

	// Set parameter values using a HashMap. Parameters are name/value pairs.
	// The values must be Java objects of the correct type.

	HashMap params = new HashMap( );
	...
	task.setParameterValues( params );

	// Run the report.

	task.run( );</pre>

	<h1>Example Application</h1>

	The best way to learn about the engine API is to look at a sample application.
	This sample is a command-line application that takes a report design and can
	either print parameter information about the design (-i option), or run and render the
	report (-h option for HTML, -p option for PDF). When running, the utility takes a set of parameter values, and accepts
	an output format. The application illustrates the major steps you should follow
	in your own application.<p><a href="RunReport.java">Download the sample
	application</a>.</p>
	<a href="birtengine.zip">Download the sample
	application Ant project</a>.
	The Ant project has a readme.txt explaining which files need to be copied.
	<p>To run a <a href="test.rptdesign">sample report </a>to HTML, setting the
	"sample" parameter to the value "Hello":</p>
	<pre class="code-block">java RunReport test.rptdesign -h sample=Hello</pre>
	<p>To get information about the report properties and parameter definitions:</p>
	<pre class="code-block">java RunReport test.rptdesign -i</pre>


	</body>
	</html>