Servlets

You have a report engine and a report viewer running on different machines and you want to connect these components? This can be done either using the standalone socket-listener (programming using the socket-listener is described here) which is built into i-net Clear Reports or you use a web-server and a servlet-engine such as Apache-Tomcat, Bea WebLogic or IBM WebSphere.

• A web-server
• A servlet engine which is compliant to the servlet specification 2.2
• i-net Clear Reports in the classpath of the servlet engine
• Java viewer extracted in the document root of the web-server. If you want to embed the Java viewer into HTML pages or a standalone viewer running on the client machine..

• If you want basic/Kerberos authentication or another authentication the web-server must support this method. When running the Java viewer within a browser and this browser supports the authentication method, Java viewer and i-net Clear Reports will support this also.
• If you want SSL secured connections from the client to the web-server, the web-server must support the SSL protocol. If you further want secure connections from the reporting engine i-net Clear Reports to a secured web-server, the container in which i-net Clear Reports runs must also support SSL connections.

The following sections describe how to use the report servlet we ship with i-net Clear Reports.

The report servlet mediates between the client and the engine. It must wait for client requests and respond by sending back the requested data.

It does this in two steps:

1. When a report is requested, it creates an engine object and an HTML page based on the request parameters and sends the HTML page with a link to the applet back to standard output.
2. The Java viewer is loaded from the location described in the HTML paged and sends a request to the URL described in the report parameter of the HTML page. It appends a parameter “viewer=java2” plus a export format (optional) to express that it requests binary data in the given export format.

With the help of the report engine the servlet must:

• send back an HTML page with the Java viewer embedded, when it is invoked without a “init=” or “viewer=” command.
• send back report data in the specific format if “init=” is given or send back binary data for use with the Java viewer if “viewer=” is given as a URL parameter
• cache the engine in step 1) and find it in step 2).
• respond to special commands, get_lpg and rfsh issued by the viewer and then send back the binary encoded number of pages or a refreshed report.
• respond to an error by sending back binary encoded error data.

If you look at the javadoc documentation of com.inet.report.ReportServlet, you see that the servlet uses the public methods doWriteHtmlPage() and doExecRequest(). The former is executed in step1 while doExecRequest() is executed in step 2 from within the service method, right before the servlet's doGet() and doPost() methods are called.

The methods receive the servlet request and response and a bag of URL decoded parameter/value pairs from either the get line of from the parameter list with the keys converted to lowercase. If you throw an exception within these methods, the exception will be caught and a proper error message is sent back to the client.

The default-method doWriteHtmlPage() calls the hook checkHtmlPageProperties() which could be used to change the parameters of the default HTML page. The default-method doExecRequest() calls two hooks, first checkProperties(properties, request) is called which can be used to change the report file according to the servlet request context.  The second callback checkProperties(engine, properties, request) is called after the engine has been initialized with the default values from the report file and can be used to examine and change the default values.

If you override the default-method doExecRequest(), you may find the engine's method getPageCountData() and get/setErrorData() helpful.

• Servlet Installation