org.faceless.report
Class ReportParser

java.lang.Object
  extended by 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


Copyright © 2001-2012 Big Faceless Organization