net.sf.jasperreports.engine

## Class JasperCompileManager

- java.lang.Object
- - net.sf.jasperreports.engine.JasperCompileManager

-     public final class JasperCompileManager
      extends java.lang.Object

  Facade class for compiling report designs into the ready-to-fill form and for getting the XML representation of report design objects for storage or network transfer.

  This class exposes all the library's report compilation functionality. It has various methods that allow the users to compile JRXML report templates found in files on disk or that come from input streams. It also lets people compile in-memory report templates by directly passing a `JasperDesign` object and receiving the corresponding `JasperReport` object.

  Other utility methods include report template verification and JRXML report template generation for in-memory constructed `JasperDesign` class instances. These instances are especially useful in GUI tools that simplify report design work.

  The facade class relies on the report template language to determine an appropriate report compiler. The report compilation facade first reads a configuration property called `net.sf.jasperreports.compiler.<language>` to determine whether a compiler implementation has been configured for the specific report language. If such a property is found, its value is used as compiler implementation class name and the facade instantiates a compiler object and delegates the report compilation to it. By default, JasperReports includes configuration properties that map the Groovy, JavaScript and BeanShell report compilers to the `groovy`, `javascript` and `bsh` report languages, respectively.

  If the report uses Java as language and no specific compiler has been set for this language, the report compilation facade employs a built-in fall back mechanism that picks the best Java-based report compiler available in the environment in which the report compilation process takes place.

  The facade first reads the configuration property called `net.sf.jasperreports.compiler.class` to allow users to override its built-in compiler-detection logic by providing the name of the report compiler implementation to use directly.

  If the property is not provided, the facade first tries to see if the JDT compiler from the Eclipse Foundation is available in the application's classpath. If it is, the `JRJdtCompiler` implementation is used.

  If the JDT compiler is not available, the compilation facade then tries to locate the JDK 1.3-compatible Java compiler from Sun Microsystems. This is normally found in the `tools.jar` file that comes with the JDK installation.

  If all these fail, the last thing the fall back mechanism does is to try to launch the `javac.exe` program from the command line in order to compile the temporarily generated Java source file on the fly.

  ### Configuration Properties to Customize Report Compilation

  JasperReports offers various mechanisms for letting users customize its behavior. One of these mechanisms is a complete set of configuration properties. The following list contains all the configuration properties that customize report compilation.
  `net.sf.jasperreports.compiler.<language>`
    Such properties are used for indicating the name of the class that implements the `JRCompiler` interface to be instantiated by the engine for a specific report language when the default compilation is used through this facade class. The value for such a configuration property can be the name of one of the built-in implementations of this interface shipped with the library as listed previously, or the name of a custom-made implementing class.
    One can configure report compilers for custom report languages and override the default compiler mappings by setting JasperReports properties of the form `net.sf.jasperreports.compiler.<language>` to the desired compiler implementation class names. In particular, the mechanism that automatically chooses a Java report compiler can be superseded by explicitly setting the `net.sf.jasperreports.compiler.java` property to the name of one of the built-in Java compiler classes or of a custom compiler implementation class.
    Note that the classes implementing the `JRCompiler` interface can also be used directly in the programs without having to call them through this facade class.
  `net.sf.jasperreports.compiler.xml.validation`
    The XML validation, which is on by default, can be turned off by setting this configuration property to false. When turned off, the XML parser no longer validates the supplied JRXML against its associated XSD. This might prove useful in some environments, although it is not recommended.
  `net.sf.jasperreports.compiler.classpath`
    This property supplies the classpath. JDK-based compilers require that the classpath be supplied as a parameter. They cannot use the current JVM classpath. The supplied classpath resolves class references inside the Java code they are compiling.
    This property is not used by the JDT-based report compiler, which simply uses the parent application's classpath during Java source file compilation.
  `net.sf.jasperreports.compiler.temp.dir`
    The temporary location for the files generated on the fly is by default the current working directory. It can be changed by supplying a value to this configuration property. This is used by the JDT-based compiler only when it is requested that a copy of the on-the-fly generated Java class be kept for debugging purposes as specified by the next configuration property, because normally this report compiler does not work with files on disk.
  `net.sf.jasperreports.compiler.keep.java.file`
    Sometimes, for debugging purposes, it is useful to have the generated `*.java` file or generated script in order to fix compilation problems related to report expressions. By default, the engine deletes this file after report compilation, along with its corresponding `*.class` file. To keep it, however, set this configuration property to true.

  ### JDT Compiler-Specific Configuration Properties

  The JRJdtCompiler report compiler can use special JasperReports configuration properties to configure the underlying JDT Java compiler. This report compiler collects all the JasperReports configuration properties (the ones usually set in the jasperreports.properties file) that start with the `org.eclipse.jdt.core.` prefix and passes them to the JDT Java compiler when compiling the generated Java class to evaluate report expressions.

  One of the uses of this mechanism is to instruct the JDT compiler to observe Java 1.5 code compatibility. To do so, the following properties should be set:

  - `org.eclipse.jdt.core.compiler.source=1.5`
  - `org.eclipse.jdt.core.compiler.compliance=1.5`
  - `org.eclipse.jdt.core.compiler.codegen.TargetPlatform=1.5`
  Version:
    $Id: JasperCompileManager.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)
  See Also:
    `JasperReport`, `JasperDesign`, `JRCompiler`, `JRJdtCompiler`, `JRVerifier`, `JRXmlLoader`, `JRXmlWriter`, `JRLoader`, `JRSaver`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JasperReport` | `compile(java.io.InputStream inputStream)` Compiles the serialized report design object read from the supplied input stream and returns the generated compiled report design object.
    `JasperReport` | `compile(JasperDesign jasperDesign)` Compiles the report design object received as parameter and returns the generated compiled report design object.
    `JasperReport` | `compile(java.lang.String sourceFileName)` Compiles the XML report design file received as parameter, and returns the compiled report design object.
    `static JasperReport` | `compileReport(java.io.InputStream inputStream)`
    `static JasperReport` | `compileReport(JasperDesign jasperDesign)`
    `static JasperReport` | `compileReport(java.lang.String sourceFileName)`
    `static void` | `compileReportToFile(JasperDesign jasperDesign, java.lang.String destFileName)`
    `static java.lang.String` | `compileReportToFile(java.lang.String sourceFileName)`
    `static void` | `compileReportToFile(java.lang.String sourceFileName, java.lang.String destFileName)`
    `static void` | `compileReportToStream(java.io.InputStream inputStream, java.io.OutputStream outputStream)`
    `static void` | `compileReportToStream(JasperDesign jasperDesign, java.io.OutputStream outputStream)`
    `void` | `compileToFile(JasperDesign jasperDesign, java.lang.String destFileName)` Compiles the report design object received as the first parameter, placing the result in the file specified by the second parameter.
    `java.lang.String` | `compileToFile(java.lang.String sourceFileName)` Compiles the XML report design file specified by the parameter.
    `void` | `compileToFile(java.lang.String sourceFileName, java.lang.String destFileName)` Compiles the XML report design file received as the first parameter, placing the result in the file specified by the second parameter.
    `void` | `compileToStream(java.io.InputStream inputStream, java.io.OutputStream outputStream)` Compiles the XML representation of the report design read from the supplied input stream and writes the generated compiled report design object to the output stream specified by the second parameter.
    `void` | `compileToStream(JasperDesign jasperDesign, java.io.OutputStream outputStream)` Compiles the report design object represented by the first parameter and writes the generated compiled report design object to the output stream specified by the second parameter.
    `JREvaluator` | `getEvaluator(JasperReport jasperReport)`
    `JREvaluator` | `getEvaluator(JasperReport jasperReport, JRCrosstab crosstab)`
    `JREvaluator` | `getEvaluator(JasperReport jasperReport, JRDataset dataset)`
    `static JasperCompileManager` | `getInstance(JasperReportsContext jasperReportsContext)`
    `protected void` | `initialize(JREvaluator evaluator)`
    `static JREvaluator` | `loadEvaluator(JasperReport jasperReport)`
    `static JREvaluator` | `loadEvaluator(JasperReport jasperReport, JRCrosstab crosstab)`
    `static JREvaluator` | `loadEvaluator(JasperReport jasperReport, JRDataset dataset)`
    `java.util.Collection<JRValidationFault>` | `verify(JasperDesign jasperDesign)` Verifies the validity and consistency of the report design object.
    `static java.util.Collection<JRValidationFault>` | `verifyDesign(JasperDesign jasperDesign)`
    `static java.lang.String` | `writeReportToXml(JRReport report)`
    `static void` | `writeReportToXmlFile(JRReport report, java.lang.String destFileName)`
    `static java.lang.String` | `writeReportToXmlFile(java.lang.String sourceFileName)`
    `static void` | `writeReportToXmlFile(java.lang.String sourceFileName, java.lang.String destFileName)`
    `static void` | `writeReportToXmlStream(java.io.InputStream inputStream, java.io.OutputStream outputStream)`
    `static void` | `writeReportToXmlStream(JRReport report, java.io.OutputStream outputStream)`
    `java.lang.String` | `writeToXml(JRReport report)` Generates the XML representation of the report design object supplied as parameter using the "UTF-8" enconding.
    `void` | `writeToXmlFile(JRReport report, java.lang.String destFileName)` Generates the XML representation of the report design supplied as the first parameter and place it in the file specified by the second parameter.
    `java.lang.String` | `writeToXmlFile(java.lang.String sourceFileName)` Generates the XML representation of the report design loaded from the specified filename.
    `void` | `writeToXmlFile(java.lang.String sourceFileName, java.lang.String destFileName)` Generates the XML representation of the report design loaded from the first file parameter and place it in the file specified by the second parameter.
    `void` | `writeToXmlStream(java.io.InputStream inputStream, java.io.OutputStream outputStream)` Generates the XML representation of the serialized report design object read from the supplied input stream abd writes it to the specified output stream, using the "UTF-8" encoding.
    `void` | `writeToXmlStream(JRReport report, java.io.OutputStream outputStream)` Generates the XML representation of the report design object supplied as parameter and writes it to the specified output stream, using the "UTF-8" encoding.

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

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

- - ### Method Detail

    - #### getInstance

          public static JasperCompileManager getInstance(JasperReportsContext jasperReportsContext)

    - #### compileToFile

          public java.lang.String compileToFile(java.lang.String sourceFileName)
                                         throws JRException

      Compiles the XML report design file specified by the parameter. The result of this operation is another file that will contain the serialized `JasperReport` object representing the compiled report design, having the same name as the report design as declared in the XML plus the `*.jasper` extension, located in the same directory as the XML source file.
      Parameters:
        `sourceFileName` - XML source file name
      Returns:
        resulting file name containing a serialized `JasperReport` object
      Throws:
        `JRException`

    - #### compileToFile

          public void compileToFile(java.lang.String sourceFileName,
                           java.lang.String destFileName)
                             throws JRException

      Compiles the XML report design file received as the first parameter, placing the result in the file specified by the second parameter. The resulting file will contain a serialized instance of a `JasperReport` object representing the compiled report design.
      Parameters:
        `sourceFileName` - XML source file name
        `destFileName` - file name to place the result into
      Throws:
        `JRException`

    - #### compileToFile

          public void compileToFile(JasperDesign jasperDesign,
                           java.lang.String destFileName)
                             throws JRException

      Compiles the report design object received as the first parameter, placing the result in the file specified by the second parameter. The resulting file will contain a serialized instance of a `JasperReport` object representing the compiled report design.
      Parameters:
        `jasperDesign` - source report design object
        `destFileName` - file name to place the compiled report design into
      Throws:
        `JRException`

    - #### compile

          public JasperReport compile(java.lang.String sourceFileName)
                               throws JRException

      Compiles the XML report design file received as parameter, and returns the compiled report design object.
      Parameters:
        `sourceFileName` - XML source file name
      Returns:
        compiled report design object
      Throws:
        `JRException`

    - #### compileToStream

          public void compileToStream(java.io.InputStream inputStream,
                             java.io.OutputStream outputStream)
                               throws JRException

      Compiles the XML representation of the report design read from the supplied input stream and writes the generated compiled report design object to the output stream specified by the second parameter.
      Parameters:
        `inputStream` - XML source input stream
        `outputStream` - output stream to write the compiled report design to
      Throws:
        `JRException`

    - #### compileToStream

          public void compileToStream(JasperDesign jasperDesign,
                             java.io.OutputStream outputStream)
                               throws JRException

      Compiles the report design object represented by the first parameter and writes the generated compiled report design object to the output stream specified by the second parameter.
      Parameters:
        `jasperDesign` - source report design object
        `outputStream` - output stream to write the compiled report design to
      Throws:
        `JRException`

    - #### compile

          public JasperReport compile(java.io.InputStream inputStream)
                               throws JRException

      Compiles the serialized report design object read from the supplied input stream and returns the generated compiled report design object.
      Parameters:
        `inputStream` - XML source input stream
      Returns:
        compiled report design object
      Throws:
        `JRException`

    - #### compile

          public JasperReport compile(JasperDesign jasperDesign)
                               throws JRException

      Compiles the report design object received as parameter and returns the generated compiled report design object.
      Parameters:
        `jasperDesign` - source report design object
      Returns:
        compiled report design object
      Throws:
        `JRException`
      See Also:
        `JRCompiler`

    - #### verify

          public java.util.Collection<JRValidationFault> verify(JasperDesign jasperDesign)

      Verifies the validity and consistency of the report design object. Returns a collection of `errors`, if problems are found in the report design.
      Parameters:
        `jasperDesign` - report design object to verify
      Returns:
        collection of `JRValidationFault` if problems are found
      See Also:
        `JRVerifier`

    - #### getEvaluator

          public JREvaluator getEvaluator(JasperReport jasperReport,
                                 JRDataset dataset)
                                   throws JRException

      Throws:
        `JRException`

    - #### getEvaluator

          public JREvaluator getEvaluator(JasperReport jasperReport,
                                 JRCrosstab crosstab)
                                   throws JRException

      Throws:
        `JRException`

    - #### getEvaluator

          public JREvaluator getEvaluator(JasperReport jasperReport)
                                   throws JRException

      Throws:
        `JRException`

    - #### initialize

          protected void initialize(JREvaluator evaluator)

    - #### writeToXmlFile

          public java.lang.String writeToXmlFile(java.lang.String sourceFileName)
                                          throws JRException

      Generates the XML representation of the report design loaded from the specified filename. The result of this operation is an "UTF-8" encoded XML file having the same name as the report design, plus the `*.jasper.jrxml` extension, located in the same directory as the source file.
      Parameters:
        `sourceFileName` - source file name containing the report design object
      Returns:
        XML representation of the report design
      Throws:
        `JRException`

    - #### writeToXmlFile

          public void writeToXmlFile(java.lang.String sourceFileName,
                            java.lang.String destFileName)
                              throws JRException

      Generates the XML representation of the report design loaded from the first file parameter and place it in the file specified by the second parameter. The result is "UTF-8" encoded.
      Parameters:
        `sourceFileName` - source file name containing the report design object
        `destFileName` - output file name to write the XML report design representation to
      Throws:
        `JRException`

    - #### writeToXmlFile

          public void writeToXmlFile(JRReport report,
                            java.lang.String destFileName)
                              throws JRException

      Generates the XML representation of the report design supplied as the first parameter and place it in the file specified by the second parameter. The result is "UTF-8" encoded.
      Parameters:
        `report` - source report design object
        `destFileName` - output file name to write the XML report design representation to
      Throws:
        `JRException`
      See Also:
        `JRXmlWriter`

    - #### writeToXmlStream

          public void writeToXmlStream(java.io.InputStream inputStream,
                              java.io.OutputStream outputStream)
                                throws JRException

      Generates the XML representation of the serialized report design object read from the supplied input stream abd writes it to the specified output stream, using the "UTF-8" encoding.
      Parameters:
        `inputStream` - source input stream to read the report design object from
        `outputStream` - output stream to write the XML report design representation to
      Throws:
        `JRException`

    - #### writeToXmlStream

          public void writeToXmlStream(JRReport report,
                              java.io.OutputStream outputStream)
                                throws JRException

      Generates the XML representation of the report design object supplied as parameter and writes it to the specified output stream, using the "UTF-8" encoding.
      Parameters:
        `report` - source report design object
        `outputStream` - output stream to write the XML report design representation to
      Throws:
        `JRException`
      See Also:
        `JRXmlWriter`

    - #### writeToXml

          public java.lang.String writeToXml(JRReport report)

      Generates the XML representation of the report design object supplied as parameter using the "UTF-8" enconding.
      Parameters:
        `report` - source report design object
      Returns:
        XML representation of the report design
      See Also:
        `JRXmlWriter`

    - #### compileReportToFile

          public static java.lang.String compileReportToFile(java.lang.String sourceFileName)
                                                      throws JRException

      Throws:
        `JRException`
      See Also:
        `compileToFile(String)`

    - #### compileReportToFile

          public static void compileReportToFile(java.lang.String sourceFileName,
                                 java.lang.String destFileName)
                                          throws JRException

      Throws:
        `JRException`
      See Also:
        `compileToFile(String, String)`

    - #### compileReportToFile

          public static void compileReportToFile(JasperDesign jasperDesign,
                                 java.lang.String destFileName)
                                          throws JRException

      Throws:
        `JRException`
      See Also:
        `compileToFile(JasperDesign, String)`

    - #### compileReport

          public static JasperReport compileReport(java.lang.String sourceFileName)
                                            throws JRException

      Throws:
        `JRException`
      See Also:
        `compile(String)`

    - #### compileReportToStream

          public static void compileReportToStream(java.io.InputStream inputStream,
                                   java.io.OutputStream outputStream)
                                            throws JRException

      Throws:
        `JRException`
      See Also:
        `compileToStream(InputStream, OutputStream)`

    - #### compileReportToStream

          public static void compileReportToStream(JasperDesign jasperDesign,
                                   java.io.OutputStream outputStream)
                                            throws JRException

      Throws:
        `JRException`
      See Also:
        `compileToStream(JasperDesign, OutputStream)`

    - #### compileReport

          public static JasperReport compileReport(java.io.InputStream inputStream)
                                            throws JRException

      Throws:
        `JRException`
      See Also:
        `compile(InputStream)`

    - #### compileReport

          public static JasperReport compileReport(JasperDesign jasperDesign)
                                            throws JRException

      Throws:
        `JRException`
      See Also:
        `compile(JasperDesign)`

    - #### verifyDesign

          public static java.util.Collection<JRValidationFault> verifyDesign(JasperDesign jasperDesign)

      See Also:
        `verify(JasperDesign)`

    - #### loadEvaluator

          public static JREvaluator loadEvaluator(JasperReport jasperReport,
                                  JRDataset dataset)
                                           throws JRException

      Throws:
        `JRException`
      See Also:
        `getEvaluator(JasperReport, JRDataset)`

    - #### loadEvaluator

          public static JREvaluator loadEvaluator(JasperReport jasperReport,
                                  JRCrosstab crosstab)
                                           throws JRException

      Throws:
        `JRException`
      See Also:
        `getEvaluator(JasperReport, JRCrosstab)`

    - #### loadEvaluator

          public static JREvaluator loadEvaluator(JasperReport jasperReport)
                                           throws JRException

      Throws:
        `JRException`
      See Also:
        `getEvaluator(JasperReport)`

    - #### writeReportToXmlFile

          public static java.lang.String writeReportToXmlFile(java.lang.String sourceFileName)
                                                       throws JRException

      Throws:
        `JRException`
      See Also:
        `writeToXmlFile(String)`

    - #### writeReportToXmlFile

          public static void writeReportToXmlFile(java.lang.String sourceFileName,
                                  java.lang.String destFileName)
                                           throws JRException

      Throws:
        `JRException`
      See Also:
        `writeToXmlFile(String, String)`

    - #### writeReportToXmlFile

          public static void writeReportToXmlFile(JRReport report,
                                  java.lang.String destFileName)
                                           throws JRException

      Throws:
        `JRException`
      See Also:
        `writeToXmlFile(JRReport, String)`

    - #### writeReportToXmlStream

          public static void writeReportToXmlStream(java.io.InputStream inputStream,
                                    java.io.OutputStream outputStream)
                                             throws JRException

      Throws:
        `JRException`
      See Also:
        `writeToXmlStream(InputStream, OutputStream)`

    - #### writeReportToXmlStream

          public static void writeReportToXmlStream(JRReport report,
                                    java.io.OutputStream outputStream)
                                             throws JRException

      Throws:
        `JRException`
      See Also:
        `writeToXmlStream(JRReport, OutputStream)`

    - #### writeReportToXml

          public static java.lang.String writeReportToXml(JRReport report)

      See Also:
        `writeToXml(JRReport)`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com