Whitepapers

Crystal Reports for J2EE Startup Guide

Version 1.0

August 2004

Crystal Reports for J2EE Startup Guide Citigate Hudson

August 2004

Summary: This whitepaper provides step-by-step instructions on the details of generating and displaying reports in various deployment scenarios and application environments using Crystal Reports for Java2, Enterprise Edition.

Overview

What is the Crystal Reports For J2EE Startup Guide? The Crystal Reports for J2EE Startup Guide (hereafter known as “the guide”) is intended to get competent J2EE developers, who are new to Crystal Reports or familiar with older versions, up to speed quickly, using the product in a variety of reporting scenarios. The guide presents several scenario-driven approaches to designing and building reports with Crystal Reports. The guide walks through three different reporting scenarios. The scenarios increase in difficulty, and are described below:

Scenario Description

Basic A Tabular report, designed using the Expert, utilizing a standalone report file deployed as part of a JSP-based Web application.

Intermediate A Master-Detail report with drill-down capabilities, designed manually, utilizing a database view (instead of a straight table) as the data source and using the Crystal Reports Java Reporting Components tag library as the presentation layer code.

Deployment We discuss how to pass database credentials in to a report (so that they need not be deployed with the report itself), how to pass parameters in to the report (to constrain the data displayed as part of the report), and how to export to PDF for display within the browser.

Prerequisites The guide provides the most benefit to developers who are familiar with servlets, JSP, and the general concepts of J2EE. No particular IDE is assumed—all report development is presumed to be done using the Crystal Reports report development environment, rather than using any of the IDE integrations offered by Crystal Reports.

In addition, the guide uses the Xtreme Database sample shipped with Crystal Reports, which installs itself as an ODBC data source. This means that the sample guides will be using the JDBC-ODBC driver to access and report off of this database, something that in general should be avoided for any production system, since the Sun JDBC-ODBC driver is fairly old and fragile. (We use this database so as to provide a baseline that will be familiar to Crystal developers and other documentation and guides.) Because of the fragility of the JDBC-ODBC driver, we will be designing the reports using the direct ODBC connection support in Crystal Reports, but at runtime the data will be coming through the JDBC-ODBC driver, just to prove that this is a 100% Pure Java (at least as much as it can be, using that driver) solution.

One administrative prerequisite must be handled before any samples can be started, however. Crystal Reports, out of the box, does not ship with a JDBC driver for developing reports against, and must be downloaded from the Business Objects website, at http://www.businessobjects.com/products/downloadcenter/. Download the InstallNewDriversv10.zip file, unzip it, run the installation, and when it is complete, we’re almost ready to make use of the JDBC driver to build a report against. (You’ll need to do this if you want to design against the JDBC driver—even though we’re not going to in this guide, you will once you get past these examples.)

The last step necessary to get things into place is to manually edit a configuration file that was installed as part of this “new drivers” installation. In the “Program Files\Common Files\Crystal Decisions\2.5\bin” directory, there is a CRDB_JavaServer.ini file, which needs to be told where to point to your Java Runtime Environment and a CLASSPATH setting to include the Crystal Reports CRDBJavaServer.jar file. Set the PATH setting to point to the “bin” directory of your JRE environment, and make sure the CLASSPATH setting is correct. (Be careful to use backslashes instead of the forward slash as it appears in the default file; Crystal Reports takes this string quite literally and will do no “slash translation” as is common in other Java filenames.) In addition, you will need to point the IORFileLocation to a viable subdirectory, usually something like C:\Temp. (You can also configure the JVM’s max and min heap sizes in this configuration file, as per the –mx and –ms options to the java.exe command-line launcher, but for now the defaults of 64m and 32m, respectively, should be acceptable.)

Although the J2EE Specification is vendor-agnostic, and encourages developers to write code that can be deployed into any J2EE-compliant application server environment, unfortunately it is far more difficult to write about J2EE applications in a concrete fashion without mentioning any vendor-specific details. Rather than try and work around clumsy sentences such as “deploy the web application using the vendor’s web application deployment tool to a servlet context name of ‘Example’, and ensure that the deployment descriptor contains references…”, we will assume the deployment environment is the latest version of Tomcat (5.0.27, as of this writing), installed on a Windows box at C:\Tomcat5.01, and is running on port 8080.

1 Be careful, by the way; if the Tomcat installation path contains a space, you may get errors that complain that “Report location must be set” at runtime. This is because despite support within Java for file- or directory-names with embedded whitespace, it’s still awkward to work with names-with-spaces in them. The workaround, of course, is to install Tomcat to a directory without spaces in it.

Basic Reporting Scenario The Basic Reporting Scenario illustrates the simplicity of adding reporting capabilities to a J2EE web-based application. This scenario creates a report using the Crystal Reports design-time wizards, a.k.a. Experts, which come with the Crystal Reports Designer environment. No code will be necessary to generate the report, and only a minimal amount of code will be necessary to wire up the report into the J2EE application.

To create the sample, start the Crystal Reports environment and begin the design of a new report using File|New. Select “Using the Report Wizard” (which will most likely be the default) radio buton, and under “Choose a Wizard” leave it selected on “Standard”, as per Figure 1 below:

Next you will be greeted with a dialog asking you for the data source to generate the report from. Generally, when developing reports designed to be run from the J2EE environment, you will want to use JDBC/JNDI database connections, since that’s how the report will be fetching data at runtime. Double-click “JDBC(JNDI)” (under the “Create New Connection” folder in the “Available Data Sources” list), and the “JDBC(JNDI) Connection” dialog will appear, asking for the JDBC or JNDI connection properties to use in order to connect to the database. In our case, we’re looking to connect against the Xtreme Sample Database that’s installed as part of the Crystal Reports environment, so set the Connection URL to a suitable JDBC URL (“jdbc:odbc:Xtreme ”) and the Database Classname to the JDBC driver of choice (“sun.jdbc.odbc.JdbcOdbcDriver”)2:

2 Again, because of the fragility of the JDBC-ODBC driver, for purposes of this guide, the report will be designed using the ODBC driver; for any other JDBC driver, however, you would proceed exactly as described. (Note that the screen shots after this one will show designing from the ODBC connection, instead of the JDBC-ODBC connection.)

Click Next, and the wizard will next present “Connection Information” for you to fill in User ID, password, and database values; these correspond to the parameters used when connecting via the JDBC DriverManager, and for our purposes can remain as they are.

Once we’ve connected to the database, specify the tables to add to the report by opening up the “Tables” node underneath the data source, and either double-clicking or selecting and clicking the “>>” button to insert the table names into the right-hand column. Select the “Customer” table, and click “Next”.

Select which columns should be displayed as part of this report by, again, double-clicking the column names in the left-hand tree. Select the following columns:

• Customer ID

• Customer Name

• Contact First Name, Contact Last Name, and Contact Position

• Address1 and Address2

• City, Region, Country and Postal Code

When these have been selected, click “Next”:

We want to group the report by Country, so on this next page double click the “Customer.Country” item underneath “Grouping Fields” in the left-hand pane, and click “Finish” to generate the report:

What we end up with (after

the Report Designer churns for a while, depending on how much data is in the data source already) is something similar to the following:

At this point, the report is created and ready to run. The last few steps involve setting up the J2EE application server environment to host the report from the web application. For this, we will need to do a few installation/deployment tasks in order to enable Crystal Reports to execute successfully from the application server environment. Save the report as “Report1.rpt” to a location of your choice (we’ll copy it from there into the web application directory in just a bit), and close down the Crystal Reports studio.

Several steps need to be done in order to execute the report from the Tomcat web application (which we’ll assume is running already in a web application called “CRStartupGuide”, and is already installed as per the Tomcat administrative interface):

1. Copy Java Reporting Component and necessary support .jars from C:\Program Files\Common Files\Crystal Decisions\2.5\java\lib and C:\Program Files\Common Files\Crystal Decisions\2.5\java\lib\external into the “/lib” folder inside the web application or .war file.

2. Copy the contents of the crystalreportviewers10 directory (found in C:\Program Files\Common Files\Crystal Decisions\2.5) to a subdirectory of the same name directly underneath the CRStartupGuide directory (as a peer to WEB-INF). Ensure that all contents, both files and subdirectories, are copied—there should be about 150 files in all. This name of this subdirectory in the CRStartupGuide directory is not important, so long as it matches up when referenced in the web.xml file, which must have the following block added:

<context-param>

<param-name>crystal_image_uri</param-name>

<param-value>crystalreportviewers10</param-value>

</context-param>

Generally, developers will leave the name as is (crystalreportviewers10).

3. Copy the CrystalReportingEngine-config.xml file into the “WEB-INF/classes” subdirectory from C:\Program Files\Common Files\Crystal Decisions\2.5\java directory. Open it up, and change the “reportlocation” element to read “..” instead of its default “../..”3.

4. Copy the report file itself into the WEB-INF directory of the webapp.

5. Write the JSP page (call it basic.jsp, in the root of the web application subdirectory) that will ask the Crystal Reports rendering engine to take the passed report and generate HTML from it, echoing it back to the webapp’s current client. This takes two principal steps. First, we need to create a report viewer to use to process the HTTP request, and second, we need to create a report source that the report viewer will use as the input for generating the report. The report source is an simple object around the filename of the report, as shown here:

<%@ page

import="com.crystaldecisions.reports.reportengineinterface.*,

com.crystaldecisions.report.web.viewer.*" %>

<%

CrystalReportViewer crv = new CrystalReportViewer();

JPEReportSourceFactory jrsf = new JPEReportSourceFactory();

crv.setReportSource(

jrsf.createReportSource("Report1.rpt",

request.getLocale()));

crv.processHttpRequest(request, response,

application, null);

%>

6. Browse to http://localhost:8080/CRStartupGuide/basic.jsp:

3 This will allow you to “hide” the Crystal Reports .rpt file in the WEB-INF directory, where it will not be directly browsable by the end user of your application. You could also hide them in /WEB-INF/classes or /WEB-INF/lib, or any other directory under WEB-INF, so long as you modify the config file accordingly.

Scenario Conclusion The Basic scenario describes how easy it is to add reporting to a J2EE web-based application. However, most real-world reporting demands more sophisticated reports than just simple dumps of tables, even when grouped as above. The “Intermediate” scenario walks through the creation and design of a report more commonly seen in production, a master-detail report.

Intermediate Scenario In this scenario, the application needs a master-detail report with drill-down capabilities; users wish to select an item from a high-level view (the “master” report), select it, and be greeted with a host of informational data about the item selected in another view (the “detail” report).

The report for this scenario is created by creating a Blank Report in Crystal Reports. A blank report form will be generated in the designer (the Database Expert will open immediately after clicking “OK”; for now, just ignore it, but don’t close it):

As you can see, it’s not unlike other IDEs you’re probably familiar with—the panel on the right is the Explorer, where major elements of the report can be explored and referenced, and the center area is the design view of the report itself. (As we populate the report with fields from a table, a new view will open up, previewing the report in a more WYSIWYG fashion so you can ensure that the report will look the way it should.)

If the Database Expert is closed (perhaps you clicked “Cancel” in the dialog that came up just after creating the new report), bring it up by selecting Database|Database Expert from the menubar at the top. Navigate once again to the Xtreme database in the Data connection tree on the left, and open it if it isn’t already opened. (If you have a large number of ODBC data sources, scrolling through them all can become tedious—feel free to right-click on the Xtreme node and select “Add to Favorites” so it will be available under the Favorites node in the Data connection tree.) Select the “Top Customers” view from underneath the “Views” node in the Xtreme database, and click OK to close:

At this point, the Database Fields node in the Field Explorer to the right will become expandable, and when expanded will contain the fields that are available to be placed within this report:

Building a report from scratch involves manually placing the report fields from the Field Explorer (at right) into the design view of the Crystal Reports designer. Simply drag the following fields from the Field Explorer to a position on the report itself:

• Add the following fields to the Report Header section:

o Text Object whose text is “Top Customers Drill Down Report”. Text Objects can be added by selecting Insert|Text Object from the menubar at the top of the application. Place the Text Object to the left of the Header area, fill in the text, and stretch the size of the TextObject

box so all the text can be seen.

o Insert a Print Date field object just to the right of the Text Object. The easiest way to insert a Print Date field object is to drag one from the “Special Fields” node (Print Date) in the Field Explorer to the Report Header section.

o Insert a Print Time field object in much the same manner, again just to the right of the date object just inserted.

• Add the following fields to the Group Header section:

o From the menubar, select Insert | Group… and at the Grouping dialog that opens, select the Top_Customers Country field. This will be the “master” view, looking at all of the Top Customers by country first. (We’ll let people drill in on the details of each country first in a few minutes.)

o Next, right-click on the “Running Total Fields” node in the Field Explorer, and select “New” at the context menu that pops up. This will allow you to create a new Running total for the group. In this particular case, we want to see the total sales of the Top Customers by Country, so in the Running Totals dialog that follows, just select the Top_Customers Last Years Sales field and hit the “>” button to use it. The default operation, “sum” is sufficient. When you click OK, a new field will have been added to the Report Explorer, usually by the name of RTotal0. Simply drag this field to the Group Header section, right next to the “Group #1 Name” field introduced by the last step.

• Add the following fields to the Details Section of the report:

o Individually drag the Customer Name, Last Year’s Sales, Contact First Name and Contact Last Name fields into the Details Section of the report. Note that Crystal Reports will also add column headers right above the location of the fields in the Details Section.

o Lastly, right-click on the “Details” section in the left-hand panel (directly underneath the “Group Header” text), and select “Hide (Drill Down OK)” in the context menu. This is what will hide the details from the master report, allowing users to double-click on just the items of interest to them.

When finished, the Crystal Report designer should look something like the following:

Save this report as “MasterDetail.rpt”.

Next, we need to deploy this report as part of a web application. As with the Basic Scenario, create a new web application in the Tomcat server (or reuse the existing one we created earlier—creating a new one will reinforce the deployment steps necessary to get Crystal Reports Java Reporting Components to work in a J2EE environment, reusing the existing one will get you up and running more quickly), and again go through the steps listed above:

1. Copy the .jars to /WEB-INF/lib

2. Copy the crystalreportviewers10 subdirectory and mark up the deployment descriptor accordingly. Remember that this needs to be a <context-param>, not a servlet <init-param> value.

3. Copy the CrystalReportingEngine-config.xml file to /WEB-INF/classes and change its “reportlocation” element to be “..”.

4. Copy the MasterDetail.rpt file into /WEB-INF.

Now, however, when we create the intermediate.jsp page that will be used to display the report, we’ll need to take few more steps to make this application work accordingly.

5. Create the JSP page to reference the Crystal Reports tag library, and use two of the provided tags to configure the viewer:

<%@ taglib uri="/crystal-tags-reportviewer.tld" prefix="crv" %>

<crv:viewer viewerName="" reportSourceType="reportingComponent">

<crv:report reportName="MasterDetail.rpt" />

</crv:viewer>

6. Configure the /WEB-INF/web.xml deployment descriptor to understand the Taglib URI reference and redirect it to the appropriate TLD tag library descriptor file:

<taglib>

<taglib-uri>/crystal-tags-reportviewer.tld</taglib-uri>

<taglib-location>

/WEB-INF/crystal-tags-reportviewer.tld

</taglib-location>

</taglib>

After modifying the deployment descriptor, make sure to copy over the .tld file itself from C:\Program Files\Common Files\Crystal Decisions\2.5\java\lib\taglib.

When executed, the report will appear something like the following:

And when the user chooses to drill down on one particular country in the report, the viewer will change to display something similar to the following:

Scenario Conclusion In this scenario, we created a master-detail report to show users rolled-up summarizations of data elements, and yet allowed them to “drill down” into the particulars of each category as the mood or need arises. Doing so provides a powerful way of allowing users to remain at a high level when first looking over a report, yet still home in on particular details when necessary, all within the same report.

We also made use of the Crystal Reports Java Reporting Components tag library, which simplified the display of the report itself. Although the rendered display would be identical to that which would be obtained by calling the Java code directly (as we did for the Basic scenario), this approach is generally much simpler and cleaner, which is in keeping with the general philosophy of JSP.

In the next scenario, we will build a report that uses reporting to produce a “document”, suitable for use in legal work, by exporting the report’s results to Adobe Acrobat PDF format rather than HTML. In addition, we’ll customize the data returned at runtime by passing a parameter (which we’ll just take off of the query string, but could easily be passed in via a form instead) to the report to specify which customer’s current orders to display.

Deployment Deploying Crystal Reports has already been discussed to a certain degree, in that we’ve included the report as part of a Web application’s deployment footprint by referencing the report from the webapp’s WEB-INF subdirectory, but other deployment considerations frequently arise and require discussion.

Database Credentials Frequently, we won’t want to store a report’s database login credentials as part of the report, because either the credentials aren’t known at report execution time (perhaps the data returned from the report will vary depending on to whom the report is being shown) or because we want to avoid the possibility of an attacker somehow gaining access to the report file and learning passwords from it. In these scenarios, we want to obtain database credentials at runtime, and pass those in to the report before executing it.

Doing so is relatively trivial—presuming that the following JSP page is the target of an HTML form that asks for the user’s userid and password in “userid” and “password” fields respectively, you can see that passing in database credentials to the report is as simple as creating a ConnectionInfo object, setting the username and password properties accordingly, putting it into a ConnectionInfos object, and passing that ConnecitonInfos object to the viewer before executing the report:

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

com.crystaldecisions.reports.reportengineinterface.*,

com.crystaldecisions.sdk.occa.report.data.*,

com.crystaldecisions.sdk.occa.report.reportsource.*" %>

<%

CrystalReportViewer viewer = . . .;

// set credentials information

ConnectionInfo ci = new ConnectionInfo();

ci.setUserName(request.getParameter("userid"));

ci.setPassword(request.getParameter("password"));

ConnectionInfos connections = new ConnectionInfos();

connections.add(ci);

viewer.setDatabaseLogonInfos(connections);

// . . .

%>

When the viewer now executes, it will do so using the database credentials passed in via the indicated parameters. (It goes without saying that you need to make sure that the “password” field is appropriately hidden from prying eyes, probably by sending this form over HTTPS, depending on your particular network topology and security needs.) You also would want to ensure that any failed login attempts are tracked, so as to guard against brute-force attacks against the database, one of the usual security considerations for a web application.

Passing Parameters to Reports In some cases, a report will want to have input criteria passed into it obtained from the user rather than hard-coded within the report. Again, this can be done fairly easily by making use of the Crystal Java API, passing in Parameter objects containing the data captured from the user, usually from some form of HTML form-based input. Doing so is fairly straightforward; assuming that the user-entered data is in an HTML form field called “country” (indicating the Country value to use when restricting the report data to display), the following Java code would set up the appropriate parameter to the report:

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

com.crystaldecisions.reports.reportengineinterface.*,

com.crystaldecisions.sdk.occa.report.data.*,

com.crystaldecisions.sdk.occa.report.reportsource.* " %>

<%

CrystalReportViewer viewer = . . .;

// Passing parameters

Fields fields = new Fields();

ParameterField param = new ParameterField();

param.setReportName("Report"); // must always be set, even if just to ""

param.setName("Country");

Values vals = new Values();

ParameterFieldDiscreteValue val = new ParameterFieldDiscreteValue();

val.setValue(request.getParameter("country"));

vals.add(val);

param.setCurrentValues(vals);

fields.add(param);

viewer.setParameterFields(fields);

%>

Notice that each ParameterField can have multiple values associated with it; although not used in this scenario, this is to allow for range values to be passed in as well as specific values, such as a range of names to use (as opposed to a particular name) when querying the database. This provides a huge range of flexibility in reporting that would be difficult to create directly without complicated SQL queries.

Exporting Reports Frankly, not everybody who reads reports adores the HTML format. HTML itself, while a powerful markup language (particularly when combined with CSS or DHTML), simply cannot provide the kind of presentation capability that many users will demand, especially when looking to print reports to paper. In these situations, it would be far better if the report could be generated to a more presentation-friendly technology, such

as Adobe Acrobat Portable Document Format (PDF), or Microsoft Rich Text Format (RTF).

Fortunately, Crystal Reports Java Reporting Component provides for such capability; in essence, the reporting component becomes a renderer of PDF and/or RTF files, rather than just HTML, and if the user has the Adobe Acrobat Plug-In or Microsoft Word Viewer installed into their browser, can browse these reports in a far richer format than just plain HTML.

Exporting a report to PDF or RTF is a matter of using a different “viewer” component to execute the report against, as shown below:

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

com.crystaldecisions.reports.reportengineinterface.*,

com.crystaldecisions.sdk.occa.report.data.*,

com.crystaldecisions.sdk.occa.report.reportsource.*,

com.crystaldecisions.sdk.occa.report.exportoptions.*" %>

<%

String report = "document.rpt";

IReportSourceFactory2 rptSrcFactory = new JPEReportSourceFactory();

IReportSource reportSource = (IReportSource)

rptSrcFactory.createReportSource(report, request.getLocale());

ReportExportControl exportControl = new ReportExportControl();

ExportOptions exportOptions = new ExportOptions();

exportOptions.setExportFormatType(ReportExportFormat.PDF);

PDFExportFormatOptions pdfexpopts = new PDFExportFormatOptions();

exportOptions.setFormatOptions(pdfexpopts);

exportControl.setReportSource(reportSource);

exportControl.setExportOptions(exportOptions);

exportControl.processHttpRequest(request, response,

getServletConfig().getServletContext(),

null);

exportControl.dispose();

%>

Doing so to RTF would set the export format type to ReportExportFormat.RTF, and use an RTFWordExportFormatOptions instance rather than the PDF one shown above. Note that the format options class carries a number of variables with it, such as the starting and ending page number to export. (Officially, one should use the IPDFExportFormatOptions or IRTFWordExportFormatOptions interfaces instead of their concrete subclasses, but the two, as of this writing, are one and the same.)

Summary and Conclusions This document introduced Crystal Reports 10 for J2EE applications through four common reporting scenarios. The scenarios built upon one another. Each sample report described one or more features and discussed how to implement each feature in the report.

The Basic scenario created a simple report listing customers from the sample database. Report Experts did most of the work designing the report. Data was retrieved directly from the customers table, and was displayed via the Java Reporting Component API.

Drill down capabilities was the highlighted feature in the Intermediate scenario. Drill down enables users to view the detail records that make up a summary record. This report introduced on the idea of retrieving data from views, as well as the JSP Tag library supplied with the Java Reporting Component.

The Sub-report scenario demonstrated embedding a report within a report. Performance considerations were accounted for by configuring the sub-report to load on the click of a hyperlink.

The Document scenario highlighted Crystal’s exporting features. Legal documents were created by exporting a report to PDF format and displaying the PDF data in a Web browser.

This startup guide touches on many features available with Crystal Reports 10. These features are designed to ease reporting development and deployment for programmers and enhance report presentation and functionality for end users.

About the Author

Citigate Hudson is a provider of custom database applications and a Microsoft Gold Certified Partner for business intelligence solutions. See their website at www.citigatehudson.com.