A factory of
All the data displayed in a report comes from the report parameters and report fields. This data can be processed using the report variables and their expressions. Some variables are initialized according to their reset type when the report starts, or when a page or column break is encountered, or when a group changes. Furthermore, variables are evaluated every time new data is fetched from the data source (for every row).
But simple variable expressions cannot always implement complex functionality. This is where scriptlets come in. Scriptlets are sequences of Java code that are executed every time a report event occurs. Through scriptlets, users can affect the values stored by the report variables. Since scriptlets work mainly with report variables, it is important to have full control over the exact moment the scriptlet is executed.
JasperReports allows the execution of custom Java code before or after it initializes the
report variables according to their reset type:
In order to make use of this functionality, users need only create a scriptlet class, by extending one of the following two classes:
JRDefaultScriptletinstance and registers it with the built-in
For each scriplet, a name and a class extending the
JRAbstractScriptlet class must
be specified. The class must be available in the classpath at report filling time and must
have an empty constructor, so that the engine can instantiate it on the fly.
The only case when the name of the scriptlet is not required is when it is specified using
scriptletClass attribute of the
The scriptlet instance created with this attribute, acts like the first scriptlet in the
list of scriptlets and has the predefined name
When creating a JasperReports scriptlet class, there are several methods that developers
should implement or override, including
JRAbstractScriptlet.afterGroupInit(String). The report engine calls these methods at the appropriate time when
filling the report.
For more complex reports containing very complicated report expressions for grouping
or displaying data, create a separate class to which you then make calls from simplified
report expressions. The scriptlet classes are ideal for this. This is because the reporting
engine supplies you with references to the scriptlet objects it creates on the fly using the
Scriptlet objects are not instantiated by the engine if an instance is already provided as a
value for the corresponding
<ScriptletName>_SCRIPTLET parameter, by the caller.
Another way to associate scriptlets with reports is by declaring the scriptlets globally so
that they can apply to all reports being filled in the given JasperReports deployment.
This is made easy by the fact that scriptlets can be added to JasperReports as extensions.
The scriptlet extension point is represented by the
JasperReports will load all scriptlet factories available through extensions at runtime and will ask each one of them for the list of scriptlets instances that they want to apply to the current report that is being run. When asking for the list of scriptlet instances, the engine gives some context information that the factory could use in order to decide which scriptlets actually apply to the current report. For example, some scriptlets could look for certain report properties in the report template to see if they should be triggered or stay dormant during the current report execution.
It is known that certain invalid report templates could cause the reporting engine to enter an infinite loop at runtime, while trying to generate the reports. Such invalid report templates cannot be detected at design time, because most of the time the conditions for entering the infinite loops depend on the actual data that is fed into the engine at runtime.
We cannot anticipate that certain report templates will cause the engine to enter an infinite loop, and while within an infinite loop, there is no way for the program to know it is trapped in such a loop.
And here's where report governors become handy, because they can help deciding whether a certain report has entered an infinite loop and they can stop it, preventing resource exhaustion for the machine that runs the report.
JasperReports is shipped with two simple report governors that would stop a report execution based on a specified maximum number of pages or a specified timeout interval.
MaxPagesGovernor is a global scriptlet
that is looking for two configuration properties to decide if it applies or not to the report
currently being run:
TimeoutGovernoris also a global scriptlet that is looking for the following two configuration properties to decide if it applies or not:
net.sf.jasperreports.governor.timeout.enabled=[true|false] net.sf.jasperreports.governor.timeout=[milliseconds]The properties for both governors can be set globally, in the jasperreports.properties file, or at report level, as custom report properties. This is useful because different reports can have different estimated size or timeout limits and also because you might want turn on the governors for all reports, while turning it off for some, or vice-versa.
© 2001 - 2017 TIBCO Software Inc. www.jaspersoft.com