August 2002

Crystal Enterprise Java SDK: Release Notes

Welcome to the Crystal Enterprise 8.5 Java SDK, a functional set of Java interfaces designed to work with the Crystal Enterprise system. This Java SDK can be deployed on MS Windows^TM, Sun Solaris^TM or IBM AIX^TM operating environments and provides developer features which include:

• Access to Crystal Enterprise client functionality

• Access to Crystal Enterprise administrative functionality

• A server-based DHTML viewer component

For those organizations that need to integrate CE functionality with their existing server-based Java applications, the CE 8.5 Java SDK offers a seamless and flexible solution.

Contents

Installation 
    Supported Platforms
    Notes
Notes and Limitations

The notes contained in this document cover important information pertaining to this release of the Crystal Enterprise 8.5 Java SDK. This includes installation notes, details regarding issues that are known to exist with this release, and important information for existing Crystal Decisions customers.

Please read the entire document before performing the Crystal Enterprise 8.5 Java SDK install and be sure to visit the Crystal Enterprise support web site at http://support.crystaldecisions.com/whatsnew for any additional notes and information that may become available following the release of this document. 

Installation

Supported Platforms

The following tables detail the platform support available for the CE 8.5 Java SDK.

* Limited testing occurred on this platform.

Notes:

• Netscape 4.78 Browser Limitations

• Due to limitations with Netscape 4.78, users will not be able to search for text or drill down in subreports when viewing reports using the CE 8.5 Java SDK.

• The CE 8.5 Java SDK samples utilize UTF-8 encoding which will limit functionality within the samples when viewed in Netscape 4.78.

• For full functionality with the CE 8.5 Java SDK, we recommend that Netscape users upgrade their browser version to Netscape 6.2.

• Based on the platform requirements for BEA WebLogic and IBM WebSphere, Sun’s Java HotSpot™ Server VM is not recommended for use with the CE 8.5 Java SDK. Sun’s “Client JVM” (the Hotspot JVM without the -server argument activated) is fully supported.

• Please refer to the file InstallingWebExamples.pdf for instructions on installing the web examples provided with this release.

Notes and Limitations

• While it is initializing, the Crystal Cache Server will be unavailable to all clients for a minimum of 80 seconds after being started. During this time, no viewer requests will be processed by the server.

• When using WebLogic's IIS proxy, users who attempt to export to Excel or Word using the "In-Frame Client" sample will find that this does not work. To correct this behavior, users will need to manually edit the file ...webdemo/reports.jsp by including the JSESSIONID in the URL which points to the export servlet. (See following sample code in bold): 

//DISPLAY EXPORT ICONS
String jsession = ExamplesUtil.getCookieValue(request.getCookies(), "JSESSIONID");

out.write("<td align='right'>");

out.write("&nbsp;&nbsp;<a href='exportreport?format=MSWord&errorpage=" + WebDemoUtil.ERROR_PAGE + "&sessionexpiredpage=" + WebDemoUtil.LOGON_PAGE + "&id=" + toViewID+ "&JSESSIONID=" + jsession + "'; target='main'><IMG border='0' SRC='"+ExamplesUtil.getLinkPath(request)+"images/word16.gif' height=16 width=16></a>");

out.write("&nbsp;&nbsp;<a href='exportreport?format=MSExcel&errorpage=" + WebDemoUtil.ERROR_PAGE + "&sessionexpiredpage=" + WebDemoUtil.LOGON_PAGE + "&id=" + toViewID+ "&JSESSIONID=" + jsession + "'; target='main'><IMG border='0' SRC='"+ExamplesUtil.getLinkPath(request)+"images/excel16.gif' height=16 width=16></a>");

• The samples provided with the CE 8.5 Java SDK are written to handle all submitted data as UTF-8. To have the system successfully interpret any Japanese data that may be submitted, users will need to perform the following:

On WebLogic:

Add the following character set in the web.xml file:

<context-param>
     <param-name>weblogic.httpd.inputCharset./*</param-name>
     <param-value>utf-8</param-value>
</context-param>

On WebSphere 4.0:

Users will need to modify the file "properties/encoding.properties", located in the WAS_ROOT directory. Configure the file to match the encoding for the desired locale. (i.e. To use UTF-8 for any locale, set the file content as: en=UTF-8 fr=UTF-8. 

Note: When running WebSphere 4.0 on Solaris or AIX, users will also need to make sure that the user locale is set to a UTF-8 based locale before starting the application server.

On Tomcat:

Add the following line to the servlet or JSP after the response content type has been set and before any calls to request.getParameter:

            request.setCharacterEncoding(response.getCharacterEncoding());

• The WebExamples samples will not be available to customers using WebSphere 3.5.2. (Users who attempt to deploy the WebExamples.war file will be returned an error stating that the resource bundles cannot be found.)

• WebLogic 6.x: WebExamples Deployment/Configuration

When deploying the WebExamples application on WebLogic, it will be necessary to configure a WebLogic specific deployment descriptor in order to set the cookie path of the JSESSIONID cookie used by WebLogic to track user sessions. 

If the cookie path for the JSESSIONID cookie is not set (thereby defaulting to ‘/’), the application server will fail to store session objects once the user’s session has expired and the browser closed. (i.e. The session objects would be created for any subsequent user access will not be stored by the application server.)

In this scenario, users will need to delete all cookies on the browser to avoid session tracking errors that may result in an unwarranted increase to the Crystal Enterprise user session count. (This may lead to licensing issues.) Please refer to WebLogic documentation for details on how to configure WebLogic.

Note:

Even after following the procedure above to ensure that a valid cookie path for the JSESSIONID cookie is set, this issue is known to persist on Netscape 6.x. When using Netscape 6.x browsers, users will need to clear the browser’s cookie store in order for the sample applications to function properly.

• Viewing Reports using Sample Applications

With some deployment and configuration combinations, Broken Pipe or Socket exceptions may occur when viewing reports. These exceptions do not interfere with normal viewing operations and are commonly observed in web applications that utilize Servlet technology. In the case of WebLogic, the appearance of these exceptions indicates that the application server has detected (and recovered from) an interrupted HTTP request.

• In the IReportGlobal interface page, the documentation makes note of two methods: getEmbeddedLinkURL and setEmbeddedLinkURL. These methods do not exist in the current CE Java SDK and should be ignored when reading the documentation.

• The current DHTML Viewer implementation does NOT fully support special alphanumeric characters (i.e. "@", "?", "#", etc.). We recommend that users use URL encoded versions of any special characters when they are used in a parameter value. (e.g. “?” = “%3F”)
  
  Note: Parameter values which include the "&" (when used as the first or middle character in a string), "+", and "%" characters may not return expected values in this release. (This applies even when the character is URL encoded.)

• On systems with large numbers of clients viewing reports with charts or images, the following error may occur when running the Sun 1.3.1 HotSpot JVM on Solaris or Windows NT:

java.lang.OutOfMemoryError <<no stack trace available>>

This error is generated as a result of not having enough space in the JVM heap's "young generation". (For an explanation of the Hotspot heap generations, please refer to the Sun web site at http://java.sun.com/docs/hotspot/gc/index.html.)

To increase the size of this part of the heap, use the "NewSize" and "MaxNewSize" options as described in the JVM documentation (http://java.sun.com/docs/hotspot/VMOptions.html). Testing has shown that a "young generation" size of 128MB is adequate for viewing with 100 concurrent users, but results may vary and tuning may be necessary to determine the optimal value for each deployment.

If increasing the size of the "young generation" is not an option, it is possible to serialize image conversion. To change the number of image conversion threads, set the Java system property: "crystal_image_converters" to an integer value. The default value is 4. (Note: This approach is strongly discouraged as it will negatively impact the performance of the system.)

• The CE 8.5 Java SDK uses the Apache Log4J library to provide logging functionality. By default, the SDK will use its own built-in configuration for logging. However, the SDK provides a number of options to change this configuration or work with existing Log4J configurations.
  
  The SDK provides four built-in configurations to choose from - basic, advance, detail & verbose. The default is to use the basic configuration. To use another built-in configuration, specify the configuration name using the system property: 

crystal.enterprise.trace.configuration

For example, from Java code:

System.setProperty("crystal.enterprise.trace.configuration", "verbose");

Alternatively, the SDK can configure Log4J using a configuration that users provide. Users can pass the URL of a configuration file to the SDK using the crystal.enterprise.trace.configuration property. This file will be loaded using Log4J's “PropertyConfigurator”. Refer to the Log4J documentation for more information regarding the format of this configuration file. 

If your application already configures Log4J, you can tell the SDK to use your existing configuration by setting the system property crystal.enterprise.trace.override to true. The SDK's logging uses a Log4J naming hierarchy under com.crystaldecisions, so it is possible to add logging settings specific to the SDK in your own configuration file.

Finally, note that it is possible to tell the SDK to not use Log4J at all by setting the system property.

• If one or more invalid parameter values are set for a report, users who attempt to programmatically call the getHtmlContent method (in the ServerControl abstract class, which is inherited by CrystalReportViewer class) may encounter unexpected results. (For example, the HTML tags for a frame size may have unexptectedly small values.)

• A known globalization issue exists with the provided sample servlet "ViewReportServlet". This issue will prevent report prompt parameters from working correctly when users are logged into the system with a user name containing non-ASCII characters (e.g. Japanese characters). In order to correct this problem, edit the source file “ViewReportServlet.java” as follows:
  
  At line 134, remove the following two lines:
  
  String userid = (String) request.getSession().getAttribute("userID");
  viewer.setURI(request.getRequestURI() + "?userid=" + userid + "&id=" + id + "&errorpage=" + errorpagefile + "&sessionexpiredpage=" + sessionexpiredpage);
  
  Replace with:
  
  viewer.setURI(request.getRequestURI() + "?id=" + id + "&errorpage=" + errorpagefile + "&sessionexpiredpage=" + sessionexpiredpage);
  
  At line 186, remove the following two lines:
  
  String userid = (String) request.getSession().getAttribute("userID");
  viewer.setURI(request.getRequestURI() + "?userid=" + userid + "&id=" + id + "&errorpage=" + errorpagefile + "&sessionexpiredpage=" + sessionexpiredpage);
  
  Replace with:
  
  viewer.setURI(request.getRequestURI() + "?id=" + id + "&errorpage=" + errorpagefile + "&sessionexpiredpage=" + sessionexpiredpage);
  

• When setting the input charset type for WebLogic, any users who attempt to submit a query using the Query Builder will find that the operation fails with an “error 404” error message.

• When using the CE 8.5 Java SDK with WebSphere 3.5.2, users will not be able to export report files to PDF format. 

© 2002 Crystal Decisions Inc.