|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.report.ReportParser
public class ReportParser
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 |
---|
public static final String VERSION
public static final int WARNING_UNKNOWN_TAG
setFlag
to enable warnings for unknown XML tags.
On by default.
public static final int WARNING_UNKNOWN_ATTRIBUTE
setFlag
to enable warnings for unknown attributes on the XML tags.
On by default.
public static final int WARNING_MISPLACED_TEXT
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.
public static final int DEBUG_TO_STDOUT
setFlag
to enable debug output, which is sent
to System.out
. Not useful except to include in a bug report.
Method Detail |
---|
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.
SAXException
- if the parser can't be instantiatedpublic static ReportParser getInstance(String className) throws SAXException
className
- the class implementing the XMLReader interface,
eg. "org.apache.xerces.parsers.SAXParser" or
"org.apache.crimson.parser.XMLReaderImpl"
SAXException
- if the parser can't be instantiatedpublic void setFlag(int flag, boolean value)
WARNING_UNKNOWN_TAG
, WARNING_UNKNOWN_ATTRIBUTE
,
WARNING_MISPLACED_TEXT
and DEBUG_TO_STDOUT
flag
- the name of the flag to setvalue
- the value to set the flag topublic boolean getFlag(int flag)
setFlag(int, boolean)
flag
- the name of the flag
public void setErrorHandler(ErrorHandler errorhandler) throws SAXException
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.
errorhandler
- the ErrorHandler
to use to catch
errors
SAXException
public void setMetaHandler(MetaHandler metahandler)
MetaHandler
to handle any unknown Meta Tags
encountered during the parse. The default handler ignores
these tags.
metahandler
- the MetaHandler
to use to process
any unrecognised meta tagspublic PDF parse(String url) throws IOException, SAXException
url
- the absolute URL of the XML document to parse
PDF
created from the XML document
IOException
- if the document couldn't be read
SAXException
- if the document couldn't be parsedpublic PDF parse(File f) throws IOException, SAXException
file
- the file containing the XML document to parse
PDF
created from the XML document
IOException
- if the document couldn't be read
SAXException
- if the document couldn't be parsedpublic PDF parse(InputSource source) throws IOException, SAXException
InputSource
source
- the InputSource containing the XML document to parse
PDF
created from the XML document
IOException
- if the document couldn't be read
SAXException
- if the document couldn't be parsedpublic PDF parse(XMLReader reader, InputSource source) throws SAXException, IOException
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
reader
- the XMLReader to be used as the parent for the filtersource
- the InputSource containing the XML document to parse
PDF
created from the XML document
IOException
- if the document couldn't be read
SAXException
- if the document couldn't be parsedpublic 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(
key
- the license key
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |