cr for ibm wsad tutorial

8/2/2019 Cr for Ibm Wsad Tutorial

1/22

Crystal Reports for IBM WebSphereStudio Application Developer 5.1.1

White Paper

Tutorial - Using the Java Viewer SDK


2/22

2

Author: Derek Stobbart

Audience: WebSphere Studio Application Developers usingCrystal Reports


3/22

Executive Summary 4

How to Create a Report Source 5

Creating and initializing a Java viewer 6

Launching the viewer 6

Performing garbage collection 7

How to Export a Report 8

Creating and initializing an Export Control 8

To create an Export Control 8

To specify the export format 8

To configure format specific options 8To initialize the Export Control 9

Exporting the report 9

To export a report 9

Performing garbage collection 10

To perform garbage collection for the viewer 10

How to set a parameter field 12

Creating and initializing parameter fields 12

To create parameter fields 12

To initialize parameter fields 13

Setting parameter fields 14

To set parameter fields 14

Example - parameterFieldsViewReport.jsp 14

How to set a database logon 16Creating and initializing database logon information 16

To create and initialize database logon information 16

Setting database logon information 17

To set database logon information 17

Example setDbLogonViewReport.jsp 17

Appendix A 19

Report Resources 19

Java Reporting Component 19

Specifying location through the URL 19Java Reporting Component configuration 19

3

Contents


4/22

This document contains a series of tutorials that demonstrates how to use theCrystal Reports Java Viewer SDK provided with IBM WebSphere StudioApplication Developer 5.1.1. The tutorials assume that you are familiar with JSPprogramming. Since each tutorial builds on the previous ones, it is recommendedthat you work through the series sequentially.

The first tutorial shows you how to create a report source programmatically. Youmust be able to create a report source before you can use the viewer or the exportcontrol 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.

4

Executive Summary


5/22

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 IBM

WebSphere Studio is the Java Reporting Component.

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 will be specifiedusing a relative URL. For more information on the Java Reporting Component report

source and specifying paths, see Appendix A. Also, for the Java Reporting Component

to correctly retrieve data for a report, the reports data sources must be correctly specifiedthrough JNDI, JDBC or XML.

NOTE When using JNDI to establish a connection the Java Reporting Component relies on theJNDI server running on your application server to determine how to connect to the datasources specified in a report. Once the connection information has been retrieved fromthe JNDI server, the Java Reporting Component uses the information to establish a JDBCconnection to the data source. To ensure that the Java Reporting Component cansuccessfully establish a connection when retrieving report data, ensure that the JNDIentries for the required data sources are correctly configured. For more information onhow to configure a JNDI data source entry, please consult your application server and

JDBC driver documentation.

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

2. Create a new JPEReportSourceFactory object.IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();

3. Call the IReportSourceFactory2 objects createReportSource method, passing itthe 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());

5

How to Create a Report Source


6/22

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

The tutorial contains the following sections:

Creating and initializing a Java viewer

Launching the viewer

Performing garbage collection

Creating and initializing a Java viewerThe viewer is simply an instance of a CrystalReportViewer object. A

CrystalReportViewer object has many set methods that affect how it displaysreports in a web browser. Some of them need to be called before the viewer canrender a report. When using the Java Reporting Component, you need to set theviewers report source.

1. Instantiate a CrystalReportViewer object.CrystalReportViewer viewer = new CrystalReportViewer();

2. Set the viewers 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 itsdisplay characteristics, database logon handling, and parameter prompting. For moreinformation, see the CrystalReportViewer documentation in the Crystal Reports for IBMWebSphere Studio Java API Reference provided in WebSphere Studio ApplicationDeveloper 5.1.1.

Launching the viewerOnce you have created and initialized a Java viewer, call its processHttpRequestmethod to launch it in a web browser.This example assumes that you have set up the viewer properly, and that youhave valid request, response, and session objects.

1. Call the processHttpRequest method to launch the viewer in the currentbrowser window.

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

NOTE If the viewer's content is going to be displayed more than once, using the getHtmlContentmethod is more efficient. This is because the request is processed only once and theresulting HTML string can be used multiple times.

6



7/22

Performing garbage collectionIn order to ensure the maximum performance for your web applications, youmust ensure that the dispose method is called whenever you are finished withthe viewer. This ensures that any resources being tied up are freed for use byother applications.

1. Call the viewers dispose method.viewer.dispose();

Example

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

viewreport.jsp

7



8/22

How to Export a Report

This tutorial shows you how to use the Export Control to export a Crystal reportto RTF or PDF formats.

The tutorial contains the following sections: Creating and initializing an Export Control Exporting the report Performing garbage collection Example

Creating and initializing an Export ControlThe export control handles all aspects of exporting the report. It allows you topreview the exported report within the browser window or export it as anattachment, prompting the user with a download dialog. The export control isrepresented by the ReportExportControl class.

To create an Export Control1. Instantiate a ReportExportControl object.

ReportExportControl exportControl = new ReportExportControl();Once you have created the ReportExportControl object, you must specifythe export format that you want. For the purpose of this example, RTFhas been chosen as the export format.

To specify the export format1. Create an ExportOptions object.

ExportOptions exportOptions = new ExportOptions();

2. Specify the export format by calling the ExportOptions objectssetExportFormatType method, passing it a ReportExportFormat constantrepresenting the desired format.exportOptions.setExportFormatType(ReportExportFormat.RTF);

NOTEA list of the valid constants specifying export formats can be found in the

ReportExportFormat class documentation provided in WebSphere Studio Application

Developer 5.1.1.

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

To configure format specific options1. Create the appropriate format options object. In this case, because the

export format is RTF, a RTFWordExportFormatOptions object is created.

RTFWordExportFormatOptions RTFExpOpts = newRTFWordExportFormatOptions();

8


9/22

2. Configure the options you wish to set. In this example, the export optionsare configured so that only pages 1 to 3 are exported.

RTFExpOpts.setStartPageNumber(1);RTFExpOpts.setEndPageNumber(3);

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

exportOptions.setFormatOptions(RTFExpOpts);

To initialize the Export Control1. Set the controls report source by calling its setReportSource method and

passing the method a reference to the report source object that youcreated.

exportControl.setReportSource(reportSource);

2. Call the controls setExportOptions method, passing it the ExportOptionsobject 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 dialogbox that allows users of your web application to save the exported reportbefore they open it. Otherwise, the exported report is displayed in thebrowser window directly.

exportControl.setExportAsAttachment(true);

Exporting the reportOnce 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 thatyou have valid request, response, and session objects.

To export a report1. Call the processHttpRequest method to export the report. If

setExportAsAttachment is set to true, the user is prompted with adownload dialog, otherwise the exported report is displayed directly inthe browser.

exportControl.processHttpRequest(request, response,

getServletContext(), null);

9



10/22


NOTE If you intend to export a report more than once, using the getHtmlContent method is moreefficient, because the request is processed once and the resulting HTML string can beused multiple times.

Performing garbage collectionIn order to ensure the maximum performance for your web applications, youmust ensure that the dispose method is called whenever you are finished withthe export control. This ensures that any resources being tied up are freed for useby other applications.

To perform garbage collection for the viewer2. Call the export controls dispose method.

exportControl.dispose();

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

exportreport.jsp


11/22

RTFWordExportFormatOptions RTFExpOpts = newRTFWordExportFormatOptions();

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();

%>

11



12/22

How to set a parameter field

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

Region (String)

Default value: CanadaSet value: Japan

Country Code (Number)Default value: 1Set value: 81

NOTE This report is not included with the tutorial, but a simple report containingsimilar parameter fields and information can be easily created in the CrystalReports designer.

The tutorial contains the following sections: Creating and initializing parameter fields Setting parameter fields Example

Creating and initializing parameter fieldsBefore a parameter field can be set in a report, the fields to be set must first becreated, then initialized. Individual parameter fields are all stored in a Fieldsobject. The Fields object is simply a collection of different fields that can bepassed 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 eachparameter field you wish to set. If a ranged value is being set, aParameterFieldRangeValue object should be used instead of the discrete

value object.

12


13/22

Values vals1 = new Values();Values vals2 = new Values();ParameterFieldDiscreteValue pfieldDV1 = newParameterFieldDiscreteValue();ParameterFieldDiscreteValue pfieldDV2 = newParameterFieldDiscreteValue();

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


To initialize parameter fields1. Identify the report containing the parameter(s). Sometimes your report

may include sub-reports that, in turn, contain the parameters. If this isnot the case you will set the value to be blank. If your parameter islocated in a sub-report, then set the value to the name of the sub-report.

pfield1.setReportName();pfield2.setReportName();

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

Values for parameter fields are represented by aParameterFieldDiscreteValue 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");

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

vals1.add(pfieldDV1);vals2.add(pfieldDV2);

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

pfield1.setCurrentValues(vals1);pfield2.setCurrentValues(vals2);

5. Add each parameter field to the Fields collection. The Fields object isnow ready to be used with the viewer.

fields.add(pfield1);fields.add(pfield2);

13


14/22


Setting parameter fieldsAfter 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 fields1. 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 Fieldsobject. User prompting should be disabled to automatically use the setparameter field value.

viewer.setParameterFields(fields);viewer.setEnableParameterPrompt(false);

3. Call the viewers refresh method to apply new parameters.

viewer.refresh();



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

viewer.dispose();

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

parameterFieldsViewReport.jsp

14


15/22



16/22

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

viewer.dispose();

%>

16



17/22

How to set a database logon

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

The tutorial contains the following sections:

Creating and initializing database logon information

Setting database logon information Example

Creating and initializing database logon informationDatabase logon information is stored in a ConnectionInfo object. TheConnectionInfo object is then added to a ConnectionInfos collection object. Thisallows more than one database logon to be added, providing support forsubreports with different database connections.

To create and initialize database logon information1. Create a 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 itsimplifies the methods available and allows for future support of differenttypes 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 logoninformation for a report.

17


18/22

connInfos.add(connInfo1);connInfos.add(connInfo2);


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

Setting database logon information

Once a properly initialized ConnectionInfos object has been created, the databaselogon information can be passed to the viewer. The viewer handles the process ofpassing this information to the report.

To set the database logon information1. 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);



4. Call the dispose method to allow the viewer to perform the appropriate

garbage collection and free system resources.

viewer.dispose();

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

setDbLogonViewReport.jsp


19/22

com.crystaldecisions.sdk.occa.report.reportsource.IReportSourceFactory2,com.crystaldecisions.reports.reportengineinterface.IReportSource%>

19



20/22

Appendix A

Report sources

A report source is an object used by the viewer to display the contents of thereport. It is a pointer to the report instance that the viewer renders in HTML, andit provides the viewer with the means to query for report data, page information,and other internal report information.

The primary report source you will use with Crystal Reports for IBM WebSphereStudio is the Java Reporting Component. This is an all-Java report source that isdeployable with your web applications.

Although only the Java Reporting Component is provided with Crystal Reportsfor IBM WebSphere Studio, other report sources can be used if you have CrystalEnterprise or a Report Application Server. With Crystal Enterprise and theReport Application Server, the Page Server and RAS server report sources areavailable. This allows the viewer to display reports that are accessible through aCrystal Enterprise Page Server or a RAS server. These report sources are not100% Java-based solutions, as the underlying report rendering facilities are notwritten in Java. They do, however, provide additional features that are notavailable with the Java Reporting Component.

Some of the advantages of using a Page Server include support for caching,higher throughput, and greater scalability. Advantages of using a RAS serverinclude support for report creation and modification, as well as additionalviewers.

Java Reporting Component

Specifying location through a URLThis is a URL that is specified relative to the location of the Java ReportingComponent.

For example, ../reports/sample.rpt resolves to /WEB-INF/reports/sample.rpt

where the Java Reporting Component JAR file is in /WEB-INF/lib.

Java Reporting Component configuration

The behavior of relative paths can be modified by specifying the value of thereportlocation tag in the CrystalReportEngine-config.xml, which is located inyour WEB-INF directory. The value of reportlocation must specify a location asan absolute path or as a path relative to the location of the Java ReportingComponent, which is by default WEB-INF/lib. The value of the reportlocationtag becomes the new root directory that is used to determine the location of areport.

20


21/22

The CrystalReportEngine-config.xml file also allows you to configure the timeout interval that determines when inactive report sources are freed up. This isnecessary as inactive report sources still consume system resources such asdatabase connections, server memory, and disk space used by temporary files.The time-out interval can be specified by setting the value of the timeout tag inthe CrystalReportEngine-config.xml file. By default, the timeout interval is 10minutes. The timeout interval only applies to inactive reports. Reports that arebeing processed are not timed out as a result of exceeding this value. Each time areport source request is successfully completed, the timeout timer is reset. If areport source is not used within the timeout interval, it is freed up and itsresources are made available to other processes.

21

Appendix A


22/22

AmericasBusiness Objects Americas IncTel : +1 408 953 6000+1 800 527 0580

AustraliaBusiness Objects Australia Pty LtdTel : +612 9922 3049

BelgiumBusiness Objects BeLux SA/NVTel : +32 2 713 0777

CanadaBusiness Objects Canada IncTel : +1 416 203 6055

FranceBusiness Objects SATel : +33 1 41 25 21 21

GermanyBusiness Objects Deutschland GmbHTel : +49 2203 91 52 0

ItalyBusiness Objects Italia SpATel : +39 06 518 691

JapanBusiness Objects Nihon BVTel : +81 3 5720 3570

NetherlandsBusiness Objects Nederland BV

Tel : +31 30 225 9000

SingaporeBusiness Objects Asia Pacific Pte LtdTel : +65 6887 4228

SpainBusiness Objects Ibrica SLTel : +34 91 766 87 43

SwedenBusiness Objects Nordic ABTel : +46 8 508 962 00

SwitzerlandBusiness Objects Switzerland SA

Tel : +41 56 483 40 50

United KingdomBusiness Objects (UK) LtdTel : +44 1628 764 600

www.businessobjects.com

Distributed in:AlbaniaArgentinaAustriaBahrainBrazilCameroonChileChinaColombiaCosta RicaCroatiaCzech RepublicDenmarkEcuadorEgyptEstoniaFinlandGabonGreeceHong Kong SARHungaryIcelandIndiaIsraelIvory CoastKoreaKuwaitLatviaLithuaniaLuxembourgMalaysiaMexicoMoroccoNetherlands Antilles

New ZealandNigeriaNorwayOmanPakistanPeruPhilippinesPolandPortugalPuerto RicoQatarRepublic of PanamaRomaniaRussiaSaudi ArabiaSlovak Republic

SloveniaSouth AfricaTaiwanThailandTunisiaTurkeyUAEVenezuela

Business Objects owns the following U.S. patents, which may cover products that are offered and sold by Business Objects:5,555,403; 6,247,008 B1; 6,578,027 B2; 6,490,593; and 6,289,352. Business Objects, the Business Objects logo, Crystal Reports,and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the UnitedS d h i All h i d h i b d k f h i i P d ifi i 22

cr for ibm wsad tutorial

Documents