public interface JRSubreport extends JRElement
<subreport>tag in the JRXML file. A subreport is in fact a normal report that has been incorporated into another report. You can overlap subreports or make a subreport that contains other subreports, up to any level of nesting. Subreports are compiled and filled just like normal reports. Any report template can be used as a subreport when incorporated into another report template, without anything inside it having to change. Just like normal report templates, subreport templates are in fact
JasperReportobjects, which are obtained after compiling a
JasperDesignobject. Subreport elements have an expression that is evaluated at runtime to obtain the source of the
JasperReportobject to load. The so-called subreport expression is introduced by the
getExpression()) and can return values from the following classes:
java.lang.Stringvalue, the engine tries to see whether the value represents a URL from which to load the subreport template object. If the value is not a valid URL representation, then the engine will try to locate a file on disk and load the subreport template from it, assuming that the value represents a file name. If no file is found, it will finally assume that the string value represents the location of a classpath resource and will try to load the subreport template from there. Only if all those fail will an exception be thrown.
getUsingCache()is set to true, the reporting engine will try to recognize previously loaded subreport template objects, using their specified source. For example, it will recognize a subreport object if its source is a file name that it has already loaded, or if it is the same URL. This caching functionality is available only for subreport elements that have expressions returning
java.lang.Stringobjects as the subreport template source, representing file names, URLs, or classpath resources. That's because the engine uses the subreport source string as the key to recognize that it is the same subreport template that it has cached.
fillReportXXX()methods exposed by the
JasperFillManagerclass. To do this, use the
getParametersMapExpression()), which introduces the expression that will be evaluated to obtain the specified parameters map. This expression should always return a
java.util.Mapobject in which the keys are the parameter names. In addition to (or instead of) supplying the parameter values in a map, you can supply the parameter values individually, one by one, using a
getParameters()) for each relevant parameter. To do this, specify the name of the corresponding parameter using the mandatory
nameattribute and provide an expression that will be evaluated at runtime to obtain the value for that particular parameter, the value that will be supplied to the subreport-filling routines. Note that you can use both ways to provide subreport parameter values simultaneously. When this happens, the parameter values specified individually, using the
<subreportParameter>element, override the parameter values present in the parameters map that correspond to the same subreport parameter. If the map does not contain corresponding parameter values already, the individually specified parameter values are added to the map. Caution: When you supply the subreport parameter values, be aware that the reporting engine will affect the
java.util.Mapobject it receives, adding the built-in report parameter values that correspond to the subreport. This map is also affected by the individually specified subreport parameter values, as already explained. To avoid altering the original java.util.Map object that you send, wrap it in a different map before supplying it to the subreport-filling process, as follows:
new HashMap(myOriginalMap)This way, the original map object remains unaffected and modifications are made to the wrapping map object. This is especially useful when you want to supply to the subreport the same set of parameters that the master report has received and you are using the built-in
REPORT_PARAMETERS_MAPreport parameter of the master report. However, you don't want to affect the value of this built-in parameter, so a clone of the original map needs to be used. Starting with JasperReports 3.0.1,
REPORT_PARAMETERS_MAPis automatically cloned when it is used as subreport parameters map.
getDataSourceExpression()) or a JDBC connection (see
getConnectionExpression()) for the engine to execute the subreport's internal SQL query using the
<connectionExpression>element. These two XML elements cannot both be present at the same time in a
<subreport>element declaration. This is because you cannot supply both a data source and a connection for your subreport. The report engine expects that the data source expression will return a
JRDataSourceobject or that the connection expression will return a
java.sql.Connnectionobject - whichever is present.
getReturnValues()) can be used inside a
<subreport>to specify values to be returned from the subreport. A subreport return value is represented by the
JRSubreportReturnValueclass that provides information about the subreport variable, master variable, calculation type and incrementer factory. Note that the value from the subreport is not returned on a column or page break, but only when the subreport filling is done. Also note that the calculation is a two-level process - that is, if the subreport computes a total average and the master accumulates values from the subreports using calculated averages, then the master result will be the average of the subreport averages, not the average of the combined subreport records.
JRSubreportRunnable, which would have two interchangeable implementations:
JRThreadSubreportRunner- The initial thread-based implementation
JRContinuationSubreportRunner- A Javaflow-based implementation
net.sf.jasperreports.subreport.runner.factory. This configuration property should point to a
JRSubreportRunnerFactoryimplementation able to produce the needed
JRSubreportRunnableobjects at runtime. That could be one of the following two:
JRThreadSubreportRunnerFactory, for backward-compatibility reasons. Note: A special JasperReports JAR file built using Javaflow byte code instrumentation is available for download with each JasperReports release and should be used when Java Continuations support during subreport filling is needed. In such cases, the Jakarta Commons Javaflow library is required; it can be found in the /lib directory of the JasperReports project distribution package.
|Modifier and Type||Method and Description|
Returns the list of subreport copied values.
Indicates if the engine is loading the current subreport from cache.
Specifies whether the subreport element will consume the entire vertical space available on the report page.
Sets the flag that Specifies whether the subreport element will consume the entire vertical space available on the report page.
Specifies if the engine should be loading the current subreport from cache.
clone, collectExpressions, getElementGroup, getKey, getPositionTypeValue, getPrintWhenExpression, getPrintWhenGroupChanges, getPropertyExpressions, getStretchTypeValue, getX, getY, isPrintInFirstWholeBand, isPrintRepeatedValues, isPrintWhenDetailOverflows, isRemoveLineWhenBlank, setPositionType, setPrintInFirstWholeBand, setPrintRepeatedValues, setPrintWhenDetailOverflows, setRemoveLineWhenBlank, setStretchType, setWidth, setX
getBackcolor, getForecolor, getHeight, getModeValue, getOwnBackcolor, getOwnForecolor, getOwnModeValue, getWidth, setBackcolor, setForecolor, setMode
getDefaultStyleProvider, getStyle, getStyleNameReference
getParentProperties, getPropertiesMap, hasProperties
void setUsingCache(java.lang.Boolean isUsingCache)
If set to null, the engine will rely on some default value which depends on the type of the subreport expression. The cache is turned on by default only for subreports that have java.lang.String objects in their expressions.
void setRunToBottom(java.lang.Boolean runToBottom)
This flag should be set to
true if the subreport needs to always
print its column and page footers at the bottom of the report page, even when
the subreport data does not stretch to the bottom.
Note that when
is set for the subreport, the column footers will not be printed at the bottom
of the page even if this flag is set.
runToBottom- whether the subreport element will consume the entire space down to the bottom of the page
void setOverflowType(OverflowType overflowType)
© 2001 - 2018 TIBCO Software Inc. www.jaspersoft.com