## Tutorials

This section contains a series of tutorials that show you how to use the Viewer Java SDK. The tutorials assume that you are familiar with JSP programming. Since each tutorial builds on the previous ones, it is recommended that you work through the series sequentially.

The first tutorial shows you how to create a report source programmatically. You must be able to create a report source before you can use the viewer or the export control in your JSP pages. The remaining tutorials then show you how to use the report source in conjunction with the export control and the viewer.

To jump to a particular tutorial, click the appropriate link:

- How to create a report source
- How to use the Java viewer
- How to export a report
- How to set a parameter field
- How to set a database logon

### How to create a report source

Before you can use the export control or the viewer in your JSP pages, you must obtain a report source.

A report source is an object that represents a single instance of a report. It implements the IReportSource interface, which contains a set of methods that are used by both the export control and the viewer. The report source included with Crystal Reports for BEA WebLogic Workshop is the Java Reporting Component.

The tutorial contains the following sections:

- Creating a report source object

#### Creating a report source object

Creating a Java Reporting Component report source only requires you to have the location of the report you wish to view or export. The report location can be specified using a file system path, UNC address, or URL. For more information on the Java Reporting Component report source and specifying paths, see Java Reporting Component. Also, for the Java Reporting Component to correctly retrieve data for a report, the report's data sources must be correctly specified through JNDI. For more information on data source configuration, see Configuring data sources.

###### To create a report source object

1. Ensure that you have imported the JPEReportSourceFactory class and the IReportSource and IReportSourceFactory2 interfaces.

   `<%@ page import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,`

   `com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,`

   `com.crystaldecisions.reports.reportengineinterface.IReportSource"`

   `%>`

2. Create a new JPEReportSourceFactory object.

   `IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();`

3. Call the IReportSourceFactory2 object's createReportSource method, passing it the path to the desired report and the current locale settings.

   The IReportSource object can now be used by the viewer or export control.

   `String report = "/reports/sample.rpt";`

   `IReportSource reportSource = (IReportSource) rptSrcFactory.createReportSource(report, request.getLocale());`

### How to use the Java viewer

This tutorial demonstrates how to use the Java viewer programmatically to display a report in a web browser.

It is assumed that you have already created a report source. If you haven't, see Creating a report source object for details.

The tutorial contains the following sections:

- Creating and initializing a Java viewer
- Launching the Java viewer
- Performing garbage collection
- Example

#### Creating and initializing a Java viewer

The viewer is simply an instance of a CrystalReportViewer object. A CrystalReportViewer object has many set methods that affect how it displays reports in a web browser. Some of them need to be called before the viewer can render a report. When using the Java Reporting Component, you need to set the viewer's report source.

###### To create and initialize a Java viewer

1. Instantiate a CrystalReportViewer object.

   `CrystalReportViewer viewer = new CrystalReportViewer();`

2. Set the viewer's report source by calling its setReportSource method, passing it a reference to a report source object.

   The viewer has now been created and initialized.

   `viewer.setReportSource(reportSource);`

Note: Once the viewer is created and initialized, you can set a variety of properties related to its display characteristics, database logon handling, and parameter prompting. For more information, see the CrystalReportViewer documentation in the Crystal Reports for BEA WebLogic Workshop Java API Reference.

#### Launching the Java viewer

Once you have created and initialized a Java viewer, call its processHttpRequest method to launch it in a web browser.

This example assumes that you have set up the viewer properly, and that you have valid request, response, and session objects.

###### To launch the Java viewer

1. Call the processHttpRequest method to launch the viewer in the current browser window.

   `viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), null);`

   Note: If the viewer's content is going to be displayed more than once, using the getHtmlContent method is more efficient. This is because the request is processed only once and the resulting HTML string can be used multiple times.

#### Performing garbage collection

In order to ensure the maximum performance for your web applications, you must ensure that the dispose method is called whenever you are finished with the viewer. This ensures that any resources being tied up are freed for use by other applications.

###### To perform garbage collection for the viewer

1. Call the viewer's dispose method.

   `viewer.dispose();`

#### Example

The following example is a simple JSP page that demonstrates how to use the viewer to display a simple report.

##### viewreport.jsp

`<%@ page import="com.crystaldecisions.report.web.viewer.CrystalReportViewer" %>`

`<%@ page import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,`

`com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,`

`com.crystaldecisions.reports.reportengineinterface.IReportSource"`

`%>`

``

`<%`

``

`String report = "c:/reports/sample.rpt";`

`IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();`

`IReportSource reportSource = (IReportSource) rptSrcFactory.createReportSource(report, request.getLocale());`

``

`CrystalReportViewer viewer = new CrystalReportViewer();`

`viewer.setReportSource(reportSource);`

``

`viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), out);`

``

`viewer.dispose();`

``

`%>`

### How to export a report

This tutorial shows you how to use the Export Control to export a Crystal report to one of several available formats. For the complete list of possible export formats, see Export formats.

It is assumed that you have already created a report source. If you haven't, see Creating a report source object for details.

The tutorial contains the following sections:

- Creating and initializing an Export Control
- Exporting the report
- Performing garbage collection
- Example

#### Creating and initializing an Export Control

The export control handles all aspects of exporting the report. It allows you to preview the exported report within the browser window or export it as an attachment, prompting the user with a download dialog. The export control is represented by the ReportExportControl class.

###### To create an Export Control

1. Instantiate a ReportExportControl object.

   `ReportExportControl exportControl = new ReportExportControl();`

Once you have created the ReportExportControl`` object, you must specify the export format that you want. For the purpose of this example, RTF has been chosen as the export format. For a complete list of export formats, see the Export formats section.

###### To specify the export format

1. Create an ExportOptions object.

   `ExportOptions exportOptions = new ExportOptions();`

2. Specify the export format by calling the ExportOptions object's setExportFormatType method, passing it a ReportExportFormat constant representing the desired format.

   `exportOptions.setExportFormatType(ReportExportFormat.RTF);`

   Note: A list of the valid constants specifying export formats can be found in the ReportExportFormat class documentation.

Some formats contain additional options that can be configured to customize how the report is exported. This includes control over what page range is exported and so on.

###### To configure format specific options

1. Create the appropriate format options object.

   In this case, because the export format is RTF, a RTFWordExportFormatOptions object is created.

   `RTFWordExportFormatOptions RTFExpOpts = new RTFWordExportFormatOptions();`

2. Configure the options you wish to set.

   In this example, the export options are configured so that only pages 1 to 3 are exported.

   `RTFExpOpts.setStartPageNumber(1);`

   `RTFExpOpts.setEndPageNumber(3);`

3. Call the ReportExportOptions object's setFormatOptions method, passing it the format options object.

   `exportOptions.setFormatOptions(RTFExpOpts);`

###### To initialize the Export Control

1. Set the control's report source by calling its setReportSource method and passing the method a reference to the report source object that you created.

   `exportControl.setReportSource(reportSource);`

2. Call the control's setExportOptions method, passing it the ExportOptions object that you created earlier.

   `exportControl.setExportOptions(exportOptions);`

3. You may also want to call the setExportAsAttachment method.

   Setting this method to true causes the Export Control to display a dialog box that allows users of your web application to save the exported report before they open it. Otherwise, the exported report is displayed in the browser window directly.

   `exportControl.setExportAsAttachment(true);`

#### Exporting the report

Once you have created and initialized an export control, calling its processHttpRequest method completes the export.

This example assumes that you have set up the export control properly, and that you have valid request, response, and session objects.

###### To export a report

- Call the processHttpRequest method to export the report.

  If setExportAsAttachment is set to true, the user is prompted with a download dialog, otherwise the exported report is displayed directly in the browser.

  `exportControl.processHttpRequest(request, response, getServletContext(), null);`

Note: If you intend to export a report more than once, using the getHtmlContent method is more efficient, because the request is processed once and the resulting HTML string can be used multiple times.

#### Performing garbage collection

In order to ensure the maximum performance for your web applications, you must ensure that the dispose method is called whenever you are finished with the export control. This ensures that any resources being tied up are freed for use by other applications.

###### To perform garbage collection for the viewer

1. Call the export control's dispose method.

   `exportControl.dispose();`

#### Example

The following example is a simple JSP page that demonstrates how to use the export control to export the first 3 pages of a report to RTF.

exportreport.jsp

`<%@ page import="com.crystaldecisions.report.web.viewer.ReportExportControl" %>`

`<%@ page import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,`

`com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,`

`com.crystaldecisions.reports.reportengineinterface.IReportSource"`

`%>`

`<%@ page import="com.crystaldecisions.sdk.occa.report.exportoptions.ExportOptions" %>`

`<%@ page import="com.crystaldecisions.sdk.occa.report.exportoptions.ReportExportFormat" %>`

`<%@ page import="com.crystaldecisions.sdk.occa.report.exportoptions.IRTFWordExportFormatOptions" %>`

``

`<%`

``

`String report = "c:/reports/sample.rpt";`

`IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();`

`IReportSource reportSource = (IReportSource) rptSrcFactory.createReportSource(report, request.getLocale());`

``

`ReportExportControl exportControl = new ReportExportControl();`

`ExportOptions exportOptions = new ExportOptions();`

`exportOptions.setExportFormatType(ReportExportFormat.RTF);`

``

`RTFWordExportFormatOptions RTFExpOpts = new RTFWordExportFormatOptions();`

`RTFExpOpts.setStartPageNumber(1);`

`RTFExpOpts.setEndPageNumber(3);`

`exportOptions.setFormatOptions(RTFExpOpts);`

``

`exportControl.setReportSource(reportSource);`

`exportControl.setExportOptions(exportOptions);`

`exportControl.setExportAsAttachment(true);`

`exportControl.processHttpRequest(request, response, getServletConfig().getServletContext(), null);`

`exportControl.dispose();`

``

`%>`

### How to set a parameter field

This tutorial shows you the basic steps required to programmatically set parameter fields for a report that is displayed using the viewer. Setting the parameter fields for a report allows a report that contains parameter prompts to always be displayed using the same values. Also, setting parameter fields can be used to change the default values or modify the values as needed. The report used in this example is created in the Crystal Reports Designer and has two parameter fields: Region and Country Code. The default values of the parameter fields and the new values that the code sets them to are as follows:

- Region (String)

  Default value: Canada

  Set value: Japan

- Country Code (Number)

  Default value: 1

  Set value: 81

Note: This report is not included with the tutorial, but a simple report containing similar parameter fields and information can be easily created in the Crystal Reports Designer.

It is assumed that you have already created a report source. If you haven't, see Creating a report source object for details.

The tutorial contains the following sections:

- Creating and initializing parameter fields
- Setting parameter fields
- Example

#### Creating and initializing parameter fields

Before a parameter field can be set in a report, the fields to be set must first be created, then initialized. Individual parameter fields are all stored in a Fields object. The Fields object is simply a collection of different fields that can be passed to the viewer.

###### To create parameter fields

1. Create a Fields object to store the parameter fields in.

   `Fields fields = new Fields();`

2. Create a ParameterField object for each field that you wish to set.

   `ParameterField pfield1 = new ParameterField();`

   `ParameterField pfield2 = new ParameterField();`

3. Create a Values object and a ParameterFieldDiscreteValue object for each parameter field you wish to set.

   If a ranged value is being set, a ParameterFieldRangeValue object should be used instead of the discrete value object.

   `Values vals1 = new Values();`

   `Values vals2 = new Values();`

   `ParameterFieldDiscreteValue pfieldDV1 = new ParameterFieldDiscreteValue();`

   `ParameterFieldDiscreteValue pfieldDV2 = new ParameterFieldDiscreteValue();`

Once all the required objects have been created, the values for the fields can be initialized.

###### To initialize parameter fields

1. Set the name and value for each parameter field that is added.

   Values for parameter fields are represented by a ParameterFieldDiscreteValue or ParameterFieldRangeValue object.

   `pfield1.setName("Region");`

   `pfieldDV1.setValue("Japan");`

   `pfieldDV1.setDescription("The region is Japan");`

   ``

   `Integer CountryCode = new Integer("81");`

   `pfield2.setName("Country Code");`

   `pfieldDV2.setValue(CountryCode);`

   `pfieldDV2.setDescription("The country code is 81");`

2. Add the parameter field values to the Values collection object.

   `vals1.add(pfieldDV1);`

   `vals2.add(pfieldDV2);`

3. Set the current Values collection for each parameter field.

   `pfield1.setCurrentValues(vals1);`

   `pfield2.setCurrentValues(vals2);`

4. Add each parameter field to the Fields collection.

   The Fields object is now ready to be used with the viewer.

   `fields.add(pfield1);`

   `fields.add(pfield2);`

#### Setting parameter fields

After all the parameter fields have been initialized and added to the Fields object, the Fields object can be passed to the viewer.

###### To set parameter fields

1. Create an instance of the viewer, passing it a reference to a report source object.

   `CrystalReportViewer viewer = new CrystalReportViewer();`

   `viewer.setReportSource(reportSource);`

2. Set the parameter fields for the viewer by passing in the initialized Fields object.

   User prompting should be disabled to automatically use the set parameter field value.

   `viewer.setParameterFields(fields);`

   `viewer.setEnableParameterPrompt(false);`

3. Call the viewer's refresh method to apply new parameters.

   `viewer.refresh();`

4. Call the processHttpRequest method to launch the viewer in the current browser window.

   `viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), null);`

5. Call the dispose method to allow the viewer to perform the appropriate garbage collection and free system resources.

   `viewer.dispose();`

#### Example

The following example is a JSP page that demonstrates how to set two parameter fields for a report containing Region and Country Code parameter. After the parameters have been set, the report is displayed.

parameterFieldsViewReport.jsp

`<%@ page import= "com.crystaldecisions.report.web.viewer.*,`

`com.crystaldecisions.sdk.occa.report.data.*" %>`

`<%@ page import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,`

`com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,`

`com.crystaldecisions.reports.reportengineinterface.IReportSource"`

`%>`

``

`<%`

``

`String report = "c:/reports/sample.rpt";`

`IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();`

`IReportSource reportSource = (IReportSource) rptSrcFactory.createReportSource(report, request.getLocale());`

``

`Fields fields = new Fields();`

``

`ParameterField pfield1 = new ParameterField();`

`ParameterField pfield2 = new ParameterField();`

``

`Values vals1 = new Values();`

`Values vals2 = new Values();`

``

`ParameterFieldDiscreteValue pfieldDV1 = new ParameterFieldDiscreteValue();`

`ParameterFieldDiscreteValue pfieldDV2 = new ParameterFieldDiscreteValue();`

``

`pfield1.setName("Region");`

`pfieldDV1.setValue("Japan");`

`pfieldDV1.setDescription("The region is Japan");`

``

`Integer CountryCode = new Integer("81");`

`pfield2.setName("Country Code");`

`pfieldDV2.setValue(CountryCode);`

`pfieldDV2.setDescription("The country code is 81");`

``

`vals1.add(pfieldDV1);`

`vals2.add(pfieldDV2);`

``

`pfield1.setCurrentValues(vals1);`

`pfield2.setCurrentValues(vals2);`

``

`fields.add(pfield1);`

`fields.add(pfield2);`

``

`CrystalReportViewer viewer = new CrystalReportViewer();`

`viewer.setReportSource(reportSource);`

``

`viewer.setParameterFields(fields);`

`viewer.setEnableParameterPrompt(false);`

``

`viewer.refresh();`

``

`viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), out);`

``

`viewer.dispose();`

``

`%>`

### How to set a database logon

This tutorial shows you the basic steps required to programmatically set a database logon. Almost all reports rely on a database to retrieve information, with the large majority of database connections requiring a user logon. While the viewer prompts the user for database logon information when it is needed, it is often desirable to set the database logon information for a report, as it simplifies the user's viewing experience.

It is assumed that you have already created a report source. If you haven't, see Creating a report source object for details.

The tutorial contains the following sections:

- Creating and initializing database logon information
- Setting database logon information
- Example

#### Creating and initializing database logon information

Database logon information is stored in a ConnectionInfo object. The ConnectionInfo object is then added to a ConnectionInfos collection object. This allows more than one database logon to be added, providing support for subreports with different database connections.

###### To create and initialize database logon information

1. Create an ConnectionInfos object to store the database logon information in.

   `ConnectionInfos connInfos = new ConnectionInfos();`

2. Create a ConnectionInfo object for each database logon you wish to set.

   `IConnectionInfo connInfo1 = new ConnectionInfo();`

   `IConnectionInfo connInfo2 = new ConnectionInfo();`

   Note: The interface is used to manipulate the ConnectionInfo object, as it simplifies the methods available and allows for future support of different types of ConnectionInfo objects.

3. Set the database logon information for each ConnectionInfo object.

   In this case, a generic guest account is used for each.

   `connInfo1.setUserName("guest");`

   `connInfo1.setPassword("password");`

   ``

   `connInfo2.setUserName("guest");`

   `connInfo2.setPassword("password");`

4. Add each ConnectionInfo object to the ConnectionInfos collection.

   The ConnectionInfos object can now be used to set the database logon information for a report.

   `connInfos.add(connInfo1);`

   `connInfos.add(connInfo2);`

   Note: If only one ConnectionInfo object is added to the ConnectionInfos collection, then the user name and password stored in that ConnectionInfo object is applied to all connections, including embedded subreports and on-demand subreports.

#### Setting database logon information

Once a properly initialized ConnectionInfos object has been created, the database logon information can be passed to the viewer. The viewer handles the process of passing this information to the report.

###### To set the database logon information

1. Create an instance of the viewer, passing it a reference to a report source object.

   `CrystalReportViewer viewer = new CrystalReportViewer();`

   `viewer.setReportSource(reportSource);`

2. Set the database logon information by passing the viewer the initialized ConnectionInfos object.

   `viewer.setDatabaseLogonInfos(connInfos);`

   `viewer.setEnableLogonPrompt(false);`

3. Call the processHttpRequest method to launch the viewer in the current browser window.

   `viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), null);`

4. Call the dispose method to allow the viewer to perform the appropriate garbage collection and free system resources.

   `viewer.dispose();`

#### Example

The following example is a JSP page that demonstrates how to set the database logon information for a report requiring 2 database logons. After the logon information has been set, the report is displayed.

setDbLogonViewReport.jsp

`<%@ page import= "com.crystaldecisions.report.web.viewer.*,`

`com.crystaldecisions.sdk.occa.report.data.*" %>`

`<%@ page import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,`

`com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,`

`com.crystaldecisions.reports.reportengineinterface.IReportSource"`

`%>`

``

`<%`

``

`String report = "c:/reports/sample.rpt";`

`IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();`

`IReportSource reportSource = (IReportSource) rptSrcFactory.createReportSource(report, request.getLocale());`

``

`ConnectionInfos connInfos = new ConnectionInfos();`

``

`IConnectionInfo connInfo1 = new ConnectionInfo();`

`IConnectionInfo connInfo2 = new ConnectionInfo();`

``

`connInfo1.setUserName("guest");`

`connInfo1.setPassword("password");`

`connInfo2.setUserName("guest");`

`connInfo2.setPassword("password");`

``

`connInfos.add(connInfo1);`

`connInfos.add(connInfo2);`

``

`CrystalReportViewer viewer = new CrystalReportViewer();`

`viewer.setReportSource(reportSource);`

``

`viewer.setDatabaseLogonInfos(connInfos);`

`viewer.setEnableLogonPrompt(false);`

``

`viewer.processHttpRequest(request, response, getServletConfig().getServletContext(), out);`

``

`viewer.dispose();`

``

`%>`

Crystal Decisions http://www.crystaldecisions.com/ Support services http://support.crystaldecisions.com/