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.
  Version:
    $Id: JRTextExporter.java 7067 2014-04-30 09:32:46Z shertage $
  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`
    `protected java.lang.String` | `lineSeparator`
    `protected int` | `pageHeightInChars`
    `protected java.lang.String` | `pageSeparator`
    `protected int` | `pageWidthInChars`
    `protected static java.lang.String` | `systemLineSeparator`
    `protected java.io.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_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`

  - ### 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(java.util.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 java.lang.Class<TextExporterConfiguration>` | `getConfigurationInterface()`
    `java.lang.String` | `getExporterKey()`
    `java.lang.String` | `getExporterPropertiesPrefix()` Returns the properties prefix for the current exporter.
    `protected int` | `getHeightInChars(int height)` Transforms height from pixel space to character space.
    `protected java.lang.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, 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

    - #### writer

          protected java.io.Writer writer

    - #### pageWidthInChars

          protected int pageWidthInChars

    - #### pageHeightInChars

          protected int pageHeightInChars

    - #### charWidth

          protected float charWidth

    - #### charHeight

          protected float charHeight

    - #### pageSeparator

          protected java.lang.String pageSeparator

    - #### lineSeparator

          protected java.lang.String lineSeparator

    - #### systemLineSeparator

          protected static final java.lang.String systemLineSeparator

  - ### Constructor Detail

    - #### JRTextExporter

          public JRTextExporter()

      See Also:
        `JRTextExporter(JasperReportsContext)`

    - #### JRTextExporter

          public JRTextExporter(JasperReportsContext jasperReportsContext)

  - ### Method Detail

    - #### getConfigurationInterface

          protected java.lang.Class<TextExporterConfiguration> getConfigurationInterface()

      Specified by:
        `getConfigurationInterface` in class `JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>`

    - #### getItemConfigurationInterface

          protected java.lang.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,
                                              java.io.IOException

      Throws:
        `JRException`
        `java.io.IOException`

    - #### exportPage

          protected void exportPage(JRPrintPage page)
                             throws java.io.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:
        `java.io.IOException`

    - #### exportElements

          protected void exportElements(java.util.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 java.lang.String getExporterKey()

      Specified by:
        `getExporterKey` in class `JRAbstractExporter<TextReportConfiguration,TextExporterConfiguration,WriterExporterOutput,JRTextExporterContext>`

    - #### getExporterPropertiesPrefix

          public java.lang.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

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com