Read Me

JASPER OPEN SERVLET v1.0 build 15
a java servlet to embed reports in a web application.
Copyright (C) 2009-2010 Dotsolutions & Tecknoworks 
Licence: 
BSD (see licence.txt)
homepage:
http://sourceforge.net/projects/jasperos/
sourcecode:
http://www.datawarestudio.com/files/jasperos_src.zip

Jasper Open Servlet is part of QuickApplicationSuite
http://www.datawarestudio.com

email for bugreports & comments:
info@datawarestudio.com



Description
===========
Jasper Open Servlet is a Java http servlet to provide complex and drillable reports, created with Jasper/iReports. Output format can be html, pdf, csv, rtf.
The servlet can be encapsulated into a portal using an iframe portlet to add reporting capabilities to all your web applications.
Reports schemas definitions (.jasper or .jrxml) are stored on server filesystem.



Components
==========
Jasper Open Servlets uses on includes these components:
JasperReports ( http://www.jasperforge.org )
Famfamfam icons by Mark James ( http://www.famfamfam.com )
Commons BeanUtils ( http://commons.apache.org/beanutils )
Commons Collections ( http://commons.apache.org/collections )
iText by Bruno Lowagie ( http://www.lowagie.com/iText )
jfreechart ( http://www.jfree.org/jfreechart )
jxl ( http://jexcelapi.sourceforge.net )

This build uses mysql ( http://www.mysql.com ) as default database and includes
mysql-connector-java
You can use any ODBC compliant database inserting in the .war the appropriate JDBC connector, before deploying the servlet.

Jasper Open Servlet needs Apache Commons Logging, which is often included in the webserver. If needed, Jasper Open Servlet shows an error message: add the .jar to the server classpath.
You can find Apache Commons Logging at http://commons.apache.org/logging/download_logging.cgi



Overview
========
Install the servlet in your application server. After the deploy, you can access the servlet from you browser.
Example for Tomcat running on localhost, port 8080:
http://localhost:8080/JasperServlet/JasperServlet
If the install process finished without errors, you should find an "Hello World" demo.

It's possible to pass to the servlet the report to show and the parameters using the calling url. Example:
http://localhost:8080/JasperServlet/JasperServlet?_report=test&param1=xxx&param2=yyy
where 
The report to show is passed using 
_report=test
and param1 and param2 are defined in test.jrxml and accessed through $P{param1} and $P{param2}.
All parameters are type java.lang.String:
<parameter name="test" class="java.lang.Integer"/>



Configuration
=============
Default servlet configuration is set through "report.properties" file.
You can modify it in .war file or in ./webapps/JasperServlet directory.
In the first case, to accept mods, servlet must be newly deployed.
In the second one, a server stop/restart is needed.

report.properties Example
#Servlet Properties
driver=com.mysql.jdbc.Driver
url=jdbc:mysql://localhost:3306/MySchema
user=root
pass=xxx
report=test
basePath=/reports
forceRelativePath=1
compression=0
footer=Report created by Jasper Open Servlet


Report to call can be set either in report.properties (report=xxx.[jasper|jrxml]) or using direct call: http://localhost:8080/JasperServlet/JasperServlet?_report=xxx.[jasper|jrxml]
In this case, report written in address string overrides report set in report.properties.

If you need to use different parameters for different reports, you can create, for each report and in the same directory of the report, a file with the same name of the report, and the .properties extension (report_name.properties).
Parameters set in this file override Jasper Open Servlet general settings.

Html is the standard output format; To change it, you must pass to the servlet the correct parameter in the form:
output=html|pdf|xml|rtf or _output=html|pdf|xml|rtf

Example
http://localhost:8080/JasperServlet/JasperServlet?_report=test&output=pdf

In-memory report compression can be set with compression=1 parameter.
By default this option is disabled and reports are paginated in temporary files stored in default servlet directory.


If set, driver, url,user and pass allows to generate a dynamic report, connecting to the specified database.

Footer, if not void, prints a footer at every report page.



Embedded objects
================
Each embedded object (graphs, subreports) must be called using a path that can be absolute or relative.
In the former case, you can set it at your wish, in the latter one by default it's starting point is the webapp directory (example: C:\tomcat\webapps\JasperServlet).
Hint: check there are no problems concerning user rights. 
If the user can't access the server filesystem, it's possible to insert the reports to be shown in the .war file, before deploying it (as done with the hello report in the demo subdir).
If the user can access the server filesystem, it's useful/suggested to set a default path in servlet parameters (modifying report.properties)
You can even force JasperOpenServlet to convert an absolute path into a relative one.
Under Linux, Tomcat must be run by a user who has at least reading rights over default path.

Example (report.properties) 
basePath=/reports
forceRelativePath=1

A file without a path name should be present in "/reports" folder
A file with path /test/report/jasper/myfile.jasper - if forceRelativePath enabled - should be present in "/reports/test/report/jasper". If forceRelativePath is not enabled, the program uses the absolute path.
A file with path test/report/jasper should be always present in /reports/test/report/jasper

If the file name is passed without extension, the servlet tries at first the .jasper extension and than .jrxml one.
If the compiled file is not up to date, a strange behaviour could be experienced: it's recommended to create .jasper only as final step.



Portal Integration
==================
JasperOpenServlet is designed to be encapsulated into a standard Jsr168/286 portlet.
To exchange informations between portlet and servlet, the former must set a parameter _id=xxx.
Under these circumstances, JasperOpenServlet searches two objects:
a Map<String,String> named
	(_id)+connectionParams -> these ones replace parameters set in properties files, and must be equally named.
and an Array<String>
	(_id)+reportParams -> contains the names of the objects set by the portlet
	The servlet passes to the report the parameters included in the array, with the values set in the application scope named ("QPGA"+paramname)
	code example: 
		jasperParameters.put(param, session.getAttribute("QPGA"+param));
	


Misc
====
JasperServer ReportExecution statement, to call a report from another, is supported.

JasperOpenServlet can be used to create .jasper files from a .jrxml input:
- switch &_compile must be set to 1;
- A .jasper of the same file must not exist before running compiler.
Example
http://localhost:8080/JasperServlet/JasperServlet?_report=test&_compile=1



Limitations
===========
Only Java syntax is accepted as scripting language. There's no support for javascript or Groovy.
Subreports MUST be compiled (.jasper files) and MUST be called with path (relative or absolute) and extension (.jasper)
Unlikely Jasperserver, where you can use the syntax 
	repo:subreport
in JasperOpenServlet you must declare pathname and full extension (.jasper)
	/reports/subreport.jasper


JasperServer proprietary classes are not supported (LoggedInUser for example)


If report is empty or static (like helloworld) .jrxml uses "AllSectionsNoDetail" mode and always shows everything.
.jasper otherwise uses the mode set in .xml file.
Pay Attention: iReport always shows everything, even if this properties is not set.
To gain full control it's useful to define needed mode in jrxml, compile the source and use .jasper