de.vc.jfo.renderer

## Class Renderer

- java.lang.Object
- - de.vc.jfo.renderer.Renderer

- All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable
  Direct Known Subclasses:
    CompositeRenderer, FOP0205Renderer, FOP1Renderer, Ibex3Renderer, PlainRenderer, XEP4Renderer, XincRenderer, XMLTreeViewer, XSLFormatter3Renderer, XSLTRenderer

      public abstract class Renderer
      extends java.lang.Object
      implements java.lang.Comparable, java.lang.Cloneable

  A renderer transforms an XSL-FO into another output format like PDF, Postscript or XHTML. This is an abstraction of a concrete renderer like the FOPRenderer or XEP4Renderer that are using a third party tool. Actually implementations of this renderer are just adapters of existing renderers like FOP, XEP, XSLFormatter, Ibex...
  You can either create a renderer by using it's constructor or you can use the RendererFactory. We recommend to use the Factory pattern because it allows you changed the renderer implementation easily. The Factory is normally set-up with the jfo-config.xml (prefered method), but it's also possible to equip the factory with Java Code.
  Most renderers have following properties:
  - output-formats - Supported output formats
  - config-file - A file to initalize an external renderer
  - priority - Gives the factory a hint which renderer is to use if an output-format is supported by 2 or more renderers
  - printer-job-factory - provides print-jobs if this renderer supports output format PRINT
  See Also:
    `RendererFactory`, `OutputFormat`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_PRIORITY`
    `static java.lang.String` | `XML_ATTR_CLASS`
    `static java.lang.String` | `XML_ATTR_CONFIG_EDITOR`
    `static java.lang.String` | `XML_ATTR_CONFIG_FILE`
    `static java.lang.String` | `XML_ATTR_NAME`
    `static java.lang.String` | `XML_ATTR_PRIORTIY`
    `static java.lang.String` | `XML_ATTR_RESET_IMAGE_CACHE`
    `static java.lang.String` | `XML_ATTR_USE_JFO_LOGGING`
    `static java.lang.String` | `XML_NODE_RENDERER`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Renderer()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `afterRendering()` Invoked after rendering.
    `protected void` | `beforeRendering()` Invoked before rendering starts.
    `boolean` | `canRender(OutputFormat format)` Deprecated. Use supportsFormat(OutputFormat) instead.
    `int` | `compareTo(java.lang.Object o)`
    `void` | `configure(de.vc.config.Configuration config)` Configures this renderer.
    `Renderer` | `copy()` Clones this renderer.
    `protected java.awt.print.PrinterJob` | `createPrinterJob()` Creates a new print-job that subclasses could use to print a XSL-FO document.
    `protected void` | `doRender(Document document, java.io.OutputStream outStream, OutputFormat format)` Renders the given document using this renderer.
    `protected abstract void` | `doRender(java.io.InputStream foStream, java.io.OutputStream outStream, OutputFormat outputFormat)` Do render a FO-stream (Stream is in XML, not in XSL).
    `boolean` | `equals(java.lang.Object o)`
    `java.lang.String` | `getConfigFile()` Gets the location of the configuration file if there is any.
    `abstract java.lang.String` | `getDisplayName()` Gets the display name of renderer that can be shown in GUIs.
    `RTF2FOCompatibilityMode` | `getPreferredRTF2FOCompatibilityMode()` Gets the preferred compatibility mode for RTF to XSL-FO transformation or null if there is no preferation.
    `PrinterJobFactory` | `getPrinterJobFactory()` Gets the factory for creating print jobs.
    `int` | `getPriority()` Gets the priority of this renderer.
    `abstract OutputFormat[]` | `getSupportedOutputFormats()` Gets an array of all supported output formats.
    `boolean` | `isReady()` Checks if this renderer has all needed resources (external classes, configuration files etc) to renderer a document.
    `boolean` | `isUseJFOLogging()` Returns `true` if logs of renderers are written through JFO's logger.
    `protected void` | `logUnsupportedFormat(OutputFormat format)` This methode is called, if this logger can't render into given format.
    `void` | `reconfigure()`
    `void` | `render(Document document, java.io.File outputFile, OutputFormat format)` Renders the given document using this renderer.
    `void` | `render(Document document, OutputFormat format)` Renders the given document into a non file (AWT, PRINT, TREE_VIEWER) format.
    `void` | `render(Document document, java.io.OutputStream outStream, OutputFormat format)` Renders the given document using this renderer.
    `void` | `render(java.io.InputStream foStream, java.io.OutputStream outStream, OutputFormat format)` Render an XSL-FO stream.
    `protected java.net.URL` | `resolveConfig()`
    `void` | `setConfigFile(java.lang.String configFile)` Sets the location of configuration file if this renderer uses a separate, external file for intialization.
    `void` | `setPrinterJobFactory(PrinterJobFactory fac)` Sets the factory that is used to create PrinterJobs if printer-output is required.
    `void` | `setPriority(int priority)` Sets the priority of this renderer.
    `void` | `setUseJFOLogging(boolean jfoLogging)`
    `boolean` | `supportsFormat(OutputFormat format)` Checks whether this renderer can generated a given output format.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### XML_NODE_RENDERER

          public static final java.lang.String XML_NODE_RENDERER

      See Also:
        Constant Field Values

    - #### XML_ATTR_CONFIG_FILE

          public static final java.lang.String XML_ATTR_CONFIG_FILE

      See Also:
        Constant Field Values

    - #### XML_ATTR_CLASS

          public static final java.lang.String XML_ATTR_CLASS

      See Also:
        Constant Field Values

    - #### XML_ATTR_NAME

          public static final java.lang.String XML_ATTR_NAME

      See Also:
        Constant Field Values

    - #### XML_ATTR_PRIORTIY

          public static final java.lang.String XML_ATTR_PRIORTIY

      See Also:
        Constant Field Values

    - #### XML_ATTR_CONFIG_EDITOR

          public static final java.lang.String XML_ATTR_CONFIG_EDITOR

      See Also:
        Constant Field Values

    - #### XML_ATTR_USE_JFO_LOGGING

          public static final java.lang.String XML_ATTR_USE_JFO_LOGGING

      See Also:
        Constant Field Values

    - #### XML_ATTR_RESET_IMAGE_CACHE

          public static final java.lang.String XML_ATTR_RESET_IMAGE_CACHE

      See Also:
        Constant Field Values

    - #### DEFAULT_PRIORITY

          public static final int DEFAULT_PRIORITY

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Renderer

          protected Renderer()

  - ### Method Detail

    - #### getDisplayName

          public abstract java.lang.String getDisplayName()

      Gets the display name of renderer that can be shown in GUIs.
      Returns:
        Display name.

    - #### getSupportedOutputFormats

          public abstract OutputFormat[] getSupportedOutputFormats()

      Gets an array of all supported output formats.
      Returns:
        Array of output formats (see OUTPUT_*).

    - #### render

          public final void render(Document document,
                    OutputFormat format)
                            throws java.lang.Exception

      Renders the given document into a non file (AWT, PRINT, TREE_VIEWER) format.
      Parameters:
        `document` - Document.
        `format` - Non-file output format (see OutputFormat.*).
      Throws:
        `java.lang.Exception` - This renderer may throw an exception.

    - #### render

          public final void render(Document document,
                    java.io.OutputStream outStream,
                    OutputFormat format)
                            throws java.lang.Exception

      Renders the given document using this renderer. Don't forget to close the stream after rendering.
      Parameters:
        `document` - Document.
        `outStream` - Output stream.
        `format` - Output format (see OutputFormat.*).
      Throws:
        `java.lang.Exception` - This renderer may throw an exception.

    - #### render

          public final void render(java.io.InputStream foStream,
                    java.io.OutputStream outStream,
                    OutputFormat format)
                            throws java.lang.Exception

      Render an XSL-FO stream. Don't forget to close the stream after rendering.
      Parameters:
        `foStream` - FO-stream.
        `outStream` - Output stream, where rendered FO should be stored into.
        `format` - Outputformat (see OutputFormat.*).
      Throws:
        `java.lang.Exception` - Throw an exception in necessary.

    - #### render

          public final void render(Document document,
                    java.io.File outputFile,
                    OutputFormat format)
                            throws java.lang.Exception

      Renders the given document using this renderer.
      Parameters:
        `document` - Document.
        `outputFile` - Output file.
        `format` - Output format (see OutputFormat.*).
      Throws:
        `java.lang.Exception` - This renderer may throw an exception.

    - #### supportsFormat

          public boolean supportsFormat(OutputFormat format)

      Checks whether this renderer can generated a given output format.
      Parameters:
        `format` - OutputFormat.
      Returns:
        true, if this renderer supports the output format.

    - #### canRender

          public boolean canRender(OutputFormat format)

      Deprecated. Use supportsFormat(OutputFormat) instead.
      Checks whether this renderer can generated a given output format.
      Parameters:
        `format` - OutputFormat.
      Returns:
        true, if this renderer can render into format.
      See Also:
        `supportsFormat(OutputFormat)`

    - #### configure

          public void configure(de.vc.config.Configuration config)
                         throws de.vc.config.ConfigurationException

      Configures this renderer. This method does only configure this adapter to the external renderer but not the external renderer. The external renderer is configured when the renderer method is invoked (lazy initialization).
      Parameters:
        `config` - Configuration
      Throws:
        `de.vc.config.ConfigurationException`

    - #### isReady

          public boolean isReady()

      Checks if this renderer has all needed resources (external classes, configuration files etc) to renderer a document.
      Returns:
        boolean

    - #### getPriority

          public int getPriority()

      Gets the priority of this renderer. If a renderer is requested from the renderer-factory and more then one renderer supports the needed output-format, then the renderer with the highest priority is returned. If two renderers have an equal highest priority, it's unsure which renderer will be used.
      Returns:
        Priority.

    - #### setPriority

          public void setPriority(int priority)

      Sets the priority of this renderer.
      Parameters:
        `priority` - int

    - #### reconfigure

          public void reconfigure()
                           throws de.vc.config.ConfigurationException

      Throws:
        `de.vc.config.ConfigurationException`

    - #### getPreferredRTF2FOCompatibilityMode

          public RTF2FOCompatibilityMode getPreferredRTF2FOCompatibilityMode()

      Gets the preferred compatibility mode for RTF to XSL-FO transformation or null if there is no preferation.
      Returns:
        RTF2FOCompatibilityMode

    - #### setUseJFOLogging

          public void setUseJFOLogging(boolean jfoLogging)

      Parameters:
        `jfoLogging` - boolean

    - #### isUseJFOLogging

          public boolean isUseJFOLogging()

      Returns `true` if logs of renderers are written through JFO's logger.
      Returns:
        boolean
      See Also:
        `JFOConfig.getLogger()`

    - #### setPrinterJobFactory

          public void setPrinterJobFactory(PrinterJobFactory fac)

      Sets the factory that is used to create PrinterJobs if printer-output is required. If no factory is defined PrinterJob.getPrinterJob() is used to create a new PrinterJob.
      Parameters:
        `fac` - Factory for PrinterJobs.

    - #### getPrinterJobFactory

          public PrinterJobFactory getPrinterJobFactory()

      Gets the factory for creating print jobs. If renderer supports the output format PRINT, then it has to use a PrintJob in most cases. The factory creates such a job for this renderer when needed.
      Returns:
        Factory for PrinterJobs.

    - #### getConfigFile

          public java.lang.String getConfigFile()

      Gets the location of the configuration file if there is any. Some renderers use such a file to initialize fonts, logging options and other features.
      Returns:
        Relative or absolute path to configuration file.

    - #### setConfigFile

          public void setConfigFile(java.lang.String configFile)

      Sets the location of configuration file if this renderer uses a separate, external file for intialization.
      Parameters:
        `configFile` - String

    - #### copy

          public Renderer copy()

      Clones this renderer. This can be useful if you need to use a certain renderer as a prototype for a multithreaded system. You could create a prototype for example, when a servlet is initialized and use a copy if the prototype for a requested PDF. You should use the prototype itself in such situations since this renderer is not multithreaded and the renderer method is synchronized.
      Returns:
        Renderer

    - #### compareTo

          public int compareTo(java.lang.Object o)

      Specified by:
        `compareTo` in interface `java.lang.Comparable`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### doRender

          protected abstract void doRender(java.io.InputStream foStream,
                      java.io.OutputStream outStream,
                      OutputFormat outputFormat)
                                    throws java.lang.Exception

      Do render a FO-stream (Stream is in XML, not in XSL). You don't have to close the output-stream.
      Parameters:
        `foStream` - FO-stream.
        `outStream` - Output stream, where rendered FO should be stored into.
        `outputFormat` - Outputformat (see OUTPUT_*).
      Throws:
        `java.lang.Exception` - Throw an exception in necessary.

    - #### doRender

          protected void doRender(Document document,
                      java.io.OutputStream outStream,
                      OutputFormat format)
                           throws java.lang.Exception

      Renders the given document using this renderer. You don't have to close the output-stream.
      Parameters:
        `document` - Document.
        `outStream` - Output.
        `format` - Output format.
      Throws:
        `java.lang.Exception` - This renderer may throw an exception.

    - #### logUnsupportedFormat

          protected void logUnsupportedFormat(OutputFormat format)

      This methode is called, if this logger can't render into given format.
      Parameters:
        `format` - Format that is not supported.

    - #### beforeRendering

          protected void beforeRendering()
                                  throws java.lang.Exception

      Invoked before rendering starts.
      Throws:
        `java.lang.Exception`

    - #### afterRendering

          protected void afterRendering()
                                 throws java.lang.Exception

      Invoked after rendering.
      Throws:
        `java.lang.Exception`

    - #### createPrinterJob

          protected java.awt.print.PrinterJob createPrinterJob()

      Creates a new print-job that subclasses could use to print a XSL-FO document. Please be aware, that not every print implementation will use this print-job.
      Returns:

    - #### resolveConfig

          protected java.net.URL resolveConfig()

© 2003-2011 by Sascha Schmidt (vision-cloud.de). All Rights Reserved.