Tour of the Java API

Using JReport Server with an existing application

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

• Use the web application composed of JReport Server JSP pages. Allow users to browse to the existing web pages for an interactive session to make report requests, rather than write new programs to offer special features based on calls the Java API. The web application components offer a full set of report functions as well as listing available report resources based on the user's identity and permissions. These can be used with an application built with any technology including .NET and HTML web pages.
• Use the compiled servlets to make direct requests by URL. Although not technically an API, they serve the same purpose. Action requests are the method calls, with query parameters similar to method parameters. The set of servlet actions is limited to running, scheduling and viewing results. These can be used with an application built with any technology that can request a URL including HTML web pages, .NET applications and Java web applications.
• Use the Java API classes and methods. They are called directly from a Java program to extend existing applications by building in access to JReport functionality. These same Java API classes and methods are used by JReport servlets and JSP web pages. Each Java API method has a Javadoc entry that describes how to use it.

  Every function of JReport is available through classes in the Java API including creating and modifying catalogs and reports, providing security such as single sign on (SSO) uthentication and authorization, running reports, scheduling reports and viewing results.

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.

• Method: HttpUtil.initEnv(); - initialize and start the singleton JReport Server running on the machine which all programs will access.
• Method: HttpUtil.getHttpRptServer(); - connect to the running JReport Server and return a handle to the server to use in future API calls.

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.

• Control access to web pages
  • Class: jet.server.api.http.HttpUtil - This class provides a variety of utilities for programs running within a Java Servlet container.
    • Method: HttpUtil.checkLogin(); - This method only returns when a validated JReport User is logged into the web session. If a user is already logged in, it returns true. If not, it tries to validate and login a user based on credentials in the current HTTP request. If no logged-in user can be identified, it will send a response to the browser to perform an HTTP Authentication to obtain credentials, using the browser login dialog form. The credentials are sent back to the same JSP page in the next HTTP Request.
  • Class: jet.server.api.http.HttpUserSessionManager - This class provides methods that help to create and manage the UserSession associated with a logged in user.
    • Method: HttpUserSessionManager.checkLogin(); - indicates if a validated JReport User is logged into the web session. If no user is logged in, it tries to validate and login a user based on credentials in the current HTTP request. It does not automatically send a response to the browser to perform an HTTP Authentication.
    • Method: HttpUserSessionManager.sendUnauthorizedResponse(); - sends an Unauthorized response (HTTP 401) to the browser, which initiates a HTTP Authentication process to obtain login credentials from the next HTTP Request.
  • Sample code: APISecurity\LoginLogout\loginIndex.jsp - entry point page for a group of JSP pages that exercise these two versions of checkLogin() to demonstrate how they work. Read the comments in the JSP files.
  • Network security: Using the checkLogin() system for controlling access to the web pages is not an airtight security protocol because login credentials in the HTTP Request are in an insecure stream. If this system is used for production outside a firewall, the network should be secure with URLs to the web pages using https (SSL) instead of http. Secure Socket Layer (SSL) can easily be configured using the JReport Administration Console.
• Single Sign On - Access control to the JReport web pages is based on logging in to the JReport web session with a user name and password. In the standard setup, JReport Server will cause a popup login dialog on the first attempt to run a JReport web page in a session. This should not happen when a logged-in application user does their first attempt to run a JReport web page. JReport Server provides a framework to allow Single Sign On,, to avoid this experience. When Single Sign On is turned on, JReport will just ask the application for the current user name and not challenge the user.
  • Interface: jet.server.api.http.HttpExternalAuthorized. This Java interface defines a class that application developers can write and deploy within JReport Server that co-operates with the checkLogin() methods that control access to web pages.

    This Java interface defines a protocol for the application to tell JReport Server that a user is already logged into the application's web session so that checkLogin() will log in that user to JReport Server. It also has a protocol for asking the application to handle the case where no user is logged in, so that the application can direct the user to the application's login workflow. This allows the application to provide the single place where a user logs into the web application. This also prevents checkLogin() from using the HTTP Authentication process.

    Single Sign On is turned on when the implementation of this Java interface is compiled and deployed as a jar, and JReport Server is configured to use it.

    • Method: HttpExternalAuthorized.getExternalAuthorizedUser(); - return the JReport User ID (user name) for the user who is currently logged into the web session.
    • Method: HttpExternalAuthorized.handleUnauthorizedRequest(); - build a response to send to the browser redirecting the user to the application login page, and return a true to tell JReport Server to use that response, instead of the HTTP 401 Unauthorized response.
  • Sample code: APISecurity\SingleSignOn\CustomHttpExternalAuthorized.java - example implementation of the interface. Read comments in the source for detailed explanations on the application security model it uses.

    This implementation is perfect for deploying using the command line method of registering it with JReport Server, or when using a servlet to register it with JReport Server by making an API call. Because of limitations in the JSP parser, it is not usable as the class to use when registering it with JReport Server using a JSP page to make the API call.

  • Sample code: APISecurity\SingleSignOn\com\example\MyExternalAuthorized.java - example implementation of the interface. Read comments in the source for detailed explanations on the application security model it uses.

    This implementation is written as a package with a multi-tier package name. This can be registered with JReport Server as the implementation in all possible cases, include from code in a JSP page that calls an API.

  • Turning on Single Sign On - JReport Server will use Single Sign On when the implementation class of the java interface is registered with it.
    • Register in command line
      Set a system property in the command line that starts up your application or JReport Server. The property jrs.httpExternalAuthorized should be set to the name of the implementation class. For example, use -Djrs.httpExternalAuthorized=CustomHttpExternalAuthorized when starting the Java JVM for the application containing the JSP pages that call checkLogin().
    • Register with Java API call
      • Class: jet.server.api.http.HttpUserSessionManager - This class provides methods that manage the UserSession associated with a logged in user.
        • Method: HttpUserSessionManager.setHttpExternalAuthorized(); - turn on Single Sign On by setting the class instance object to use for HttpExternalAuthorized. When a null value is used as the class instance to set, this turns off Single Sign On.
      • Sample code: APISecurity\SingleSignOn\CustomServlet.java - example of a servlet that sets the ExternalAuthorized using the Java API call.
    • Where to turn on Single Sign On
      The Single Sign On should be turned on for the JVM where the JSP pages are running. If the application and JReport JSP pages are running on a web server with JReport Server installed on a dedicated back end server, the Single Sign On should be turned on in the web server machine. Single Sign On access control to the web pages will be handled properly for the HTTP requests for the web pages, while access to the back end JReport Server will be over RMI, which does not use the checkLogin() or Single Sign On for access control.
  • Sample code: APISecurity\SingleSignOn\customIndex.jsp - entry point JSP page to a group of JSP pages that demonstrate how Single Sign On works. Read comments in the JSP page to learn more about the demonstration.
• Authentication - This Java interface defines a class that application developers can write that replaces the built-in user validation system of JReport. Even when using Single Sign On, the system will check that the user is valid in JReport so it can determine if the credentials identify a registered user. This Java interface is called to check if the user is valid. A custom implementation can use local DBMS data or the application's data to validate the user. Another option rather than to authenticate with JReport's built in system is to authenticate directly to an LDAP or Active Directory service.
  • Interface: jet.server.api.custom.security.AuthenticationProvider
    • Method: isValidUser();
  • Sample code: APISecurity\DemoAuthenticationProvider.java
• Authorization - This built-in package provides methods for determining authorization rights to resources based on the user's user id, group and role that have been defined using JReport Server's admin web interface for managing users, groups, and roles. Permissions to resources can be placed on any of the 3 levels, user, group or role but role is the preferred method as it is standard for Java applications and provides you with more flexibility as individual users change jobs while roles are stable for long periods of time.
  • Class: jet.server.api.Authenticator
    • Method: isValidUser();
    • Method: isPermissionOK();
    • Method: isValidAdminUser();
  • Sample code: none
• Custom Authorization - This Java interface defines a class that application developers can implement to replace the built-in Authorization (Authenticator) class. After a user has been validated as a registered JReport User, there is still the question if the user can do the operation requested against the target resource. Methods in this Java interface will be called to determine if the user has permission to do a given action against a given report resource. You can implement your own method for making this decision.
  • Interface: jet.server.api.custom.security.AuthorizationProvider.
    • Method: isPermissionOk();
  • Sample code: - APISecurity\DemoAuthorizationProvider.java
• Add/Modify/Delete Roles/Groups/Users - This built-in package allows an application to build a system to synchronize their internal system for managing user identity with JReport Server's DBMS of user identity. By default users are added to JReport Server manually using the JReport Administration interface or by synchronizing with an LDAP service. This package provides a third way, allowing you to add the users, groups and roles into JReport Server by making API calls so that you can utilize JReport Server's built-in authorization, including permissions to resources and row level and column level security. Since users, groups and roles are in the JReport Server DBMS developers are sometimes tempted to directly update the DBMS tables but this is highly discouraged. Since a running JReport Server caches the security information, any updates not using the API will be ignored until the server is restarted.
  • Class: jet.server.api.admin.SecurityAdminService
    • Method: addRole();
    • Method: addGroup();
    • Method: addUser();
  • Sample code: APISecurity\AddPrincipal\SecurityGroupCover.java, SecurityRoleCover.java, SecurityUserCover.java

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.

• Interface: jet.server.api.TaskListener
  • Method: beforeRun
  • Method: afterRun
  • Method: validateParameter
• Sample code: APITaskListener\TestTaskListener.java

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.

• Class: jet.server.api.engine.ReportEngine
  • Method: ReportEngineFactory.getInstance - Creates a report server bean
  • Method: setReportHome - There are a number of required set methods to set reporthome, catalog, report name, and so on.
  • Method: exportToPDF - There are a number of export methods available for each type of export
  • Method: runReport - Runs the report and produces a JReport rst file that can be used to export to a user viewable report
• Sample code: APIServer\APIDemoReportEngine.java

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.

• Interface: jet.util.NLSBundleInfo
  • NLSBundleInfo
• Sample code: APINLS\MyNLSBundleInfo.java

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:

• ReportSet | Reports | Report Tab | Report Body | Banded Object | Banded Header / Footer Panel
• ReportSet | Reports | Report Tab | Report Body | Banded Object | Group Header / Footer Panel | Detail
• ReportSet | Reports | Report Tab | Report Body | Chart
• ReportSet | Reports | Report Tab | Report Body | Crosstab
• ReportSet | Reports | Report Tab | Report Body | Table

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

• Class: jet.api.Designer

  The following methods are the most commonly used in Design API.

  • Method: createReportSet - Creates the ReportSet.cls file and first level of hierarchy
  • Method: addDataset - Creates a dataset handle given a data source, query and dataset name
  • Method: bindDataset - Binds the dataset to the data container which can be a ReportBody or a banded object, chart, table or crosstab.
  • Method: addReport - Add a report tab to the report set. It is the only container object that can be added to a report set.
  • Method: insertBandedObject - Creates a Banded Object structure that includes BandedObject, BandedHeader, BandedPagePanel, BandedFooter, BandedPageHeader, BandedPageFooter, and DetailPanel.
  • Method: insertSectionGroup - Inserts a group into a BandedObject or into a BandedObject Group.
  • Method: insertChart - Inserts a chart into the parent panel
  • Method: insertCrossTab - Inserts a crosstab into the parent panel
  • Method: insertTable - Inserts a table into the parent panel
  • Method: getHandles - Returns the handles of the items in the hierarchies listed above.
  • Method: insert - Inserts labels, DBFields, parameters. formulas, summaries, and special fields into the parent group container
  • Method: set - Set the attributes of the inserted objects such as text, font, foreground, format, and so on.
• Sample code: APIDesign\TestDesignInvoice.java, TestDesignGraph.java, TestInsertCrosstabIntoReport.java, TestInsertCrossTabInfoBanded, TestDesignSubreport, TestDesignEditInvoice.java, TestMultiUserDesign.java

Catalog API

The Catalog class and the subclass MultiUserCatalog have methods that allow application programs to modify 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.

• Class: jet.api.CatalogAPI.MultiUserCatalogAPI
  • Method: Designer.getCatalogAPI(); - Gets a catalog API instance for a given catalog from a Designer instance.
  • Method: insert(); - objects in catalog
  • Method: set(); - attributes of objects in catalog
• Sample code: APICatalog\TestCatalogAPI.java, TestCatalogBC.java

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.

• Class: jet.formula.javaformula
• Sample code: APIUDFormula\jet\formula\javaformula\MyFunctions.java

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.

• Class: jet.datasource.JRUserDataSource
• Class: jet.datasource.JRHierarchicalDataSource
• Sample code: APIUDS\unionUDS\UnionSample.java, UnionSampleResult.java

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.

• Class: jet.server.api.ResourceManage
  • Intention: Publish
    • Method: createFolder();
    • Method: addResource();
    • Method: addResourcesToFolder();
  • Intention: Security
    • Method: getAuthenticator().checkPrivilege();
    • Method: checkPermission();
  • Intention: Delete
    • Method: removeNode();
    • Method: removeVersion();
  • Intention: List
    • Method: getReportsInPath();
    • Method: getResultsInPath();
• Sample code: APIServer\APIDemoDeployReport.java

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.

• Class: jet.server.api.TriggerManager
  • Method: subScheduledTask();
  • Method: fire();
• Sample code: APIServer\DemoTrigger.java

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.

• Class: jet.server.api.RptServer
  • Method: runReport() - run on-demand report
  • Method: exportResult() - export to one or more export types such as PDF, HTML, and so on.
• Sample code: APIServer\APIDemoRunAndExportReport.java

E-mail

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

• Sample code: APIServer\APIDemoSendEMail.java

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.

• Class: jet.server.api.RemoteReportServerToolkit
  • Method: getRemoteFileService()
  • Method: copyFromRemote()
• Sample code: APIRemoteServer\RemoteAPIDemoFIleService.java

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.

• Class: jet.server.api.rmi.RemoteReportServerToolkit
  • Method: getRemoteRptServer();
  • Method: runTask();
  • Method: getResourceManager();
  • Method: getRemoteFileService();
• Sample code: APIRemoteServer\RemoteAPIDemoPublishRpt.java, RemoteAPIDemoRunAndExportReport.java, RemoteAPIDemoRunReportWithTimeout.java

Schedule Report using RptServer

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

• Class: jet.server.api.RptServer
  • submitScheduledTask(); - run scheduled report task
• Sample code: APIServer\APIDemoPublishReport.java and APIRemoteServer\RemoteAPIDemoPublishRpt.java

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.

• Class: jet.server.api.rmi.RemoteDispatcher
  • RemoteDispatcher();
• Sample code: APICluster\DemoRemoteDispatcher.java

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.

• Class: jet.server.api.cluster.LoadBalancer
  • Method: LoadBalancer();
  • Method: selectMember();
• Sample code: APICluster\DemoLoadBalancer.java

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.

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.