Tour of the Java API

Using JReport Server with an existing application

There are three ways to use JReport Server with an application:

The JReport Server Java API classes provide thousands of methods, each having a Javadoc entry describing the method and parameters. It is this library of classes and methods that is explained below, showing the relationship of classes to particular functional areas.

This tour section categorizes the Java API classes by functionality making it easier to find specific methods to use for particular situations.

Java Application Programming Interface (API)

JReport Server provides a library of classes and methods called the Java API.

The major functional areas in the library are categorized below into sections.

Each functional area will show the class or interface name and have a general description. Below that will be a list of common methods, and other information as needed.

Initializing and connecting to JReport Server

Every program that uses JReport Server Java API must start with calls to ensure an instance of the server is running, and then obtain a handle to the server for use in later API calls.

Class: jet.server.api.http.HttpUtil - This class provides a variety of utilities for programs running within a Java Servlet container.

Additionally, the two most commonly used methods of the Java API are in this class. These two methods must be called by any program that wants to use JReport Server in order to initialize and connect to JReport Server. These will still be used by programs that run outside a servlet container.

Security

Every web application must manage access control, identity of a visitor, permissions for a visitor, and maintain this across multiple HTTP Requests that define the web session for the user.

JReport Server provides built-in methods for doing this based on a protocol using HTTP Authentication and query parameters to pass in log-in credentials. The security mechanism includes a framework system that allows application developers to write code to co-operate with JReport Server's built in system so that existing applications can provide the security functionality.

Event Framework - Task Listener

JReport Server uses an event framework model that allows the application to provide methods that are called at various points in the processing of requests in JReport Server. These include calls to methods before a report is run, after the parameters are entered by the user to validate the parameters or generate new derived parameters, and after a report is run to log information. By using these methods you can keep detailed logs of information about the report in addition to the logging information that JReport provides.

This Java interface defines a class that applications developers can implement and deploy to provide actions tied to processing events happening.

Engine API

JReport Engine allows you to run reports directly in your application without connecting to a JReport Server instance. As long as you don't need the JReport Server features such as Page Report Studio, security and scheduling then this is an efficient way to embed reporting into your application.

NLS

This Java interface defines an implementation you can build to provide your own methods to do data mapping and text replacement. The implementation that is provided by JReport Server works out of the box, but can be changed easily.

Design API

The JReport Server Design class and the subclass MultiUserDesigner allow a developer to write programs that create and modify reports with API calls that are fully compatible with reports you create and modify using JReport Designer.

The MultiUserDesigner class should be used when there is a possibility of more than one user running the program to create reports at the same time. The common methods in the Design API and MultiUserDesigner API are all the same, other than including a user id parameter in the versions in the MultiUserDesigner class. However; Design API supports many more features such as multiple tab reports and tabular layout reports.

The most important concept when using a program to create reports is to define the report structure so that it matches the organizational hierarchy used by JReport Designer.

Here is the standard set of hierarchy to use:

Many other structures are possible within these combinations because charts, crosstabs and tables can be inserted into banded panels.

Catalog API

The Catalog class and the subclass MultiUserCatalog have methods that allow application programs to modify any of the properties stored in the catalog such as formulas, summaries, queries and DBMS connection information. The two class APIs are the same other than the multi-user version includes a user name so multiple users updating the catalog will not collide with each other. You would want to use this if you were modifying a catalog before running it on JReport Server. If you are creating the catalog and reports to deploy to the server, you should use the single user version. You can also use the Catalog class API to dynamically build Business Views, Report Cubes and Business Cubes for ad hoc reporting. Report Cubes and Business Cubes are referred to as Business Logic in the Catalog API.

User Defined Formula - UDF

User defined formulas allow developers to create their own formulas to use in JReport just like the formulas created with the formula editor. The example has some useful functions to read and write to files on the server, such as for logging usage.

User Defined Data Source - UDS

User defined datasources allow developers to build a java.sql.ResultSet with custom code that JReport Server will use exactly the same as how JReport Server uses a JDBC returned ResultSet.

Resource Management

The ResourceManager class provides methods to control all aspects of deploying resources to the server and managing resources that are already deployed. Resources include folders, catalogs, reports, and library components.

It does not include publishing results to the version system which are handled by jet.server.api.RptServer.

When resources are deployed, the application can set the permissions at the same time. Folder permissions are automatically applied to all contents deployed into the folder unless explicitly overridden.

Trigger Manager API

The TriggerManager class allows the application code to fire a trigger that will start running all of the scheduled tasks waiting on the trigger.

Run Report - RptServer API

This RptServer class is at the core of JReport Server. Although it is documented as a Java interface, it is not intended to be replaced by a custom implementation built by developers. This section will talk about it as a Java class. The class provides methods to start and stop JReport Server, to get information about deployed resources and to run and schedule reports. Report results can also be saved as resources using these methods.

See the section above about initialization and connecting to the Report Server to see that an instance of this class, or the subclass HttpRptServer, is needed by an application program before any other API methods may be called.

E-mail

This class is used by programs that want to interface to an SMTP server to export results to email as attachments or as embedded reports in the email body.

Remote File Service

This class is used by client programs that run a report on a remote JReport Server but then want the generated exported result such as PDF or Excel file to be available to open locally on the client computer.

Remote Method Invocation - RMI

This class is used by programs that need to request reports to run on a remote server and to copy the results to the local system. The report can be run asynchronously when using the timeout option. Programs written to access RptServer or RemoteRptServer are identical except for initialization so it is easy to write an application that tries to connect remotely before starting a local RptServer.

Schedule Report using RptServer

This class allows programs to add, modify and delete schedules based on time or triggers.

Remote Cluster Dispatcher

The RemoteDispatcher class allows the user's remote application to determine the load balance algorithm, and remotely dispatch reports to be run on specified servers.

Clustering

The Cluster class provides methods to allow the user to build their own algorithm for balancing server loads by assigning new reports to run onto the desired server.

Page Report Studio API

This class allows applications to directly control the options and features provided to the user when using Page Report Studio to view reports.

- jet.web.dhtml.DHtmlAPI

Server Configuration

This class allows applications to configure the server similar to the JReport Administration Console. For programming examples use the actual JSP pages under public_html\admin.

- jet.server.api.admin.cfg

Server Monitor

JReport Server Monitor is a client application that can be downloaded for free from the JReport downloads page. It allows you to monitor activity on a single server or on an entire group of servers in a cluster. The API can be used to start and stop servers as well as configure properties on them remotely.

- jet.server.api.monitor

Server Profiling

This is the class used by JReport Server to implement Server Monitor. It allows your application to catch the same types of resource use as Server Monitor using JMX technology.

- jet.server.api.profiling

Server Cached Reusable Data (CRD)

This class is similar to scheduling of reports. The application can schedule just the cached result data and have it available for any number of reports to use it. Often it is for datasets that many reports might need such as month end sales reports.

- jet.server.api.crd

JSP and URL Samples

JSP_DHTMLRunAndExport

An example of using JSP to build URLs to run a report in Page Report Studio. The user can choose the report to run then choose to export it to other formats such as PDF and download it to their client computer. The user can also call a search function to search the current report for specific content. To run the demo, copy the entire contents of the folder to where JSP can be run, for example, <install_root>\public_html, a folder named demo is added, and you can run the demo using the URL http://localhost:8888/demo/main.jsp.