# Package net.sf.jasperreports.engine.fill

Contains fill time implementations for the library's main interfaces and the entire engine used in the filling process (the actual core of JasperReports).

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AsynchronousFilllListener | Listener interface for the asynchronous filling method.
  DatasetExpressionEvaluator |
  DatasetFillContext | Context information related to a fill time dataset.
  DynamicPropertiesHolder |
  FillContainerContext | A fill context provides access to data and functionality related to a report component fill.
  FillHandle | Interface implemented by classes that are used to perform report filling asychronously.
  FillListener | Listener notified of page events during a report generation.
  FillReturnValues.SourceContext |
  JasperReportsContextAware |
  JRBaseFiller.DefaultStyleListener |
  JRCalculable | Interface for objects that can be used by extended incrementers for calculations.
  JRExtendedIncrementer | Extended incrementer interface.
  JRExtendedIncrementerFactory | Extended incrementer factory interface.
  JRFillCloneable | Interface of elements that can be cloned at fill time.
  JRFillContext.FillCacheDisposable |
  JRFillDataset.CacheRecordIndexCallback |
  JRFillExpressionEvaluator | Fill time expression evaluators interface.
  JRIncrementer |
  JRIncrementerFactory |
  JRMeasuredText | Text measuring information as produced by a `text measurer`.
  JROriginProvider | A provider of `JROrigin` instances, used by report elements at fill time.
  JRRecordedValuesPrintElement | Interface implemented by print elements that can record field/variable values.
  JRSubreportRunner | Subreport runner interface.
  JRSubreportRunnerFactory | Factory of `JRSubreportRunner` instances.
  JRTextMeasurer | Text measurer interface.
  JRTextMeasurerFactory | Deprecated Replaced by `JRTextMeasurerFactory`.
  PrintElementOriginator | Default `PrintElementOriginator` implementation.
  TextFormat |
  TextLine |
  TextLineWrapper |
  TextMeasureContext |
  VirtualizationListener<T> | Listener that plugs into the virtualization process.
  VirtualizerStore |
  VirtualizerStoreFactory |

- Class Summary
  Class | Description
  --- | ---
  AbstractThreadSubreportRunner |
  AbstractValueProvider |
  AsynchronousFillHandle | Class used to perform report filling asychronously.
  BaseFillHandle | Base class used to perform report filling asychronously.
  CachingLineBox |
  CachingParagraph |
  ComplexTextLineWrapper |
  CompositeFillListener | `FillListener` implementation that contains several other listeners.
  DatasetSortUtil |
  DefaultChartTheme |
  DefaultPrintElementOriginator | Default `PrintElementOriginator` implementation.
  FillDatasetPosition | Position that uniquely identifies a dataset instantiation as part of a fill process.
  FillFunctionContext |
  FillReturnValues |
  FillStyleProviderContext |
  JRAbstractExtendedIncrementer | Base class for extended incrementers.
  JRAbstractExtendedIncrementerFactory | Base abstract implementation of `JRExtendedIncrementerFactory`.
  JRAbstractLRUVirtualizer | Abstract base for LRU and serialization based virtualizer
  JRAbstractLRUVirtualizer.CacheReference |
  JRBaseFiller |
  JRBigDecimalIncrementerFactory |
  JRByteIncrementerFactory |
  JRCalculator | Evaluates JasperReports expressions.
  JRClonePool | Working clones pooling utility used at fill time.
  JRComparableIncrementerFactory |
  JRContinuationSubreportRunner | Implemetation of `JRSubreportRunner` using Javaflow continuations.
  JRContinuationSubreportRunnerFactory | `JRContinuationSubreportRunner` subreport runners factory.
  JRDefaultIncrementerFactory |
  JRDistinctCountExtendedIncrementerFactory |
  JRDistinctCountIncrementerFactory |
  JRDoubleIncrementerFactory |
  JREvaluationTime | An evaluation time during the report fill process.
  JREvaluator | Base class for the dynamically generated expression evaluator classes.
  JRFileVirtualizer | Virtualizes data to the filesystem.
  JRFillBand |
  JRFillBreak |
  JRFillCellContents | Crosstab cell contents filler.
  JRFillCellContents.BoxContents |
  JRFillCellContents.StretchedContents |
  JRFillChart |
  JRFillChartDataset |
  JRFillChartPlot |
  JRFillCloneFactory | Factory class used for fill-time working clones creation.
  JRFillComponentElement | A `JRComponentElement` which is used during report fill.
  JRFillContext | Context class shared by all the fillers involved in a report (master and subfillers).
  JRFillCrosstab | Fill-time implementation of a `crosstab`.
  JRFillDataset |
  JRFillDataset.CacheRecordIndexChainedCallback |
  JRFillDataset.FillDatasetPositionRecordIndexCallback |
  JRFillDataset.VariableCalculationReq | Class used to hold expression calculation requirements.
  JRFillDatasetRun | Class used to instantiate sub datasets.
  JRFillDatasetScriptlet |
  JRFillElement |
  JRFillElementContainer | Abstract implementation of an element container filler.
  JRFillElementDataset | Abstract `JRElementDataset` implementation used at report fill time.
  JRFillElementGroup |
  JRFillEllipse |
  JRFiller |
  JRFillField |
  JRFillFrame | Fill time implementation of a frame element.
  JRFillGenericElement | A `JRGenericElement` used during report fill.
  JRFillGraphicElement |
  JRFillGroup |
  JRFillHyperlinkHelper | Utility class used to evaluate custom hyperlink parameters.
  JRFillImage |
  JRFillLine |
  JRFillObjectFactory | A factory used to instantiate fill objects based on compiled report objects.
  JRFillObjectFactory.StylesList |
  JRFillParameter |
  JRFillRectangle |
  JRFillReportTemplate | Fill-time `JRReportTemplate` implementation.
  JRFillScriptlet |
  JRFillSection |
  JRFillStaticText |
  JRFillSubreport |
  JRFillSubreportReturnValue | Implementation of `JRSubreportReturnValue` used by the filler.
  JRFillTextElement |
  JRFillTextField |
  JRFillVariable |
  JRFloatIncrementerFactory |
  JRGzipVirtualizer | GZips the pages that it doesn't need, but keeps them in memory.
  JRHorizontalFiller |
  JRIncrementerFactoryCache |
  JRIntegerIncrementerFactory |
  JRLongIncrementerFactory |
  JRParameterDefaultValuesEvaluator | Utility class to be used to evaluate parameter default value expressions for a report without actually filling it.
  JRParameterDefaultValuesEvaluator.ObjectFactory |
  JRPrintBand |
  JRPrintBand.ElementsIterator |
  JRPrintBand.OffsetElements |
  JRRecordedValues | Recorded values container used by elements with `Auto evaluation time`.
  JRRecordedValuesGenericPrintElement | Generic print element implementation that supports recorded values.
  JRRecordedValuesPrintImage | Print image implementation that supports recorded values.
  JRRecordedValuesPrintText | Print text implementation that supports recorded values.
  JRResourcesFillUtil | Resources utility class used for report fills.
  JRResourcesFillUtil.ResourcesFillContext |
  JRShortIncrementerFactory |
  JRSubreportRunnable | Abstract base for `Runnable`-based `JRSubreportRunner` implementations.
  JRSubreportRunResult | A result returned by `JRSubreportRunner.start()` or `JRSubreportRunner.resume()`.
  JRSwapFileVirtualizer | A virtualizer that uses a single swap file to serialize virtual data.
  JRTemplateElement | Base class consisting of print element information shared by multiple print elements.
  JRTemplateEllipse | Ellipse information shared by multiple print ellipse objects.
  JRTemplateFrame | Frame information shared by multiple print frame objects.
  JRTemplateGenericElement | Generic print element information shared by multiple elements.
  JRTemplateGenericPrintElement | Implementation of `JRGenericPrintElement` that uses a `JRTemplateGenericElement` instance to store common attributes.
  JRTemplateGraphicElement | Base class consisting of graphic print element information shared by multiple print element instances.
  JRTemplateImage | Image information shared by multiple print image objects.
  JRTemplateLine | Line element information shared by multiple print line objects.
  JRTemplatePrintElement | Base implementation of `JRPrintElement` that uses a `JRTemplateElement` instance to store common attributes.
  JRTemplatePrintEllipse | Base implementation of `JRPrintEllipse` that uses a `JRTemplateEllipse` instance to store common attributes.
  JRTemplatePrintFrame | Implementation of `JRPrintFrame` that uses `template frames` to store common attributes.
  JRTemplatePrintGraphicElement | Base implementation of `JRPrintGraphicElement` that uses a `JRTemplateGraphicElement` instance to store common attributes.
  JRTemplatePrintImage | Implementation of `JRPrintImage` that uses a `JRTemplateImage` instance to store common attributes.
  JRTemplatePrintLine | Implementation of `JRPrintLine` that uses a `JRTemplateLine` instance to store common attributes.
  JRTemplatePrintRectangle | Implementation of `JRPrintRectangle` that uses a `JRTemplateRectangle` instance to store common attributes.
  JRTemplatePrintText | Implementation of `JRPrintText` that uses a `JRTemplateText` instance to store common attributes.
  JRTemplateRectangle | Rectangle information shared by multiple print rectangle objects.
  JRTemplateText | Text element information shared by multiple print text objects.
  JRThreadSubreportRunner | Thread-based `JRSubreportRunner` implementation.
  JRThreadSubreportRunnerFactory | `JRThreadSubreportRunner` subreport runners factory.
  JRVerticalFiller |
  JRVirtualizationContext | Context used to store data shared by virtualized objects resulted from a report fill process.
  JRYComparator |
  JRYXComparator |
  SimpleTextFormat |
  SimpleTextLine |
  SimpleTextLineWrapper |
  SimpleTextLineWrapper.ElementFontInfo |
  SimpleTextLineWrapper.FontInfo |
  SimpleTextLineWrapper.FontKey |
  SimpleTextLineWrapper.FontStatistics |
  SortedDataSource |
  SortedDataSource.SortRecord |
  StoreFactoryVirtualizer |
  StoreVirtualizer |
  TextLayoutLine |
  TextMeasurer | Default text measurer implementation.
  TextMeasurer.TextMeasuredState |
  TextMeasurerFactory | Default text measurer factory.
  ThreadExecutorSubreportRunner | Thread-based `JRSubreportRunner` implementation.
  ThreadPoolSubreportRunnerFactory |
  ThreadPoolSubreportRunnerFactory.ExecutorServiceDisposable |
  ThreadPoolSubreportRunnerFactory.SubreportsThreadFactory |
  VirtualizationObjectInputStream | `java.io.ObjectInputStream` subclass used for deserializing report data on virtualization.
  VirtualizationObjectOutputStream | `java.io.ObjectOutputStream` subclass used for serializing report data on virtualization.

- Exception Summary
  Exception | Description
  --- | ---
  JRExpressionEvalException |
  JRFillInterruptedException |
  JRReadOnlyPropertyException |

## Package net.sf.jasperreports.engine.fill Description

Contains fill time implementations for the library's main interfaces and the entire engine used in the filling process (the actual core of JasperReports).

### Filling Report Templates

The report-filling process is the most important piece of JasperReports library functionality, because it manipulates sets of data to produce high-quality documents. This is the main purpose of any reporting tool.

The following things should be supplied to the report-filling process as input:

- a report template (in the compiled form)
- parameters
- data source

The output is always a single, final `JasperPrint` document ready to be viewed, printed, or exported to other formats.

The `JasperFillManager` class is usually used for filling a report template with data. This class has various methods that fill report templates located on disk, come from input streams, or are supplied directly as in-memory `JasperReport` objects. After getting the report template, the report filling methods are calling the related `fill(...)` method in the `JRFiller` class, that actually fills the report.

The output produced always corresponds to the type of input received. That is, when receiving a file name for the report template, the generated report is also placed in a file on disk. When the report template is read from an input stream, the generated report is written to an output stream, and so forth.

The various utility methods for filling the reports may not be sufficient for a particular application - for example, loading report templates as resources from the classpath and outputting the generated documents to files on disk at a certain location.

In such cases, manually loading the report template objects is to be considered before passing them to the report-filling routines using the `JRLoader` utility class. This way, one can retrieve report template properties, such as the report name, to construct the name of the resulting document and place it at the desired disk location.

The report-filling manager class covers only the most common scenarios. However, you can always customize the report-filling process using the library's basic functionality just described.

### Generated Reports

The output of the report-filling process is always a pixel-perfect document, ready for viewing, printing, or exporting to other formats. These documents come in the form of `JasperPrint` objects, which are serializable. This allows the parent application to store them or transfer them over the network if needed.

At the top level, a `JasperPrint` object contains some document-specific information, like the name of the document, the page size, and its orientation (portrait or landscape). Then it points to a collection of page objects (`JRPrintPage` instances), each page having a collection of elements that make up its content. Elements on a page are absolutely positioned at x and y coordinates within that page and have a specified width and height in pixels. They can be lines, rectangles, ellipses, images, or text, with various style settings corresponding to their type.

JasperReports templates allow the detail section to be smaller than the specified page width so that the output can be structured into multiple columns, like a newspaper.

When multiple-column report templates are used, the order used for filling those columns is important. There are two possible column orders, that can be set in the report template using the `printOrder` attribute:

- `Vertical` - meaning that they run from top to bottom and then from left to right. This is the default order. The report filling process is provided by the `JRVerticalFiller` class.
- `Horizontal` - meaning that they first run from left to right and then from top to bottom. In this case the report is filled using methods in the `JRHorizontalFiller` class.

When filling report templates horizontally, dynamic text fields inside the detail section do not stretch to their entire text content, because this might cause misalignment on the horizontal axis of subsequent detail sections. The detail band actually behaves the same as the page and column footers, preserving its declared height when horizontal filling is used.

### Asynchronous Report Filling

JasperReports provides the `AsynchronousFillHandle` class to be used for asynchronous report filling. The main benefit of this method is that the filling process can be canceled if it takes too much time. This can be useful, for example, in GUI applications where the user would be able to abort the filling after some time has elapsed and no result has been yet produced.

When using this method, the filling is started on a new thread. The caller is notified about the progress of the filling process by way of listeners implementing the `AsynchronousFilllListener` interface. The listeners are notified of the outcome of the filling process, which can be success, failure, or user cancellation. The handle is used to start the filling process, register listeners, and cancel the process if wanted.

A typical usage of this handle is the following:

- The handle is created by calling the static `AsynchronousFillHandle.createHandle()` methods that take as arguments the report object, the parameter map, and the data source or the database connection to be used.
- One or more listeners are registered with the handle by calling the `addListener()` method. In a GUI application, the listener could perform some actions to present to the user the outcome of the filling process.
- The filling is started with a call to the `startFill()` method. In a GUI application, this could be the result of some user action; the user can also be notified that the filling has started and is in progress.
- The filling can be canceled by calling `cancellFill()` on the handle. In a GUI, this would be the result of a user action.
- The listeners are notified when the process finishes. There are three events defined for the listeners, only one of which will be called, depending on the outcome of the filling:
  - `reportFinished()` - called when the filling has finished successfully; the filled report is passed as a parameter. In a GUI, the user would be presented the filled report or would be able to save/export it.
  - `reportFillError()` - called when the filling ends in error; the exception that occurred is passed as a parameter.
  - `reportCancelled()` - called when the filling is aborted by the user.

### Large File Support

If very large datasets are used for report filling, the size of the resulting `JasperPrint` object could also be very large and might cause the JVM to run out of memory.

To increase the memory available for the Java application, first use the `-Xmx` option when launching the JVM, since the default value for this parameter is fairly small. However, if you do this with large datasets (for example, containing tens of thousands or more records and resulting in documents that have thousands or more pages), the JVM may run out of memory.

JasperReports offers a simple solution to the problem by introducing the report virtualizer. The virtualizer is a simple interface (`JRVirtualizer`) that enables the reporting engine to optimize memory consumption during report filling by removing parts of the JasperPrint object from memory and storing them on disk or in other temporary locations. If a report virtualizer is used during filling, the engine keeps only a limited number of pages from the generated JasperPrint object at a time and serializes all the other pages to a temporary storage location, usually the file system.

Using a report virtualizer is very simple. You supply an instance of the `JRVirtualizer` interface as the value for the built-in `REPORT_VIRTUALIZER` parameter when filling the report.

In virtualized form, a generated `JasperPrint` document still behaves normally and can be subject to exporting, printing, or viewing processes, and the impact on memory consumption is minimal even when dealing with very large documents.

When produced using a virtualizer (which itself performs partial document serialization into temporary files), once completed, a `JasperPrint` document can itself be serialized normally without any loss of information. During the serialization of a virtualized `JasperPrint` object, the program puts back together all the pieces and a single serialized file is produced. However, because this single file is probably very large, simple deserialization would not make sense (in fact, it wouldn't be possible, as the JVM would run out of memory, which is the reason for using virtualization in the first place). So in order to reload into memory a virtualized document that was serialized to a permanent storage facility, a report virtualizer is needed. This would be set using a local thread variable by calling the following:

     JRVirtualizationHelper.setThreadVirtualizer(JRVirtualizer virtualizer)

### File virtualizer

The library ships with a ready-to-use implementation of this interface called `JRFileVirtualizer`, which stores document pages on disk during the filling process to free up memory. Once a `JasperPrint` object is produced using a report virtualizer, it can be exported to other formats or viewed directly using the library's built-in viewer component, even though this document is not fully loaded at any one time. The virtualizer ensures that pages are deserialized and loaded from their temporary storage location as needed during exporting or display. A single `JRFileVirtualizer` instance can be shared across multiple report-filling processes so that the number of document pages kept in-memory at any one time will be limited by the virtualizer `maxSize` property, regardless of the number of reports that are generated simultaneously.

Because it works with temporary files on disk, the file virtualizer has a built-in mechanism to remove those files after they are no longer needed (that is, after the generated document or the virtualizer itself have been disposed of by the JVM). The `cleanup()` method exposed by this virtualizer implementation can be also called manually so that the temporary files are removed from disk right away instead of after the finalization of the entities involved.

To ensure that no virtualization files are left over on disk by the application that uses the file virtualizer, all these temporary files are registered with the JVM so that they are deleted automatically when the JVM exits normally.

But using `File.deleteOnExit()` will accumulate JVM process memory on some virtual machine implementations (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4513817); you should avoid using this feature in long-running applications by turning it off using the `net.sf.jasperreports.virtualizer.files.delete.on.exit` configuration property.

### Swap File Virtualizer

On some platforms, working with a large number of files in a single folder, or even the file manipulating processes themselves, may have a significant impact on performance or pose additional problems. This makes the use of the `JRFileVirtualizer` implementation less effective.

Fortunately, there is another implementation of a file-based report virtualizer that uses a single swap file and can also be shared among multiple report-filling processes. Instead of having one temporary file per virtualized page, we create a single file into which all virtualized pages are stored to and then retrieved from.

This swap file virtualizer implementation is represented by the `JRSwapFileVirtualizer` class that is part of the JasperReports library core functionality, and works in combination with a `JRSwapFile` instance representing the target swap file.

The `JRSwapFile` instance has to be created and configured prior to being passed to the swap virtualizer. You can create such an instance by specifying the target directory where the swap file will be created, the size of the blocks allocated by the swap file, and the minimum number of blocks by which the swap file will grow when its current size becomes insufficient.

The `JRConcurrentSwapFile` class represents an enhanced implementation of the JRSwapFile that only works with JRE version 1.4 or later, because it uses a `java.nio.channels.FileChannel` to perform concurrent I/O on the swap file.

### In-Memory GZIP Virtualizer

The `JRGzipVirtualizer` is a convenient report virtualizer implementation that does not rely on the file system to temporarily store unused/virtualized document pages during the report filling. Rather, it optimizes memory consumption by compressing those pages in-memory using a GZIP algorithm. Tests indicate that memory consumption during large report-generating processes is reduced up to a factor of ten when the in-memory GZIP report virtualizer is used.

### Related Documentation

JasperReports Tutorial

See Also:
  `JasperFillManager`, `JasperPrint`, `JasperReport`, `JRPrintPage`, `JRVirtualizer`, `JRConcurrentSwapFile`, `JRLoader`, `JRSwapFile`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com