Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.faceless.report
Class ReportParser

    java.lang.Object
      org.faceless.report.ReportParser

    public class ReportParser

extends Object

The top level class for the Big Faceless Report Generator.

This class manages the process of converting an XML document to a PDF, taking care of instantiating a SAX parser and parsing the XML via the `parse` method.

Creating a PDF at it's simplest involves just three lines - create the Parser, parse the XML and render the PDF. Here's a simple example to get you started:

       import org.xml.sax.*;
       import org.faceless.pdf2.*;
       import org.faceless.report.*;

       try {
           ReportParser p = ReportParser.getInstance();
           PDF pdf = p.parse("http://www.mycompany.com/myreport.xml");
           pdf.render(new FileOutputStream("myreport.pdf"));
       } catch (Exception e) {
           e.printStackTrace();
       }

> There are a large number of SAX parsers around, some of which are SAX 1.0 only. Although this package will run with SAX 1.0, we recommend upgrading to a SAX 2.0 parser like Xerces or Crimson.

A more sophisticated program would probably call the `setErrorHandler` method to determine how to handle any warnings or errors thrown during the parse. This method takes an `ErrorHandler` as a parameter - here's an example implementation which isn't too different to the default settings.

       public class MyErrorHandler implements org.xml.sax.ErrorHandler
       {
           public void warning(SAXParseException ex)
               throws SAXException
           {
               System.err.println("WARNING at line "+ex.getLineNumber()+": "+ex.getMessage());
               throw ex; // comment out this line to carry on after a warning
           }

           public void error(SAXParseException ex)
               throws SAXException
           {
               System.err.println("ERROR at line "+ex.getLineNumber()+": "+ex.getMessage());
               throw ex;    // die on errors
           }

           public void fatalError(SAXParseException ex)
               throws SAXException
           {
               System.err.println("FATAL ERROR at line "+ex.getLineNumber()+": "+ex.getMessage());
               throw ex;  // die on fatal errors
           }
       }

The `setMetaHandler` method may also be called to supply a callback handler for any unknown meta tags in the document.

Flags can be set to alter which warnings are thrown, and to extract debug output for bug reporting. This is done using the `setFlag` method.

Finally, since 1.0.11, it's possible to use the Report Parser as the last stage in a sequence of transformations, using the `parse(org.xml.sax.XMLReader, org.xml.sax.InputSource)` method

Field Summary
`static int` | `DEBUG_TO_STDOUT` Parameter to `setFlag` to enable debug output, which is sent to `System.out`.
`static String` | `VERSION` This variable contains the version number of the current build.
`static int` | `WARNING_MISPLACED_TEXT` Parameter to `setFlag` to enable warnings for text (CDATA) outside of it's rightful place.
`static int` | `WARNING_UNKNOWN_ATTRIBUTE` Parameter to `setFlag` to enable warnings for unknown attributes on the XML tags.
`static int` | `WARNING_UNKNOWN_TAG` Parameter to `setFlag` to enable warnings for unknown XML tags.

Method Summary
`boolean` | `getFlag(int flag)` Get the status of a flag, as set by `setFlag(int, boolean)`
`static ReportParser` | `getInstance()` Create a new parser.
`static ReportParser` | `getInstance(String className)` Create a new parser using the specified SAX parser implementation.
`PDF` | `parse(File f)` Parse the XML document from the specified file
`PDF` | `parse(InputSource source)` Parse the XML document from the specified `InputSource`
`PDF` | `parse(String url)` Parse the XML document at the supplied URL
`PDF` | `parse(XMLReader reader, InputSource source)` Parse the XML document from the specified `InputSource` using a filter with the specified `XMLReader` as it's parent.
`void` | `setErrorHandler(ErrorHandler errorhandler)` Set the `ErrorHandler` to handle any errors or warning thrown by the parsing process.
`void` | `setFlag(int flag, boolean value)` Set or clear a flag to change the parsing process.
`static void` | `setLicenseKey(String key)` Set the license key for the library.
`void` | `setMetaHandler(MetaHandler metahandler)` Set the `MetaHandler` to handle any unknown Meta Tags encountered during the parse.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### VERSION

    public static final String VERSION

  This variable contains the version number of the current build. A typical values would be "1.0.10". Please be sure to include this information with any bug reports

### WARNING_UNKNOWN_TAG

    public static final int WARNING_UNKNOWN_TAG

  Parameter to `setFlag` to enable warnings for unknown XML tags. On by default.

  See Also:
    Constant Field Values

### WARNING_UNKNOWN_ATTRIBUTE

    public static final int WARNING_UNKNOWN_ATTRIBUTE

  Parameter to `setFlag` to enable warnings for unknown attributes on the XML tags. On by default.

  Since:
    1.0.2
  See Also:
    Constant Field Values

### WARNING_MISPLACED_TEXT

    public static final int WARNING_MISPLACED_TEXT

  Parameter to `setFlag` to enable warnings for text (CDATA) outside of it's rightful place. Can help to pickup misformed XML documents, but will slightly slow parsing. On by default.

  See Also:
    Constant Field Values

### DEBUG_TO_STDOUT

    public static final int DEBUG_TO_STDOUT

  Parameter to `setFlag` to enable debug output, which is sent to `System.out`. Not useful except to include in a bug report.

  See Also:
    Constant Field Values

Method Detail

### getInstance

    public static ReportParser getInstance()
                                    throws SAXException

  Create a new parser. This constructor tries a number of methods to determine the appropriate implementation of `SAXParser`, checking for `org.xml.sax.driver`, JAXP1.1, JAXP1.0 and eventually looking for Xerces or Sun Crimson (arguably the two most common SAX implementations) directly.

  If a SAX parser can be found it will be used, but warnings may be printed to `System.err`. If the search found no SAX 2.0 parser at all, a `SAXException` is thrown.

  Throws:
    `SAXException` - if the parser can't be instantiated

### getInstance

    public static ReportParser getInstance(String className)
                                    throws SAXException

  Create a new parser using the specified SAX parser implementation.

  Parameters:
    `className` - the class implementing the `XMLReader` interface, eg. `"org.apache.xerces.parsers.SAXParser"` or `"org.apache.crimson.parser.XMLReaderImpl"`
  Throws:
    `SAXException` - if the parser can't be instantiated

### setFlag

    public void setFlag(int flag,
                        boolean value)

  Set or clear a flag to change the parsing process. Current valid flags are `WARNING_UNKNOWN_TAG`, `WARNING_UNKNOWN_ATTRIBUTE`, `WARNING_MISPLACED_TEXT` and `DEBUG_TO_STDOUT`

  Parameters:
    `flag` - the name of the flag to set
    `value` - the value to set the flag to

### getFlag

    public boolean getFlag(int flag)

  Get the status of a flag, as set by `setFlag(int, boolean)`

  Parameters:
    `flag` - the name of the flag
  Returns:
    the value of the flag

### setErrorHandler

    public void setErrorHandler(ErrorHandler errorhandler)
                         throws SAXException

  Set the `ErrorHandler` to handle any errors or warning thrown by the parsing process. The default handler prints any exceptions and warnings to `System.err` and throws a `SAXException`, ending the parsing process.

  Parameters:
    `errorhandler` - the `ErrorHandler` to use to catch errors
  Throws:
    `SAXException`

### setMetaHandler

    public void setMetaHandler(MetaHandler metahandler)

  Set the `MetaHandler` to handle any unknown Meta Tags encountered during the parse. The default handler ignores these tags.

  Parameters:
    `metahandler` - the `MetaHandler` to use to process any unrecognised meta tags

### parse

    public PDF parse(String url)
              throws IOException,
                     SAXException

  Parse the XML document at the supplied URL

  Parameters:
    `url` - the absolute URL of the XML document to parse
  Returns:
    the `PDF` created from the XML document
  Throws:
    `IOException` - if the document couldn't be read
    `SAXException` - if the document couldn't be parsed

### parse

    public PDF parse(File f)
              throws IOException,
                     SAXException

  Parse the XML document from the specified file

  Parameters:
    `file` - the file containing the XML document to parse
  Returns:
    the `PDF` created from the XML document
  Throws:
    `IOException` - if the document couldn't be read
    `SAXException` - if the document couldn't be parsed

### parse

    public PDF parse(InputSource source)
              throws IOException,
                     SAXException

  Parse the XML document from the specified `InputSource`

  Parameters:
    `source` - the InputSource containing the XML document to parse
  Returns:
    the `PDF` created from the XML document
  Throws:
    `IOException` - if the document couldn't be read
    `SAXException` - if the document couldn't be parsed

### parse

    public PDF parse(XMLReader reader,
                     InputSource source)
              throws SAXException,
                     IOException

  Parse the XML document from the specified `InputSource` using a filter with the specified `XMLReader` as it's parent. This method allows the Report Generator to be used as the last step in a sequence of one or more transformations - either using XSL or a normal XMLFilter. Here's a simplified example to show how this could be done.

          // Create a filter from an XSL stylesheet
          SAXTransformerFactory factory;
          factory = (SAXTransformerFactory)TransformerFactory.getInstance();
          XMLFilter filter = factory.newXMLFilter(new StreamSource("sample.xsl"));

          // Create an XML reader for the filter to read from
          XMLReader reader = XMLReaderFactory.createXMLReader();
          filter.setParent(reader);

          // Do the transformation and save the resulting PDF
          ReportParser parser = ReportParser.getInstance();
          PDF pdf = parser.parse(filter, new InputSource("sample.xml"));
          pdf.render(new FileOutputStream("sample.pdf"));

  Note this method requires a SAX 2.0 or later implementation

  Parameters:
    `reader` - the `XMLReader` to be used as the parent for the filter
    `source` - the `InputSource` containing the XML document to parse
  Returns:
    the `PDF` created from the XML document
  Throws:
    `IOException` - if the document couldn't be read
    `SAXException` - if the document couldn't be parsed
  Since:
    1.0.11

### setLicenseKey

    public static void setLicenseKey(String key)

  Set the license key for the library. When the library is purchased, the Big Faceless Organization supplies a key which removes the "DEMO" stamp on each of the reports.

  Please note this method is static - it should be called BEFORE the first Report is created, like so:

        ReportParser.setLicenseKey(.....);
        ReportParser parser = ReportParser.getInstance(

  Parameters:
    `key` - the license key

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2012 Big Faceless Organization