programming guide - i-net /// software · 2014. 9. 15. · server programming © copyright 1996 -...

Programming GuideServer

http://www.inetsoftware.de

Server Programming

© Copyright 1996 - 2014, i-net software GmbH; All Rights Reserved.

1 Overview 2 ........................................................................................... 1.1 Sample files 2 .............................................................................. 1.2 Requirements 2 ............................................................................ 1.3 Call Sequence 2 ...........................................................................

2 ReportServlet 5 .................................................................................... 3 Servlet Filter 6 ..................................................................................... 4 Cache 7 ................................................................................................ 5 EngineFactory 9 ................................................................................... 6 PropertiesChecker 10 ...........................................................................

6.1 Send an e-mail in case of an error 11 ............................................. 7 Database 12 ........................................................................................

7.1 Setting the Database class 13 ....................................................... 7.1.1 Data Source Configuration 13 .................................................. 7.1.2 API 14 .................................................................................

7.2 Implementation of your own DataFactory 14 .................................. 8 Dummy JDBC Driver 15 ........................................................................

8.1 Building your own JDBC driver 16 .................................................. 9 EngineRenderData 16 .......................................................................... 10 CacheRenderData 17 ......................................................................... 11 RDC and Engine 18 ............................................................................ 12 Compare the programming techniques 18 ........................................ 13 Plugins 19 ..........................................................................................

13.1 Architecture 20 .......................................................................... 13.2 Live cycle 20 .............................................................................. 13.3 Plugin Properties 21 .................................................................... 13.4 Extension points 22 .................................................................... 13.5 Sample Code 22 .........................................................................


Server Programming

Page 2© Copyright 1996 - 2014, i-net software GmbH; All Rights Reserved.

1 Overview

I-net Clear Reports contains an extensive API for programming the reportserver. This guide will give you an overview about the possibilities. Morecomplete information can be found in the documentation, e.g. the list oflibraries and the API documentation. You can find the documentation in theinstallation directory (if installed) or on the i-net Clear Reports website.

1.1 Sample files

Please find the examples of this guide as java classes and some moreexamples in the folder "/client/documentation/samples" of the installationfolder. (If you have installed the Documentation and Examples)

1.2 Requirements

This guide describes the usage of the i-net Clear Reports API. Therefore it isnecessary that i-net Clear Reports is installed either as report server or it isembedded into your own application so that you can access the API.

Note that the main JAR file to link your source to is ClearReports.jar, found inthe core subdirectory of your installation.

1.3 Call Sequence

To help you understand where you can change what, we'll show you first thesequence of code points of a typical report request. Many of these methods(as for example the PropertyChecker methods) can be overloaded by your

https://www.inetsoftware.de/products/clear-reports/documentation/index

https://www.inetsoftware.de/documentation/clear-reports/online-help/installation/libraries-of-i-net-clear-reports

https://www.inetsoftware.de/documentation/clear-reports/online-help/installation/libraries-of-i-net-clear-reports

https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/index.html

https://www.inetsoftware.de/products/clear-reports


Server Programming


own classes.


Server Programming



Server Programming


2 ReportServlet

If you deploy i-net Clear Reports in a servlet engine then the classcom.inet.report.ReportServlet is the main entry point. If you only wantto control the access to the reports then the easiest solution is to extend thisReportServlet. You can find the Report Servlet API in the API documentation.

There are some methods which are called on the live cycle of the reportrequest.

You can:

set or modify the report name●

set or modify the report parameters (prompts)●

modify the HTML page of the applet●

modify the Engine after the template was read●

use a specific output format (report viewer applet, PDF, etc.)●

use the Remote Configuration Manager●

You can not:

create the Engine yourself●

https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/com/inet/report/ReportServlet.html


https://www.inetsoftware.de/documentation/clear-reports/online-help/features/output-formats


Server Programming


3 Servlet Filter

As an alternative to your own class that extends the ReportServlet you canuse a servlet filter because it is executed before all other classes. Theservlet filter has an effect both on the rendering as well as on the remoteaccess.

Any implementation of the class javax.servlet.Filter can be used as servletfilter. There are a lot of third party implementations available.

To add a servlet filter to i-net Clear Reports, add it to a .jar file and put this.jar file into the folder: "<install-dir>/lib". In the category "Customization" itis possible to specify a comma separated list of servlet filters. Add the classname of the filter to the property "Servlet Filter".

Using a servlet filter it is possible to forward a successful log-in to a front-end server to i-net Clear Reports so that a temporary data source can becreated for the logged in user (session scope datasource).Using a servlet filter you have complete control over theinput(javax.servlet.HttpServletRequest) andoutput(javax.servlet.HttpServletResponse).


Server Programming


4 Cache

For some output formats like the Applet Viewer or HTML the server will sendthe rendering result in multiple steps. Therefore it is necessary to cache theresults between different request. Also, with the cache it is possible to sharethe rendered results between multiple users. This optional feature canreduce the load on the server and it can be enabled/disabled using theConfiguration property: Reload On New Request.

You can find the cache API in the API documentation.

The following sample shows a simple usage of the Cache API to export toPDF:

Cache cache = Cache.getCache();Properties reportProperties = new Properties();reportProperties.put("report", "c:\\myreport.rpt" );reportProperties.put("export_fmt", "pdf" );ReportCacheKey key = cache.getKey(reportProperties); int pageCount = cache.getPageCountAndWait(key);for (int i = 1; i <= pageCount; i++) { byte[] page = cache.getPageAndWait(key, i); ....}

More samples for the usage of the Cache API you can find in the Java codesamples directory: "<installationdirectory>/client/documentation/samples/cache".

If you use the Cache API directly you do not need to implement the caching

https://www.inetsoftware.de/documentation/clear-reports/remote-interface-help/configuration/configuration/en/system/cache/index

https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/com/inet/report/cache/Cache.html


http://www.google.com/search?hl=en&q=allinurl:docs.oracle.com javase docs api properties

http://www.google.com/search?hl=en&q=allinurl:docs.oracle.com javase docs api properties


Server Programming


itself. You have the full control over the connection between client andserver.

You can:




create the Engine (limited with addEngine)●

You can not:



Server Programming


5 EngineFactory

The Cache API has 2 static methods getEngineFactory and setEngineFactory.With these methods you can register your own global EngineFactory. Youcan find the EngineFactory API in the API documentation.

With the EngineFactory you can:

use your own report templates●

use your own parameters●


control the Engine creation●

skip some parameters from the report key●

You can not:


https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/com/inet/report/cache/EngineFactory.html



Server Programming


6 PropertiesChecker

Another option is to implement the PropertiesChecker interface.

You can find the PropertiesChecker API in the API documentation.

There are multiple solutions to set a custom PropertyChecker:

set the class name in the property Property Checker of the currently used●

Configuration

With the PropertyChecker you can accomplish much the same as with anoverridden ReportServlet, though ReportServlet has more interaction points.

You can:




modify the Engine after loading●

force a specific output format (applet, pdf, etc.)●


register an EngineFinishListener using Engine.addFinishListener(EngineFinishListener)●

You can not:

create the Engine●

6.1 Send an e-mail in case of an error

In the method checkProperties(Engine, Properties, Object) of thePropertyChecker you can register an EngineFinishListener to the currentengine ( Engine.addFinishListener(EngineFinishListener) ).

https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/com/inet/report/PropertiesChecker.html


https://www.inetsoftware.de/documentation/clear-reports/remote-interface-help/configuration/configuration/en/system/customization/index


Server Programming


In the method engineFinish(EngineFinishEvent event) of thisEngineFinishListener you can use the method Engine.getErrorMsg() to getthe error message, if an error has occurred. If no error has occurred, thismethod returns a Null.

In case of an error you can use this error message in your email.


Server Programming


7 Database

If you want to manually set the data for a report then you can do it with anyof the Engine.setData() methods. An alternative method is to set a datafactory.

An instance of the class com.inet.report.Database is the factory for thereport data. Most implementations of the Database use JDBC but it is alsopossible to set the data without JDBC. The advantages of the Database classis that it is easier to set the data for sub reports. This is the only solution forsetting individual data for each sub report.

7.1 Setting the Database class

There are multiple possible solutions.

7.1.1 Data Source Configuration

The easiest solution is to set the class name of the Database class in theData Source Configuration on which the report is based.

Note: A data source configuration with the same name can have differentunderlying data sources on the server machine and the machine running i-net Designer.

Possible problems with this approach could be that:

an administrator changes, renames or deletes the data source configuration pointing●

to your Database implementationthe Database class can not be loaded●

https://www.inetsoftware.de/documentation/clear-reports/online-help/configuration/datasources/index


Server Programming


In these cases i-net Clear Reports does its best to locate the data source viafallback solutions.

7.1.2 API

Another solution is to set your Database class via API. You need access tothe Engine instance after loading. To get the Engine instance you need touse one of the other described programming techniques.

Engine engine = ...DatabaseTables dbt = engine.getDatabaseTables();for(int i=0;i<dbt.getDatasourceCount();i++) { Datasource ds = dbt.getDatasource(i); ds.setDatabase(myDatabase);}

The same must be repeated for each sub-report.

7.2 Implementation of your own DataFactory

If you want to use your own Database class that can be used for reportdesign in i-net Designer and report execution then you need to implementyour own Database class that extends fromcom.inet.report.database.BaseDataFactory (if non JDBC data are used) orcom.inet.report.Database (if customization for a used JDBC driver isneeded). More details about the methods that need to be implemented canbe found in the API documentation.

For more details about the creation of database class please refer to thesample "DatabaseClassUsableInDesigner" in the directory

https://www.inetsoftware.de/documentation/clear-reports/online-help/programming/apispec/com/inet/report/database/datafactory.html


Server Programming


"client/documentation/samples/jdbc" of the i-net Clear Reports installation.


Server Programming


8 Dummy JDBC Driver

If you want set the data via API you can also use your own JDBC driver. JDBCis the standard data factory of Java. At first glance, this could seem to bevery difficult because a JDBC driver has a large API. But i-net Clear Reportsonly uses a few of the API methods. You can find a sample for a dummyJDBC driver in the directory: "<installationdirectory>/client/documentation/samples/jdbc_your_own_driver".

You can set the used JDBC driver in the Data Source Configuration used byyour reports. The JDBC driver can be used at design time (in the reportdesigner) and at runtime in the server. A dummy JDBC driver is the onlysolution to setting the data via API, designing a report with your own data,and using a Row Buffer.

8.1 Building your own JDBC driver

Look at the samples in the folder "<installationdirectory>/client/documentation/samples/jdbc_your_own_driver". Copy thepackage "dummydriver" in your Java IDE and change the implementation ofthe implemented methods. Create a jar file and add it to the lib directory ofthe i-net Designer.

Now you can design a report using your own JDBC driver.

https://www.inetsoftware.de/documentation/clear-reports/designer-manual/default.html?https://www.inetsoftware.de/documentation/clear-reports/designer-manual/Layout/Report-Properties.html#RowBuffer


Server Programming


9 EngineRenderData

If you want to implement an application without web interface or your ownclient-server communication protocol for example CORBA or SOAP then apossible solution is to extends the class RenderData on the Java Viewer(client) side and the class EngineRenderData on the server side. The mostimportant method is createEngine(Properties). This is the factory method forthe Engine. You need to transfer all method calls from the RenderData onclient and back. This class does not use the cache. The Engine and therendered data is hold in the memory. The i-net DesignerXML uses this classfor generating data for its embedded report viewer.

You can:

use all features of the Java viewer●

have full control over the Engine creation●

have full control over the client server communication●

You can not:


create reports larger than the RAM allows, since the report results are held in●

memory.

10 CacheRenderData

The CacheRenderData is an alternative implementation of the RenderDatainterface. The difference to the EngineRenderData is that it uses the cache.Therefore you can't create the Engine itself.

You can:

use all features of the Java viewer●

have full control over the Engine creation●

have full control over the client server communication●


Server Programming


create reports larger than memory-only●

You can not:


11 RDC and Engine

The classes com.inet.report.RDC and com.inet.report.Engine are the startingpoints if you want to work with the low-level API directly. If you use the low-level API then you will have to do many things like caching and client servercommunication yourself.

You can:

fully control the Engine creation●

fully control the client server communication●

You can not:


create reports larger than your RAM can hold●

use all features of the viewer (search, error messages).●

12 Compare the programming techniques

Repo

rtSe

rvle

t

Cach

e

Engi

neFa

ctor

y

Prop

erty

Chec

ker

Data

base

All Viewer Features 1) Yes No Yes Yes YesReport Cache Yes Yes Yes Yes YesFull control over the Enginecreation No limited 2) Yes No No

Modify report parameters Yes Yes No Yes NoModify HTML page Yes Yes No Yes No


Server Programming


Repo

rtSe

rvle

t

Cach

e

Engi

neFa

ctor

y

Prop

erty

Chec

ker

Data

base

Full control over the clientserver communication limited 3) Yes No No No

Complexity (1 – simple, 5 -difficult) 1 3 2 1 1

Modify the Engine after loading Yes limited 4) Yes Yes Limited 5)

Set the report data limited 6) No limited 7) limited 8) Yes

Own

JDBC

Driv

er

Engi

neRe

nder

Data

Cach

eRen

derD

ata

RDC

and

Engi

ne

All Viewer Features 9) Yes Yes Yes NoReport Cache Yes No Yes NoFull control over the Engine creation No Yes No YesModify report parameters No Yes Yes YesModify HTML page No Yes Yes YesFull control over the client server communication No Yes Yes YesComplexity (1 – simple, 5 - difficult) 3 4 4 5Modify the Engine after loading No Yes No YesSet the report data Yes limited 10) No limited 11)

Our recommendation is to use ReportServlet, EngineFactory or bothtogether. If you only want to set the data then your own Database class isthe best solution.

13 Plugins


Server Programming


If you want to add a new feature to i-net Clear Reports, creating a plugin isthe recommended way. A plugin is a zip file in the folder "plugins". This filecontains all that is required for this new feature.

In order to remove a feature from your i-net Clear Reports installation, justremove its plugin zip file and restart the server. In case another plugindepends on the removed one, this plugin will be disabled.

13.1 Architecture

A plugin is a zip file. It contains at least the files plugin.properties andserver.jar in order to work.

The plugin.properties defines the start class (named entrypoint) whichimplements the interface com.inet.plugin.ServerPlugin. All dependencies, id,description and included internal jar libraries must be defined in this file.

The server.jar contains the code of your plugin. At least an implementationof the interface com.inet.plugin.ServerPlugin is required.

13.2 Live cycleOn start-up, i-net Clear Reports loads all plugins that are available in the plugins●

directory.All located plugins are opened and their server.jar is extracted into a temporary●

directory.The plugin.properties files of the plugins are read and a dependency tree is●

created.If the dependency of a plugin is not fulfilled, it is disabled.●

Now each plugin gets its own classloader given access to the plugin classes, internal●

and external referenced libraries and classes that are made public by other plugins (ifthe current plugin has an according dependency defined).The next step is to instantiate the entrypoint class.●

The registerExtensions method is called. Each plugin may now register instances of●

extensions it provides. This phase is only meant for registration, initialization is


Server Programming


discouraged here. As a result, it is not allowed to query the ServerPluginManager foralready registered instances. This call would fail with an exception.After the register phase, the init phase is started which calls the init method of your●

plugin entrypoint instance. Now all required instances can be initialized. Since allextensions are registered now, it's allowed to fetch the registered extensions from theprovided ServerPluginManager instance. Registering further extensions is disabled inthis phase and will result in an exception.

If background threads are needed, they can be started in the init method.Please ensure to stop these threads in the reset method. A restart of thebackground thread should be performed if the restart method is invoked.Resetting and restarting is only invoked by some application servers thatsupport unloading unused web containers.

13.3 Plugin Properties

Out of the following list, only id and entrypoint are mandatory. Any furtherproperty is optional.

Prop

erty

Desc

riptio

n

id A unique identifier with only lowercase characters. In general it isequal to the filename of the plugin.

entrypoint The fully qualified class name of the server plugin entry class.Packages are separated with dots.

dependencies A semi-colon separated list of required plugins identified by theirID (optionally with comma-separated version).

optionalDependencies A list of optional dependencies. The current plugin will run even ifthese dependencies are missing.

internal An optional semi-colon separated list of additional jar files in thezip file. These jar files will be added to the classpath of the plugin.

externalAny external library jar files required by this plugin. A semi-colonseparated list with absolute paths or paths relative to the currentworking directory.


Server Programming


Prop

erty

Desc

riptio

nversion

The version number of this plugin. It will be shown in the log file. Ithas to be a valid float number and can also be used to define thedependency to a plugin with a special version.

description A description that will be shown in the GUI.description_<locale> A localized description that will be shown in the GUI.

initAfterA semi-colon separated list of dependencies identified by their ID.The plugin manager will try to init any of the plugins in this listbefore the current one. In case of a cyclic reference the order inthis cycle is undefined.

rootAccess If the plugin need access to the root class loader of theapplication. A setting of the dependencies property is to prefer.

13.4 Extension points

i-net Clear Reports has a growing list of extension points. Extension pointsare interfaces or abstract classes that a plugin can implement to extendsthe functionally of another plugin or the core. Here is a short list of availableextension points.

Exte

nsio

n

Plug

in

Desc

riptio

n

com.inet.report.schedule.ScheduleAction scheduler Additional action for thescheduler.

com.inet.http.PluginServlet - Adds an extra servlet contextto the server.

com.inet.authentication.UsersAndGroupsProvider -Provides a list of availableusers and groups for thesecurity settings in the GUI.

com.inet.authentication.AuthenticationProvider - Add support for an additionalauthentication mechanism.


Server Programming


13.5 Sample Code

Samples for a scheduler action and a user-group-provider including a stepby step description can be found in the samples folder of your i-net ClearReports installation.

1) , 9) The error handling and the search feature is not always possible2) , 4) With Cache.addEngine(Engine) no large reports are possible3) You can call the ReportServlet with your own implementation of HttpServletRequest and HttpServletResponse.5) In getReportData you get an Engine and you can do some modifications on the Engine but it is not recommended becausethe rendering has already started.6) , 7) , 8) , 10) , 11) You can not set the data for each individual sub report.


programming guide - i-net /// software · 2014. 9. 15. · server programming © copyright 1996 -...

Documents