Class 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
      • 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