public abstract class

AbstractJasperReportsView

extends AbstractUrlBasedView
java.lang.Object
   ↳ org.springframework.context.support.ApplicationObjectSupport
     ↳ org.springframework.web.context.support.WebApplicationObjectSupport
       ↳ org.springframework.web.servlet.view.AbstractView
         ↳ org.springframework.web.servlet.view.AbstractUrlBasedView
           ↳ org.springframework.web.servlet.view.jasperreports.AbstractJasperReportsView
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Base class for all JasperReports views. Applies on-the-fly compilation of report designs as required and coordinates the rendering process. The resource path of the main report needs to be specified as url.

This class is responsible for getting report data from the model that has been provided to the view. The default implementation checks for a model object under the specified reportDataKey first, then falls back to looking for a value of type JRDataSource, java.util.Collection, object array (in that order).

If no JRDataSource can be found in the model, then reports will be filled using the configured javax.sql.DataSource if any. If neither a JRDataSource or javax.sql.DataSource is available then an IllegalArgumentException is raised.

Provides support for sub-reports through the subReportUrls and subReportDataKeys properties.

When using sub-reports, the master report should be configured using the url property and the sub-reports files should be configured using the subReportUrls property. Each entry in the subReportUrls Map corresponds to an individual sub-report. The key of an entry must match up to a sub-report parameter in your report file of type net.sf.jasperreports.engine.JasperReport, and the value of an entry must be the URL for the sub-report file.

For sub-reports that require an instance of JRDataSource, that is, they don't have a hard-coded query for data retrieval, you can include the appropriate data in your model as would with the data source for the parent report. However, you must provide a List of parameter names that need to be converted to JRDataSource instances for the sub-report via the subReportDataKeys property. When using JRDataSource instances for sub-reports, you must specify a value for the reportDataKey property, indicating the data to use for the main report.

Allows for exporter parameters to be configured declatively using the exporterParameters property. This is a Map typed property where the key of an entry corresponds to the fully-qualified name of the static field for the JRExporterParameter and the value of an entry is the value you want to assign to the exporter parameter.

Response headers can be controlled via the headers property. Spring will attempt to set the correct value for the Content-Diposition header so that reports render correctly in Internet Explorer. However, you can override this setting through the headers property.

See Also

Summary

Constants
String CONTENT_DISPOSITION_INLINE The default Content-Disposition header.
String HEADER_CONTENT_DISPOSITION Constant that defines "Content-Disposition" header.
[Expand]
Inherited Constants
From class org.springframework.web.servlet.view.AbstractView
[Expand]
Inherited Fields
From class org.springframework.context.support.ApplicationObjectSupport
From interface org.springframework.web.servlet.View
Public Constructors
AbstractJasperReportsView()
Public Methods
Map<?, ?> getExporterParameters()
Return the exporter parameters that this view uses, if any.
void setExporterParameters(Map<?, ?> parameters)
Set the exporter parameters that should be used when rendering a view.
void setHeaders(Properties headers)
Specify the set of headers that are included in each of response.
void setJdbcDataSource(DataSource jdbcDataSource)
Specify the javax.sql.DataSource to use for reports with embedded SQL statements.
void setReportDataKey(String reportDataKey)
Set the name of the model attribute that represents the report data.
void setSubReportDataKeys(String[] subReportDataKeys)
Set the list of names corresponding to the model parameters that will contain data source objects for use in sub-reports.
void setSubReportUrls(Properties subReports)
Specify resource paths which must be loaded as instances of JasperReport and passed to the JasperReports engine for rendering as sub-reports, under the same keys as in this mapping.
Protected Methods
final void convertExporterParameters()
Converts the exporter parameters passed in by the user which may be keyed by Strings corresponding to the fully qualified name of the JRExporterParameter into parameters which are keyed by JRExporterParameter.
Object convertParameterValue(JRExporterParameter parameter, Object value)
Convert the supplied parameter value into the actual type required by the corresponding JRExporterParameter.
JRDataSource convertReportData(Object value)
Convert the given report data value to a JRDataSource.
JRExporterParameter convertToExporterParameter(String fqFieldName)
Convert the given fully qualified field name to a corresponding JRExporterParameter instance.
JRDataSource createReport(JRDataSourceProvider provider)
Create a report using the given provider.
void exposeLocalizationContext(Map<String, Object> model, HttpServletRequest request)
Expose current Spring-managed Locale and MessageSource to JasperReports i18n ($R expressions etc).
JasperPrint fillReport(Map<String, Object> model)
Create a populated JasperPrint instance from the configured JasperReport instance.
Map<JRExporterParameter, Object> getConvertedExporterParameters()
Allows subclasses to retrieve the converted exporter parameters.
JRExporterParameter getExporterParameter(Object parameter)
Return a JRExporterParameter for the given parameter object, converting it from a String if necessary.
DataSource getJdbcDataSource()
Return the javax.sql.DataSource that this view uses, if any.
JasperReport getReport()
Determine the JasperReport to fill.
JRDataSource getReportData(Map<String, Object> model)
Create an appropriate JRDataSource for passed-in report data.
Class[] getReportDataTypes()
Return the value types that can be converted to a JRDataSource, in prioritized order.
final void initApplicationContext()
Checks to see that a valid report file URL is supplied in the configuration.
boolean isUrlRequired()
JasperReports views do not strictly required a 'url' value.
JasperReport loadReport()
Load the main JasperReport from the specified Resource.
final JasperReport loadReport(Resource resource)
Loads a JasperReport from the specified Resource.
void onInit()
Subclasses can override this to add some custom initialization logic.
void postProcessReport(JasperPrint populatedReport, Map<String, Object> model)
Template method to be overridden for custom post-processing of the populated report.
void renderMergedOutputModel(Map<String, Object> model, HttpServletRequest request, HttpServletResponse response)
Finds the report data to use for rendering the report and then invokes the renderReport(JasperPrint, Map, HttpServletResponse) method that should be implemented by the subclass.
abstract void renderReport(JasperPrint populatedReport, Map<String, Object> model, HttpServletResponse response)
Subclasses should implement this method to perform the actual rendering process.
void setConvertedExporterParameters(Map<JRExporterParameter, Object> convertedExporterParameters)
Allows subclasses to populate the converted exporter parameters.
[Expand]
Inherited Methods
From class org.springframework.web.servlet.view.AbstractUrlBasedView
From class org.springframework.web.servlet.view.AbstractView
From class org.springframework.web.context.support.WebApplicationObjectSupport
From class org.springframework.context.support.ApplicationObjectSupport
From class java.lang.Object
From interface org.springframework.beans.factory.BeanNameAware
From interface org.springframework.beans.factory.InitializingBean
From interface org.springframework.context.ApplicationContextAware
From interface org.springframework.web.context.ServletContextAware
From interface org.springframework.web.servlet.View

Constants

protected static final String CONTENT_DISPOSITION_INLINE

The default Content-Disposition header. Used to make IE play nice.

Constant Value: "inline"

protected static final String HEADER_CONTENT_DISPOSITION

Constant that defines "Content-Disposition" header.

Constant Value: "Content-Disposition"

Public Constructors

public AbstractJasperReportsView ()

Public Methods

public Map<?, ?> getExporterParameters ()

Return the exporter parameters that this view uses, if any.

public void setExporterParameters (Map<?, ?> parameters)

Set the exporter parameters that should be used when rendering a view.

Parameters
parameters Map with the fully qualified field name of the JRExporterParameter instance as key (e.g. "net.sf.jasperreports.engine.export.JRHtmlExporterParameter.IMAGES_URI") and the value you wish to assign to the parameter as value

public void setHeaders (Properties headers)

Specify the set of headers that are included in each of response.

Parameters
headers the headers to write to each response.

public void setJdbcDataSource (DataSource jdbcDataSource)

Specify the javax.sql.DataSource to use for reports with embedded SQL statements.

public void setReportDataKey (String reportDataKey)

Set the name of the model attribute that represents the report data. If not specified, the model map will be searched for a matching value type.

A JRDataSource will be taken as-is. For other types, conversion will apply: By default, a java.util.Collection will be converted to JRBeanCollectionDataSource, and an object array to JRBeanArrayDataSource.

Note: If you pass in a Collection or object array in the model map for use as plain report parameter, rather than as report data to extract fields from, you need to specify the key for the actual report data to use, to avoid mis-detection of report data by type.

See Also
  • convertReportData(Object)
  • net.sf.jasperreports.engine.JRDataSource
  • net.sf.jasperreports.engine.data.JRBeanCollectionDataSource
  • net.sf.jasperreports.engine.data.JRBeanArrayDataSource

public void setSubReportDataKeys (String[] subReportDataKeys)

Set the list of names corresponding to the model parameters that will contain data source objects for use in sub-reports. Spring will convert these objects to instances of JRDataSource where applicable and will then include the resulting JRDataSource in the parameters passed into the JasperReports engine.

The name specified in the list should correspond to an attribute in the model Map, and to a sub-report data source parameter in your report file. If you pass in JRDataSource objects as model attributes, specifing this list of keys is not required.

If you specify a list of sub-report data keys, it is required to also specify a reportDataKey for the main report, to avoid confusion between the data source objects for the various reports involved.

Parameters
subReportDataKeys list of names for sub-report data source objects
See Also

public void setSubReportUrls (Properties subReports)

Specify resource paths which must be loaded as instances of JasperReport and passed to the JasperReports engine for rendering as sub-reports, under the same keys as in this mapping.

Parameters
subReports mapping between model keys and resource paths (Spring resource locations)
See Also

Protected Methods

protected final void convertExporterParameters ()

Converts the exporter parameters passed in by the user which may be keyed by Strings corresponding to the fully qualified name of the JRExporterParameter into parameters which are keyed by JRExporterParameter.

See Also

protected Object convertParameterValue (JRExporterParameter parameter, Object value)

Convert the supplied parameter value into the actual type required by the corresponding JRExporterParameter.

The default implementation simply converts the String values "true" and "false" into corresponding Boolean objects, and tries to convert String values that start with a digit into Integer objects (simply keeping them as String if number conversion fails).

Parameters
parameter the parameter key
value the parameter value
Returns
  • the converted parameter value

protected JRDataSource convertReportData (Object value)

Convert the given report data value to a JRDataSource.

The default implementation delegates to JasperReportUtils unless the report data value is an instance of JRDataSourceProvider. A JRDataSource, JRDataSourceProvider, java.util.Collection or object array is detected. JRDataSources are returned as is, whilst JRDataSourceProviders are used to create an instance of JRDataSource which is then returned. The latter two are converted to JRBeanCollectionDataSource or JRBeanArrayDataSource, respectively.

Parameters
value the report data value to convert
Returns
  • the JRDataSource
Throws
IllegalArgumentException if the value could not be converted
See Also
  • convertReportData(Object)
  • net.sf.jasperreports.engine.JRDataSource
  • net.sf.jasperreports.engine.JRDataSourceProvider
  • net.sf.jasperreports.engine.data.JRBeanCollectionDataSource
  • net.sf.jasperreports.engine.data.JRBeanArrayDataSource

protected JRExporterParameter convertToExporterParameter (String fqFieldName)

Convert the given fully qualified field name to a corresponding JRExporterParameter instance.

Parameters
fqFieldName the fully qualified field name, consisting of the class name followed by a dot followed by the field name (e.g. "net.sf.jasperreports.engine.export.JRHtmlExporterParameter.IMAGES_URI")
Returns
  • the corresponding JRExporterParameter instance

protected JRDataSource createReport (JRDataSourceProvider provider)

Create a report using the given provider.

Parameters
provider the JRDataSourceProvider to use
Returns
  • the created report

protected void exposeLocalizationContext (Map<String, Object> model, HttpServletRequest request)

Expose current Spring-managed Locale and MessageSource to JasperReports i18n ($R expressions etc). The MessageSource should only be exposed as JasperReports resource bundle if no such bundle is defined in the report itself.

The default implementation exposes the Spring RequestContext Locale and a MessageSourceResourceBundle adapter for the Spring ApplicationContext, analogous to the JstlUtils.exposeLocalizationContext method.

See Also

protected JasperPrint fillReport (Map<String, Object> model)

Create a populated JasperPrint instance from the configured JasperReport instance.

By default, this method will use any JRDataSource instance (or wrappable Object) that can be located using setReportDataKey(String), a lookup for type JRDataSource in the model Map, or a special value retrieved via getReportData(Map).

If no JRDataSource can be found, this method will use a JDBC Connection obtained from the configured javax.sql.DataSource (or a DataSource attribute in the model). If no JDBC DataSource can be found either, the JasperReports engine will be invoked with plain model Map, assuming that the model contains parameters that identify the source for report data (e.g. Hibernate or JPA queries).

Parameters
model the model for this request
Returns
  • the populated JasperPrint instance
Throws
IllegalArgumentException if no JRDataSource can be found and no javax.sql.DataSource is supplied
SQLException if there is an error when populating the report using the javax.sql.DataSource
if there is an error when populating the report using a JRDataSource
Exception
See Also

protected Map<JRExporterParameter, Object> getConvertedExporterParameters ()

Allows subclasses to retrieve the converted exporter parameters.

protected JRExporterParameter getExporterParameter (Object parameter)

Return a JRExporterParameter for the given parameter object, converting it from a String if necessary.

Parameters
parameter the parameter object, either a String or a JRExporterParameter
Returns
  • a JRExporterParameter for the given parameter object
See Also

protected DataSource getJdbcDataSource ()

Return the javax.sql.DataSource that this view uses, if any.

protected JasperReport getReport ()

Determine the JasperReport to fill. Called by fillReport(Map).

The default implementation returns the report as statically configured through the 'url' property (and loaded by loadReport()). Can be overridden in subclasses in order to dynamically obtain a JasperReport instance. As an alternative, consider overriding the fillReport(Map) template method itself.

Returns
  • an instance of JasperReport

protected JRDataSource getReportData (Map<String, Object> model)

Create an appropriate JRDataSource for passed-in report data. Called by fillReport(Map) when its own lookup steps were not successful.

The default implementation looks for a value of type java.util.Collection or object array (in that order). Can be overridden in subclasses.

Parameters
model the model map, as passed in for view rendering
Returns
  • the JRDataSource or null if the data source is not found
See Also

protected Class[] getReportDataTypes ()

Return the value types that can be converted to a JRDataSource, in prioritized order. Should only return types that the convertReportData(Object) method is actually able to convert.

Default value types are: java.util.Collection and Object array.

Returns
  • the value types in prioritized order

protected final void initApplicationContext ()

Checks to see that a valid report file URL is supplied in the configuration. Compiles the report file is necessary.

Subclasses can add custom initialization logic by overriding the onInit() method.

Throws
ApplicationContextException

protected boolean isUrlRequired ()

JasperReports views do not strictly required a 'url' value. Alternatively, the getReport() template method may be overridden.

protected JasperReport loadReport ()

Load the main JasperReport from the specified Resource. If the Resource points to an uncompiled report design file then the report file is compiled dynamically and loaded into memory.

Returns
  • a JasperReport instance, or null if no main report has been statically defined

protected final JasperReport loadReport (Resource resource)

Loads a JasperReport from the specified Resource. If the Resource points to an uncompiled report design file then the report file is compiled dynamically and loaded into memory.

Parameters
resource the Resource containing the report definition or design
Returns
  • a JasperReport instance

protected void onInit ()

Subclasses can override this to add some custom initialization logic. Called by initApplicationContext() as soon as all standard initialization logic has finished executing.

See Also

protected void postProcessReport (JasperPrint populatedReport, Map<String, Object> model)

Template method to be overridden for custom post-processing of the populated report. Invoked after filling but before rendering.

The default implementation is empty.

Parameters
populatedReport the populated JasperPrint
model the map containing report parameters
Throws
Exception if post-processing failed

protected void renderMergedOutputModel (Map<String, Object> model, HttpServletRequest request, HttpServletResponse response)

Finds the report data to use for rendering the report and then invokes the renderReport(JasperPrint, Map, HttpServletResponse) method that should be implemented by the subclass.

Parameters
model the model map, as passed in for view rendering. Must contain a report data value that can be converted to a JRDataSource, acccording to the rules of the fillReport(Map) method.
request current HTTP request
response current HTTP response
Throws
Exception

protected abstract void renderReport (JasperPrint populatedReport, Map<String, Object> model, HttpServletResponse response)

Subclasses should implement this method to perform the actual rendering process.

Note that the content type has not been set yet: Implementors should build a content type String and set it via response.setContentType. If necessary, this can include a charset clause for a specific encoding. The latter will only be necessary for textual output onto a Writer, and only in case of the encoding being specified in the JasperReports exporter parameters.

WARNING: Implementors should not use response.setCharacterEncoding unless they are willing to depend on Servlet API 2.4 or higher. Prefer a concatenated content type String with a charset clause instead.

Parameters
populatedReport the populated JasperPrint to render
model the map containing report parameters
response the HTTP response the report should be rendered to
Throws
Exception if rendering failed
See Also

protected void setConvertedExporterParameters (Map<JRExporterParameter, Object> convertedExporterParameters)

Allows subclasses to populate the converted exporter parameters.