net.sf.jasperreports.engine.export

Class JRTextExporter

java.lang.Object

net.sf.jasperreports.engine.JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

net.sf.jasperreports.engine.export.JRTextExporter

All Implemented Interfaces:

JRExporter<ExporterInput,TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput>, Exporter<ExporterInput,TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput>

public class JRTextExporter
extends JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

Exports filled reports in plain text format. The text exporter allows users to define a custom character resolution (the number of columns and rows in text format). Since the character resolution is mapped on the actual pixel resolution, every character corresponds to a rectangle of pixels. If a certain text element has a smaller size in pixels (width, height, or both) than the number of pixels that map to a character, the text element will not be rendered.

The text exporter will yield the better results if the space needed for displaying a text is large. So users have to either design reports with few text or export to big text pages. Another good practice is to arrange text elements at design time as similar as possible to a grid.

The text exporter tries to convert the JasperReports document into a simple text document with a fixed page width and height, measured in characters. Users can specify the desired page width and height, and the engine will make the best effort to fit text elements into the corresponding text page. The basic idea of the algorithm is to convert pixels to characters (to find a pixel/character ratio). To achieve this, use the following configuration settings (see TextReportConfiguration):

• getCharWidth() and getCharHeight() - these specify how many pixels in the original report should be mapped onto a character in the exported text.
• getPageWidthInChars() and getPageHeightInChars() - these specify the text page width and height in characters.

Note that both width and height must be specified and that character sizes have priority over page sizes.

Since the algorithm causes loss of precision, a few precautions should be taken when creating templates that will eventually be exported to plain text:

• Report sizes and text page sizes should be divisible (for example, specify a template width of 1,000 pixels and a page width of 100 characters, resulting in a character width of 10 pixels).
• Text element sizes should also follow the preceding rule (for example, if the character height is 10 pixels and a particular text element is expected to span two rows, then the text element should be 20 pixels tall).
• For best results, text elements should be aligned in a grid-like fashion.
• Text fields should not be too small. Following are two examples of problems that this can cause:
  • If the element height is smaller than the character height, then the element will not appear in the exported text file.
  • If the character width is 10 and the element width is 80, then only the first eight characters will be displayed.

Users can specify the text that should be inserted between two subsequent pages by using the getPageSeparator() exporter configuration setting. The default value is two blank lines.

The line separator to be used in the generated text file can be specified using the getLineSeparator() exporter configuration setting. This is most useful when you want to force a particular line separator, knowing that the default line separator is operating system dependent, as specified by the line.separator system property of the JVM.

Check the supplied /demo/samples/text sample to see the kind of output this exporter can produce.

Author:

Ionut Nedelcu (ionutned@users.sourceforge.net)

See Also:

TextExporterConfiguration, TextReportConfiguration

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	JRTextExporter.ExporterContext

Nested classes/interfaces inherited from class net.sf.jasperreports.engine.JRAbstractExporter

JRAbstractExporter.BaseExporterContext, JRAbstractExporter.PageRange

Field Summary

Fields

Modifier and Type	Field and Description
protected float	charHeight
protected float	charWidth
static String	EXCEPTION_MESSAGE_KEY_CHARACTER_HEIGHT_NEGATIVE
static String	EXCEPTION_MESSAGE_KEY_CHARACTER_WIDTH_NEGATIVE
static String	EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_HEIGHT
static String	EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_WIDTH
protected boolean	isTrimLineRight
protected String	lineSeparator
protected int	pageHeightInChars
protected String	pageSeparator
protected int	pageWidthInChars
protected static String	systemLineSeparator
protected Writer	writer

Fields inherited from class net.sf.jasperreports.engine.JRAbstractExporter

allSelector, crtCompositeConfiguration, crtCompositeItemConfiguration, crtItem, dateFormatCache, EXCEPTION_MESSAGE_KEY_END_PAGE_INDEX_OUT_OF_RANGE, EXCEPTION_MESSAGE_KEY_INVALID_IMAGE_NAME, EXCEPTION_MESSAGE_KEY_INVALID_ZOOM_RATIO, EXCEPTION_MESSAGE_KEY_MIXED_CALLS_NOT_ALLOWED, EXCEPTION_MESSAGE_KEY_OUTPUT_WRITER_ERROR, EXCEPTION_MESSAGE_KEY_PAGE_INDEX_OUT_OF_RANGE, EXCEPTION_MESSAGE_KEY_START_PAGE_INDEX_OUT_OF_RANGE, exporterConfiguration, exporterContext, exporterInput, exporterOutput, filter, itemConfiguration, jasperPrint, jasperReportsContext, noBackcolorSelector, noneSelector, numberFormatCache, parameters, propertiesUtil, PROPERTY_DEFAULT_FILTER_FACTORY, PROPERTY_SUFFIX_DEFAULT_FILTER_FACTORY, styledTextUtil, textValueClasses

Constructor Summary

Constructors

Constructor and Description
JRTextExporter()
JRTextExporter(JasperReportsContext jasperReportsContext)

Method Summary

Methods

Modifier and Type	Method and Description
protected void	ensureOutput()
protected void	exportElements(List<JRPrintElement> elements)
protected void	exportPage(JRPrintPage page) Exports a page to the output writer.
void	exportReport() Performs the export.
protected void	exportReportToWriter()
protected void	exportText(JRPrintText element) Renders a text and places it in the output matrix.
protected Class<TextExporterConfiguration>	getConfigurationInterface()
String	getExporterKey()
String	getExporterPropertiesPrefix() Returns the properties prefix for the current exporter.
protected int	getHeightInChars(int height) Transforms height from pixel space to character space.
protected Class<TextReportConfiguration>	getItemConfigurationInterface()
protected JRStyledText	getStyledText(JRPrintText textElement)
protected int	getWidthInChars(int width) Transforms width from pixel space to character space.
protected void	initExport()
protected void	initReport()

Methods inherited from class net.sf.jasperreports.engine.JRAbstractExporter

createFilter, defaultParseNumber, ensureInput, ensureJasperReportsContext, getBooleanCellValue, getCurrentConfiguration, getCurrentItemConfiguration, getCurrentJasperPrint, getCustomHandler, getDateCellValue, getDateFormat, getExporterContext, getExporterInput, getExporterOutput, getHyperlinkProducer, getJasperReportsContext, getLocale, getNumberCellValue, getNumberFormat, getOffsetX, getOffsetY, getPageRange, getParameter, getParameters, getPropertiesUtil, getReportContext, getStyledText, getTextFormatFactoryClass, getTextLocale, getTextTimeZone, getTextValue, getTextValueString, insideFrame, reset, resetClassLoader, resetExportContext, restoreElementOffsets, setClassLoader, setConfiguration, setConfiguration, setCurrentExporterInputItem, setExporterInput, setExporterOutput, setFrameElementsOffset, setJasperPrint, setJasperReportsContext, setOffset, setOffset, setParameter, setParameters, setReportContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_WIDTH

public static final String EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_WIDTH

See Also:

Constant Field Values

EXCEPTION_MESSAGE_KEY_CHARACTER_WIDTH_NEGATIVE

public static final String EXCEPTION_MESSAGE_KEY_CHARACTER_WIDTH_NEGATIVE

See Also:

Constant Field Values

EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_HEIGHT

public static final String EXCEPTION_MESSAGE_KEY_REQUIRED_POSITIVE_PAGE_OR_CHARACTER_HEIGHT

See Also:

Constant Field Values

EXCEPTION_MESSAGE_KEY_CHARACTER_HEIGHT_NEGATIVE

public static final String EXCEPTION_MESSAGE_KEY_CHARACTER_HEIGHT_NEGATIVE

See Also:

Constant Field Values

writer

protected Writer writer

pageWidthInChars

protected int pageWidthInChars

pageHeightInChars

protected int pageHeightInChars

charWidth

protected float charWidth

charHeight

protected float charHeight

pageSeparator

protected String pageSeparator

lineSeparator

protected String lineSeparator

isTrimLineRight

protected boolean isTrimLineRight

systemLineSeparator

protected static final String systemLineSeparator

Constructor Detail

JRTextExporter

public JRTextExporter()

See Also:

JRTextExporter(JasperReportsContext)

JRTextExporter

public JRTextExporter(JasperReportsContext jasperReportsContext)

Method Detail

getConfigurationInterface

protected Class<TextExporterConfiguration> getConfigurationInterface()

Specified by:

getConfigurationInterface in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

getItemConfigurationInterface

protected Class<TextReportConfiguration> getItemConfigurationInterface()

Specified by:

getItemConfigurationInterface in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

ensureOutput

protected void ensureOutput()

Specified by:

ensureOutput in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

exportReport

public void exportReport()
                  throws JRException

Description copied from interface: Exporter

Performs the export.

Specified by:

exportReport in interface Exporter<ExporterInput,TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput>

Specified by:

exportReport in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

Throws:

JRException

initExport

protected void initExport()

Overrides:

initExport in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

initReport

protected void initReport()

Overrides:

initReport in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

exportReportToWriter

protected void exportReportToWriter()
                             throws JRException,
                                    IOException

Throws:

JRException

IOException

exportPage

protected void exportPage(JRPrintPage page)
                   throws IOException

Exports a page to the output writer. Only text elements within the page are considered. For each page, the engine creates a matrix of characters and each rendered text element is placed at the appropriate position in the matrix. After all texts are parsed, the character matrix is sent to the output writer.

Throws:

IOException

exportElements

protected void exportElements(List<JRPrintElement> elements)

exportText

protected void exportText(JRPrintText element)

Renders a text and places it in the output matrix.

getHeightInChars

protected int getHeightInChars(int height)

Transforms height from pixel space to character space.

getWidthInChars

protected int getWidthInChars(int width)

Transforms width from pixel space to character space.

getStyledText

protected JRStyledText getStyledText(JRPrintText textElement)

Overrides:

getStyledText in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

getExporterKey

public String getExporterKey()

Specified by:

getExporterKey in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

getExporterPropertiesPrefix

public String getExporterPropertiesPrefix()

Description copied from class: JRAbstractExporter

Returns the properties prefix for the current exporter.

Specified by:

getExporterPropertiesPrefix in class JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>

Returns:

the properties prefix for the current exporter