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

```
public class ReportParser
extends java.lang.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

Fields
Modifier and Type	Field	Description
`static int`	`DEBUG_TO_STDOUT`	Parameter to `setFlag` to enable debug output, which is sent to `System.out`.
`static int`	`ENABLE_EXTERNAL_ENTITIES`	Parameter to `setFlag` to re-enable external entity resolution, which is disabled by default for security reasons as of 1.2.7.
`static java.lang.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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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(java.lang.String className)`	Create a new parser using the specified SAX parser implementation.
`static URLConnectionFactory`	`getURLConnectionFactory(java.lang.String scheme)`	Get a URLConnectionFactory previous registered with the specified scheme, or null if none exists.
`PDF`	`parse(java.io.File f)`	Parse the XML document from the specified file
`PDF`	`parse(java.lang.String url)`	Parse the XML document at the supplied URL
`PDF`	`parse(org.xml.sax.InputSource source)`	Parse the XML document from the specified `InputSource`
`PDF`	`parse(org.xml.sax.XMLReader reader, org.xml.sax.InputSource source)`	Parse the XML document from the specified `InputSource` using a filter with the specified `XMLReader` as it's parent.
`static void`	`registerURLConnectionFactory(java.lang.String scheme, URLConnectionFactory factory)`	Register a URLConnectionFactory for the specified Scheme
`void`	`setErrorHandler(org.xml.sax.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(java.lang.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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - VERSION
```
public static final java.lang.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
  - ENABLE_EXTERNAL_ENTITIES
```
public static final int ENABLE_EXTERNAL_ENTITIES
```
    Parameter to setFlag to re-enable external entity resolution, which is disabled by default for security reasons as of 1.2.7.
    
    Since:
    
    1.2.7
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getInstance
```
public static ReportParser getInstance()
                                throws org.xml.sax.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:
    
    org.xml.sax.SAXException - if the parser can't be instantiated
  - getInstance
```
public static ReportParser getInstance(java.lang.String className)
                                throws org.xml.sax.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:
    
    org.xml.sax.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(org.xml.sax.ErrorHandler errorhandler)
                     throws org.xml.sax.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:
    
    org.xml.sax.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(java.lang.String url)
          throws java.io.IOException,
                 org.xml.sax.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:
    
    java.io.IOException - if the document couldn't be read
    
    org.xml.sax.SAXException - if the document couldn't be parsed
  - parse
```
public PDF parse(java.io.File f)
          throws java.io.IOException,
                 org.xml.sax.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:
    
    java.io.IOException - if the document couldn't be read
    
    org.xml.sax.SAXException - if the document couldn't be parsed
  - parse
```
public PDF parse(org.xml.sax.InputSource source)
          throws java.io.IOException,
                 org.xml.sax.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:
    
    java.io.IOException - if the document couldn't be read
    
    org.xml.sax.SAXException - if the document couldn't be parsed
  - parse
```
public PDF parse(org.xml.sax.XMLReader reader,
                 org.xml.sax.InputSource source)
          throws org.xml.sax.SAXException,
                 java.io.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:
    
    java.io.IOException - if the document couldn't be read
    
    org.xml.sax.SAXException - if the document couldn't be parsed
    
    Since:
    
    1.0.11
  - setLicenseKey
```
public static void setLicenseKey(java.lang.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
  - registerURLConnectionFactory
```
public static void registerURLConnectionFactory(java.lang.String scheme,
                                                URLConnectionFactory factory)
```
    Register a URLConnectionFactory for the specified Scheme
    
    Parameters:
    
    scheme - the scheme, eg "http" or "custom"
    
    factory - the URLConnectionFactory that should be used to open URLConnections for this scheme, or null to use the default
    
    Since:
    
    1.1.67
  - getURLConnectionFactory
```
public static URLConnectionFactory getURLConnectionFactory(java.lang.String scheme)
```
    Get a URLConnectionFactory previous registered with the specified scheme, or null if none exists.
    
    Parameters:
    
    scheme - the scheme
    
    Since:
    
    1.1.67

Class ReportParser

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VERSION

WARNING_UNKNOWN_TAG

WARNING_UNKNOWN_ATTRIBUTE

WARNING_MISPLACED_TEXT

DEBUG_TO_STDOUT

ENABLE_EXTERNAL_ENTITIES

Method Detail

getInstance

getInstance

setFlag

getFlag

setErrorHandler

setMetaHandler

parse

parse

parse

parse

setLicenseKey

registerURLConnectionFactory

getURLConnectionFactory