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:
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 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.
<%@ page
import="com.crystaldecisions.reports.reportengineinterface.JPEReportSourceFactory,
com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,
com.crystaldecisions.reports.reportengineinterface.IReportSource"
IReportSourceFactory2 rptSrcFactory = new
JPEReportSourceFactory();
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());
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:
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.
CrystalReportViewer viewer = new CrystalReportViewer();
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.
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.
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.
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.
The following example is a simple JSP page that demonstrates how to use the viewer to display a simple report.
<%@ 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);
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:
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.
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.
ExportOptions exportOptions = new ExportOptions();
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.
In this case, because the export format is RTF, a RTFWordExportFormatOptions object is created.
RTFWordExportFormatOptions RTFExpOpts = new
RTFWordExportFormatOptions();
In this example, the export options are configured so that only pages 1 to 3 are exported.
RTFExpOpts.setStartPageNumber(1);
RTFExpOpts.setEndPageNumber(3);
exportOptions.setFormatOptions(RTFExpOpts);
exportControl.setReportSource(reportSource);
exportControl.setExportOptions(exportOptions);
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);
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.
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.
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.
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.
<%@ 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);
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:
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:
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.
Fields fields = new Fields();
ParameterField
pfield1 = new ParameterField();
ParameterField
pfield2 = new ParameterField();
If a ranged value is being set, a ParameterFieldRangeValue object should be used instead of the discrete value object.
ParameterFieldDiscreteValue
pfieldDV1 = new ParameterFieldDiscreteValue();
ParameterFieldDiscreteValue
pfieldDV2 = new ParameterFieldDiscreteValue();
Once all the required objects have been created, the values for the fields can be initialized.
Values for parameter fields are represented by a ParameterFieldDiscreteValue or ParameterFieldRangeValue object.
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");
pfield1.setCurrentValues(vals1);
pfield2.setCurrentValues(vals2);
After all the parameter fields have been initialized and added to the Fields object, the Fields object can be passed to the viewer.
CrystalReportViewer
viewer = new CrystalReportViewer();
viewer.setReportSource(reportSource);
User prompting should be disabled to automatically use the set parameter field value.
viewer.setParameterFields(fields);
viewer.setEnableParameterPrompt(false);
viewer.refresh();
viewer.processHttpRequest(request, response,
getServletConfig().getServletContext(), null);
viewer.dispose();
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.
<%@ 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());
ParameterField
pfield1 = new ParameterField();
ParameterField
pfield2 = new ParameterField();
ParameterFieldDiscreteValue
pfieldDV1 = new ParameterFieldDiscreteValue();
ParameterFieldDiscreteValue
pfieldDV2 = new ParameterFieldDiscreteValue();
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");
pfield1.setCurrentValues(vals1);
pfield2.setCurrentValues(vals2);
CrystalReportViewer
viewer = new CrystalReportViewer();
viewer.setReportSource(reportSource);
viewer.setParameterFields(fields);
viewer.setEnableParameterPrompt(false);
viewer.processHttpRequest(request,
response, getServletConfig().getServletContext(), out);
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:
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.
ConnectionInfos connInfos = new ConnectionInfos();
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.
In this case, a generic guest account is used for each.
connInfo1.setUserName("guest");
connInfo1.setPassword("password");
connInfo2.setUserName("guest");
connInfo2.setPassword("password");
The ConnectionInfos object can now be used to set the database logon information for a report.
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
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.
CrystalReportViewer
viewer = new CrystalReportViewer();
viewer.setReportSource(reportSource);
viewer.setDatabaseLogonInfos(connInfos);
viewer.setEnableLogonPrompt(false);
viewer.processHttpRequest(request, response,
getServletConfig().getServletContext(), null);
viewer.dispose();
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.
<%@ 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");
CrystalReportViewer
viewer = new CrystalReportViewer();
viewer.setReportSource(reportSource);
viewer.setDatabaseLogonInfos(connInfos);
viewer.setEnableLogonPrompt(false);
viewer.processHttpRequest(request,
response, getServletConfig().getServletContext(), out);
Crystal Decisions http://www.crystaldecisions.com/ Support services http://support.crystaldecisions.com/ |