JReport Enterprise Server Getting Started

Transcription

1 JReport Enterprise Server Getting Started

2 Table of Contents Getting Started: Organization of This Part...1 First Step...3 What You Should Already Know...3 Target Customers...3 Where to Find More Information or Get Help...3 General Installation Information...4 Features Overview...5 JReport Basic Concepts % Java...6 Crossing Platforms...6 Server Basic Modules...7 Ultimate Scalability, Flexibility...7 Running as a Wrapping Web Server or Service...7 Web Application Server Integration...8 Cached and On demand Content Generation...8 Scheduled Content Generation...8 Version Control...8 JSP...8 URL...8 National Language Support...9 Security and Administration...9 Report Management...9 Security...9 Administration...9 Extensibility...9 Server API...9 Security API...9 JReport (Client) Viewer Bean/Client API...10 Cluster Feature...10 Quick Tour...11 Products Roadmap...11 Deploying Reports to JReport Enterprise Server...13 Configuring and Administering JReport Enterprise Server...14 Local Configuration...14 Remote Configuration and Administration...19 Accessing JReport Enterprise Server...19 Browser...20 Enterprise Viewer...23 Client Viewer Bean...26 Application Server Integration...26 Client API Scheduling...27 JSP Page Customization...27 I

3 Getting Started: Organization of This Part The Getting Started book provides an introduction to JReport Enterprise Server. It covers issues associated with installation, setup, and configuration of JReport Enterprise Server. It is a combination of informational topics and strategic references to various topics in the server User's Guide book. The Getting Started book has the following chapters: First Steps: Preliminary knowledge you should know in order to use JReport Enterprise Server effectively, general installation and configuration information as well as where to get more help. Features Overview: High level overview for JReport Enterprise Server's major features. Quick Tour: A summary or work flow of server reporting solutions, letting you have a very quick and better understanding of scenarios to which JReport Enterprise Server can be tailored. JReport Manual Roadmap The following picture lists the other books in the JReport Designer manual, JReport Enterprise Server manual and JREntViewer manual, and the relationship between them. We recommend that you start with the JReport Designer manual. After acquiring some report design knowledge, it is easy to learn JReport Enterprise Server in the server/client architecture. JReport Designer manual includes four books: Getting Started, Tutorial, User's Guide, User Reference. For SanFrancisco users, we have an individual manual: SanFrancisco Integration Manual. JReport Enterprise Server (abbreviated as JREntServer) manual has three books: Getting Started, Tutorial, User's Guide. In addition, the JREntViewer manual is for using JREntViewer for JREntServer. For a complete coverage of the features, operations and other information, please refer to the specific book: JReport Designer Getting Started An introduction to JReport. It covers issues associated with installation, setup, and configuration of JReport Designer. It is a combination of informational topics and strategic references to various topics in the Designer User's Guide and Designer User Reference. 1

4 Getting Started: Organization of This Part JReport Designer Tutorial Basic report building instructions. This includes the reporting features that you will find useful. The idea is that after you have walked through this Tutorial, you can easily follow the examples and build your own reports. For in depth feature coverage like building reports on XML, EJB, stored procedure, or SQL file, please refer to the Designer User's Guide. JReport Designer User's Guide In depth coverage of JReport Designer's features and general explanation of how to do different things with the product. Browse to locate the chapters that are of interest to you for step by step instructions. JReport Designer User Reference Specifications, providing technical, system and other reference information related to the JReport built in objects, built in formula functions and APIs. JREntServer Tutorial Basic Server configuration, administration and accessing instructions. After walking though the tutorial, you will be able to use the server for managing the interaction between client and server that enables activities such as scheduling and running reports. JREntServer User's Guide Procedures to get a more in depth understanding of JREntServer. Here we have shown the steps involved in advanced server features like JSP, national language support, server API, application server integration and JReport (Client) Viewer Bean. JREntViewer Manual Complete coverage of features and instructions on using JREntViewer against JREntServer. The Client API usage is also introduced in this book. SanFrancisco Integration Manual Integration notes of JReport with IBM SanFrancisco, making IBM SanFrancisco application data ready/available for reporting, step by step instructions on how to wrap SanFrancisco BO or Bean to JReport Printable Object, through which a report is built. 2

5 First Step What You Should Already Know The main purpose of these JReport documents is to explain to you how to use JReport products. It assumes that you already know: How to install JVM and launch an application with it. Your organization's scenario for reporting on your data source. Your external tools and systems such as IDE's, version control systems, database management systems (DBMS), application servers, etc. Your target programming languages. Knowledge of multi tier distributed object environment (a plus). Target Customers JReport gives every type of user a level of functionality suitable to their needs. We have a visual administration and deployment environment compatible with various tools. In addition, application developers can also take advantage of a full set of APIs. The two approaches can nicely complement each other. Our target customers include: End users without any programming experience Internet and Intranet web site developers IS Project Managers Programmer/Analysts Managers of End user Computing Where to Find More Information or Get Help Rapid changes in various technologies used to develop JReport sometimes cause certain types of help documents to become outdated, even between releases. To keep you current, the latest information is always posted on the Jinfonet website. Homepage: Contents: Products and release information: Products download center: Docs and Tutorials: Server Manual related materials: Go to the Server Manual related materials. This includes example source code files or others you need to follow our instructions for a feature. You can also find them on your local drive under %help installroot%\srv material\ if you have installed JReport Enterprise Server Help (HTML version). JavaDoc for the APIs provided in JReport Enterprise Server: Go to the JavaDoc for JReport Enterprise Server. The APIs include JReport (Client) Viewer Bean, UserAuthenticator, Server API, etc.. For Client API, please go to the JReport Viewer for Enterprise Server manual. JReport technical support center: News and release notes: 3

6 First Step Problem Reporting (for JReport Enterprise Server) If you have troubles in running JReport Enterprise Server or encounter any problems during reporting, use the following steps to troubleshoot it yourself first. 1. Check whether you meet the system requirements, see User Guide Installing and Launching JReport Enterprise Server. 2. Please describe the precise steps leading to the problem. 3. Run the batch file called "jrenv.bat" under the %installroot%\bin subdirectory. Running this batch file will generate a file called "report.env" in the current directory. Send this file to us. In addition, tell us the environment description, including machine type, CPU, memory, OS, Java version, etc. 4. Send us the log file recording the JREngine running problems. For standalone server: Please start JReport with the batch file DJREntServer.bat. Running this batch file will generate log file JReport.log in the current directory. Try to reproduce the problem, and send this log file to us. For integrated JREntServer: If your JReport Enterprise Server runs as a servlet inside other Application Server, please send us the log file generated by JReport Engine in the application server. When the JReport Servlet is installed, there will be a property file generated which is used to define the class and arguments of JRservlet, for example, if you integrated JReport Enterprise Server into Weblogic, you can find Weblogic.properties is placed in the install path of Weblogic. Please edit the file to use the option vdebug verror. Your file should contain these contents: verror=true vdebug=true logfile=file name (with full path) Then restart you application server, reproduce the problem and send us the log file. 5. Send us the log files recording the event, error, debug, access, manage etc. For standalone server: Change the configuration to record all events by starting the server configuration and administration GUI, go to Configuration Logs tab. Set all the logs to Trivial. After that, reproduce your problem and send us the log files under %installroot%logs. Or do this from the remote administration. In the address bar of an IE browser, type in: Click "Log" in the left list. Then in the activated page, set Level to be 'trivial' for each Log type (access,debug,error,event and manage). After that, reproduce your problem and send us the log files under %installroot%logs. For integrated JREntServer: If your JReport Enterprise Server runs as a servlet, in the address bar of IE browser, type in: where, Jinfonet_Sybase is the database name, JRAdmin is the servlet name. 6. To reproduce your problem of running reports with JReport Enterprise Server, we very often need your report, catalog and data information. Send us the catalog file (*.cat and *.fml) and the report file *.cls with which you have problems. In order to resolve the technical issues that you have reported, we need to access your report data so that we can recreate and analyze the problem. Your database could be very large, however, we only require access to the data returned by the query of the troublesome report. We will be happy to execute any confidential agreement with you if necessary. To extract the report data, in Catalog Browser of JReport Designer, right click the query that your report is using, select the menu item 'Create Cached Query Result'. Input the data file name and click the Save button. The query result will be saved in the file. Send us all the files (including the description file also). General Installation Information JReport installation is designed to be easy and straightforward. All installers for all products provide a wizard to guide you through the installation process. Detailed installation information and start up steps for all platforms are provided within the User's Guide. In addition, we have documents describing the procedures for integrating with the most often used web application servers. To download the installation file, go to our download center at To install the product you have downloaded, you first need to register for the evaluation key. The registration form is located at The full featured product can be used for 30 days free of charge. 4

7 Features Overview This chapter presents a run down of JReport Enterprise Server's top features and gives you some basic information about each one. These topics are intended as a high level overview. More detailed information appears in the User's Guide, which contains how to steps that explain how you can try out a feature. Browse the table of contents of the User's Guide for JReport Enterprise Server, it is easy to find the features you are interested in. However, first reading the basic ideas that JReport presents here will help you better understand and use JReport in your own systems. JReport Basic Concepts In a typical business, the reporting system is responsible for making the proper information ready for the information consumer. JReport gives you powerful and easy to use ways to extract, analyze and present data in reports and distribute those reports to the right people. JReport is a reporting solution written in 100% pure Java, it covers the whole process including fetching data, analyzing data, presenting information, distributing the result, and finally printing the result. Jinfonet Reporting Suite (including JReport Designer and JReport Enterprise Server) is a Java based business intelligence tool, used for database query, reporting and analysis. JReport Designer is the client side report designing and developing tool. Reports developed can be deployed to JReport Enterprise Server for running in the server/client mode. With JReport Designer 4.0, users can also use JReport Enterprise Server to modify or design reports on line with only a web browser. In this sense, JReport is particularly well suited for Internet and intranet deployment and use by virtue of being written 100% in Java and due to its flexible client/server architecture. Overall Architecture: 5

8 Features Overview Key benefits: Object oriented for reusability. Components defined once can be used over and over again in different configurations to create different reports. Database independent. Easy and intuitive. Focus is on creating a report generator that anyone can learn to use easily, but that can be customized in infinite ways for the experienced professional. Web enabled. Reports generated with the report writer can be accessed from Web pages, either through an embedded applet, via HTML, or via PDF. Platform independent. By virtue of being built in Java, this product can run on any Java enabled platform. Full featured. The report writer should provide all of the expected functionality for a first rate report writer, and, in addition, object oriented features that allow users to subclass existing reports and report components. JReport Enterprise Server shares the same robust Engine as that in JReport Designer, and JReport Enterprise Server blends the best of Java and Web to provide an Internet reporting solution. Any sophisticated enterprise ready report designed with JReport Designer can be run in the Server for delivering report results through the Internet or intranet, the only thing you need to do is to deploy the proper files to the server. 100% Java Utilizing the full advantages of Java architecture, JReport works with any platform, any OS, any database, any web server, and any browser. Dynamic portability, low administration costs and dynamic upgrades are key advantages that are inherent to JReport s unmatched capabilities. Crossing Platforms JReport Designer and JReport Enterprise Server are Java centric object oriented reporting tools written entirely in Java. JReport supports JDK 1.2, JDK1.3 and now JDK 1.4. Besides JDK, it works with JRE, or Microsoft Java VM. With Java's cross platform 6

9 Features Overview portability, JReport can run on virtually any platform. We have JReport Designer for Windows 9x/2000/NT version. JReport Designer does not ship a special installation package for other platforms. To install JReport Designer on other platforms, users can run the extracted class file (generated on Windows) and do a manual installation. We have provided JReport Designer installation instructions on Macintosh. Usually we do not recommend you to do this since we generally Launch JReport Designer on a Windows OS to do the report design work. The most convenient method is to deploy reports to JReport Enterprise Server for which we have a Windows version and a Unix version (Solaris, Linux, HP Unix, AIX), and the reports can be run in the server/client environment. Server Basic Modules Underlying Network Support This module maintains underlying HTTP network communication for the support to both general Internet browsers and our JReport Client Viewer. JReport Engine To fetch data from database, calculate formulas, etc. and then generate the report result. Publishing Management To publish the result of a report to HTML file, PDF file etc.. Resource Management JReport Enterprise Server provides different users with different accessing hierarchies to access files or directories from anywhere. Security Management Including user/role management and resource protection. Task Management To maintain tasks. Version Management To manage and maintain the result versions of reports, catalog, and report result. Servlet for Remote Administration To handle remote administration. Ultimate Scalability, Flexibility JReport Enterprise Server scales to meet the needs of today's demanding e Business applications. The server supports very robust multi threading and can utilize multiple CPU effectively. It has been stress tested with over 1,200 concurrent user connections and reports on ordinary PC based NT servers. Users can view and interact with JReport Enterprise Server using browsers without any applets or plug ins, making internet deployments to large user populations a snap. JReport Enterprise Server is a high performance Server that supports servlet/jsp. It also can be completely implemented as a Java Servlet and is compliant with HTTP protocol. So ideally, it can be easily integrated into any Servlet enabled application server on any platform that serves Java VM. Additionally, JReport server incorporates version control, auto caching and a scheduling service. The powerful combination of these features makes it extremely scalable. With JReport Enterprise Server, you can deliver information with unparalleled response times and performance. Running as a Wrapping Web Server or Service JReport Enterprise Server can be started from the wrapping servlet enabled web server which is contained in the JReport Enterprise Server package. Or, install it as a service of OS to run as a daemon process. 7

10 Features Overview Web Application Server Integration Being written in 100% pure Java makes JReport easy to integrate with all web applications and allows it to run on any Java enabled platform. Implemented as Java servlets, JReport Enterprise Server can be seamlessly integrated to work with other web servers such as SilverStream Server, WebSphere, Apache Server, WebLogic Server, and so on. Deploying the JReport Enterprise Server runtime as a servlet involves shipping the runtime archive files. A servlet is deployed to an application server by manually registering the servlet with the server. JReport Enterprise Server will start automatically when the host server is accessed using a URL like: JReport servlet also accesses databases and delivery output through the host server. Cached and On demand Content Generation JReport server is capable of delivering both on demand and cached content to the Web. Based on users' and application's needs, specify whether data sources should be accessed in real time as the content is requested, or whether users should view a cached report result where the data sources have been queried ahead of time. Scheduled Content Generation JReport Server incorporates an advanced scheduling mechanism that allows administrators to specify the frequency with which individual reports are generated. Version Control JReport server supports the explicit storage of multiple versions of the same report using the JReport version control system. One can thus maintain different instances of individual reports that show information relevant to different users or across different time periods. JSP JSP (Java Server Page) services will provide a high level of customization and personalization, well beyond the generic Web services of today. This will give server administrators chances to tailor our server pages according to their own preferences. URL Due to the server's URL based architecture, JReport can be seamlessly integrated with the rest of the user s Web application. We support commands in URL. With them, users can directly type in the whole URL in browsers to access the destination. The HTTP methods GET and POST are available for almost all of the commands. 8

11 Features Overview National Language Support Our reports are now adaptable for world wide users through the National Language Support feature. With the national language support, the same report can be viewed in different languages depending on the client locale. Security and Administration Report Management By virtue of JReport Enterprise Server's resource management feature, enterprise reporting applications can have their own distributed data sources and reports that are located either in the local network or over the world wide network. JReport Enterprise Server organizes them into a single tree so that if a remote user has the necessary privilege, the user can view all of the resources in the tree structure, independent of physical storage location. Security To help users effectively administrate user and report resources, JReport Enterprise Server implements security by controlling the user access to the resource. Only a user with appropriate permissions has access to a certain report. All the actions from the client end will be checked by the JReport Enterprise Server Security mechanism. Whether JReport Enterprise Server accepts or denies the access requests from clients depends on the permissions the users or roles have. Administration JReport Enterprise Server's administration is based on the HTML standard, so administration can be performed using a general Internet browser. You can access to the Administration pages on a standalone TCP/IP port. Servlet that is embedded in other Servlet enabled Web servers. Extensibility The reason we say JReport is dynamic is that it offers a high degree of both interactivity and extensibility. APIs provide this extensibility by enabling the user to leverage the components and services of JReport, building them into other applications and thus integrating JReport with your existing platform infrastructure. Server API The report server API is a set of java application programming interfaces to run reports, explore report resources, provide access control, and so on for report servers. It is mainly used for writing servlets, JSPs, and java applications with report server features. Security API JReport security mechanism is implemented on the Java ACL (Access Control Lists). To avoid having two security checks (for your system and JReport Server) and thus having to log in twice in your own system, either disable JReport security check or customize security implementation for JReport server by implementing Java interface class. Main methods for the API: Checking methods isvaliduser() isvalidadminuser() ispermissionok() Getting getrealmnames() getusernames() getauditstate() getpassword() 9

12 Features Overview Putting changepassword() JReport (Client) Viewer Bean/Client API The client side or the viewer which can access JReport Enterprise Server can be a common browser (Like IE), or JReport Viewer. You can use the GUI viewer JREntViewer for Enterprise Server. To embed the viewer in your own applications, just call Client Viewer Bean or Client API. JREntViewer (with GUI) and JReport Viewer Bean are all based on Client API. To simply access reports on the server, just call Viewer Bean. However, for the advanced viewer features like scheduling, you need to use Client API. Cluster Feature A JReport Enterprise Server Cluster is a group of servers that work together to provide cluster wide shared resource, security, schedule and version services. A JReport Enterprise Server Cluster provides the following major features: Manageability All users and resources can be controlled from a central place, remotely. High Availability When one server fails to perform, the tasks running on it will be reallocated to other servers. If one server has already been fully utilized, the tasks sent to it will be allocated to other servers. Scalability You can add or remove servers dynamically according to your requirement. 10

13 Products Roadmap The following diagram represents the current structure of JReport products. Now let us dissect the above figure and give you a detailed explanation for each part. The first part should be the report designing process. That is, you use JReport Designer to design reports. JReport Designer basically contains three components: designer, engine and viewer. The designer in JReport is easy to use and feature rich. The resources, such as data source connection, table, query, formulas, and so on, a report used are saved in a catalog file (.cat or.xml), and the Report file is saved with the.cls extension. To view the report is to initiate JReport Engine to run the report, fetch the data, and return the report result. Report result will then be displayed in the viewer. 11

14 The processes of designing, running and viewing reports as discussed above can also be achieved programmatically. When you install JReport Designer, the archive files for the three have also been installed JReport Designer API, JReport Engine Bean and JReport Result Viewer Bean. They function exactly the same as if you were operating within the GUI of JReport Designer, only that you call them in your own applications. Here the CLS file is the one saved with designer JReport Designer or Designer API. The report result that JReport Result Viewer Bean recognizes can be the result file generated with JReport Designer, JReport Engine Bean, or JReport Enterprise Server. In other words, the report result is essentially generated by JReport Engine. Once reports have been developed by various end users, you may want to manage them in a server and run them on a scheduled basis or on demand. JReport Enterprise Server (JREntServer) is once again at your service. Designed as an integration enabled reporting solution for multi tier architecture, blending the best of Java and Web, and based on our robust high performance report engine, JReport Enterprise Server can be used as a component in your Intranet/Internet infrastructure. Whether JReport Enterprise Server runs as a standalone server or a servlet inside web servers, reports deployed are run by JREngine on demand or on a schedule requested by any client. Report results or output of their formats is then transferred to the clients. JReport Enterprise Viewer (JREntViewer) is the client viewer for working with JREntServer. We also have the JReport Viewer Bean/Client API (different from JReport Result Viewer Bean which runs in the standalone mode), and this means the client 12

15 command for running reports can be done with your own code. Of course, without any requirement for your web browser (like IE or Netscape), you can directly access JREntServer. Deploying Reports to JReport Enterprise Server Once you have developed various reports, you may want to manage them in a server and run them on a scheduled basis or on demand. With the Deployment Wizard provided by JReport Designer, pre developed reports can be deployed to JReport Enterprise Server for running in the server/client scenario. 1. Load JReport Designer and open a catalog to be deployed. 2. Select the File Deploy to JReport Enterprise Server to pop up the Deployment Settings dialog. 3. Browse to choose the destination to which you are going to deploy the resouce and specify where it comes. 13

16 4. Load the resouce tree and select the reports you want to deploy to server. 5. Modify the properties and permissions of ther resouce on the corresponding tabs. 6. Click Submit to finish deploying. Configuring and Administering JReport Enterprise Server Local Configuration Assume that JReport Enterprise Server runs as an independent web server in your machine under C:\JREntServer. 1. Start JReport Enterprise Server with the following command to launch the JReport Enterprise Server Configuration and Administration GUI. If the server has been started without the Administration dialog, run the command: C:\JREntServer\bin\CmdSender w:admin admin If the server has not been started, run the command: C:\JREntServer\bin\JREntServer a 14

17 2. When the server is brought up, the Administration GUI pops up. Configure the server by clicking on the Configuration button. 3. After successful login, you will get into the Configuration dialog. Go through the tabs to configure your server. Service Specify the general information, such as Port, Active realm etc. Log Configure for the log files generation in case of problems. 15

18 Mail Configure for exporting report result to mail. 16

19 Cache Specify the maximum number of catalogs and reports to be cached. 17

20 Performance Specify catalogs, reports and Java classes to be preloaded. 18

21 Advanced Configure the advanced features, for example to enable JSP. Remote Configuration and Administration An independent port is assigned to the remote configuring and administrating request, the default is The client connects with the server through port 8889, so that the remote configuration and administration options are revealed. Click the options in the left panel to configure the server remotely and the buttons on the right panel to administer the server remotely. Accessing JReport Enterprise Server You can access JReport Enterprise Server with a standard browser or with JReport viewer (with GUI or within your application). 19

22 Browser First, start JReport Enterprise Server and then load a Web Browser (here we use IE) to visit the home page of the server. After login, you can view the resources in the server, select one and then choose the catalog and the report you would like to view. 20

23 Specify the result format. 21

24 Submit to get the result in the specified format as shown below. 22

25 Enterprise Viewer First start JReport Enterprise Server and JReport Enterprise Viewer. After connecting to the JReport Enterprise Server and successfully logging in, you can browse the entire directory as follows: 23

26 Select one report and come into the following dialog: 24

27 Click the Run button, the report will be shown as below. If the report has parameters, click the Parameters button the view it. 25

28 Client Viewer Bean Like a common browser, Client Viewer Bean can send a request from a client workstation to run and view reports on JReport Enterprise Server. The difference is that it can be embedded in your applications. Your Java application calls JReport (Client) Viewer Bean and provides the following properties: setservername ("theservername"); setport ("theportnumber"); setreportname ("thereportname"); setcatname ("thecatalogname"); setloadreport ("Yes/No"); Start JReport Enterprise Server before running the application. Then, the specified report result will be shown in the viewer of the client side. Application Server Integration JReport Enterprise Server can run not only as a standalone server, a service, but also be integrated to other web enabled application servers. The integration procedure is fairly easy. After the host application server starts, JReport server will be launched as a servlet. Clients then access JReport servlet with a URL like 26

29 Client API Scheduling Scheduling tasks can also be done through user applications by calling JReport Client API. 1. Import the classes of Client API import jet.client.api.*; 2. Set the connection information and login // set the HTTP proxy for the client. if (proxyhost!= null) { JRClient.setProxy(proxyHost, proxyport); } // set the user ID for the client. JRClient.setUser(user); // set the password for the client. JRClient.setPassword(password); JRClient.login(null, server); 3. Set properties of task and time Hashtable httask = new Hashtable(); //set properties about task info httask.put("jrs.task_class", "jet.server.schedule.jrtasks.updaterpttask"); httask.put("jrs.catalog", "/hsqldemo/tutorial.cat"); httask.put("jrs.report", "invoice.cls"); httask.put("jrs.expire_days", "30"); httask.put("jrs.if_print", "false"); //set parameter values httask.put("jrs.param$ptoday", "May 20, 1998"); httask.put("jrs.param$termsdays", "31"); //set properties about time info httask.put("jrs.launch_type", "8"); httask.put("jrs.days_id", "0"); httask.put("jrs.day", "1"); httask.put("jrs.is_weekday", "false"); httask.put("jrs.is_hourly", "false"); httask.put("jrs.is_between", "false"); 4. Get scheduled tasks from the Server Vector tasks = JRClient.getScheduled(null, server); 5. Compile and run the program, you will submit a schedule task and get the information about this task. JSP Page Customization JReport Enterprise Server takes web reporting to the next level by providing options for various needs through seamless personalized web pages. JReport Enterprise Server supports JSPs, so that the content or appearance of Web pages can be controlled through the use of servlets, small programs that are specified in the Web page and run on the Web server to modify the Web page before it is sent to the user who requested it. The default document root directory of JREntServer wrapping web server is public_html. The JSPs are in the subdirectory jinfonet. By modifying the JSP pages, you can not only modify the page layout, but also the functions associated with buttons. 27