Embedding FOP

Embedding FOP - Notes about embedding FOP in your Java application + How to Embed FOP in a Java application

- Embedding FOP

Overview

Instantiate org.apache.fop.apps.Driver. Once this class is @@ -36,9 +34,9 @@

You also need to set up logging. Global logging for all FOP processes is managed by MessageHandler. Per-instance logging is handled by Driver. You want to set both using an implementation @@ -199,23 +196,71 @@ pages of each document.

- Using FOP in a servlet -

-In the directory xml-fop/examples/servlet you can find a working example how -to use FOP in a servlet. After building the servlet you can drop the fop.war -into the webapps directory of Tomcat, then go to a URL like this: +

+ Using FOP in a Servlet +

+ Here is a minimal code snippet to demonstrate the basics: +

+ response.setContentType("application/pdf"); +Driver driver=new Driver( new InputSource("foo.fo"), + response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.run(); +

+There are numerous problems with the code snippet above. +Its purpose is only to demonstrate the basic concepts. +See xml-fop/examples/servlet for a working example of FOP used in a servlet. +After building the servlet, drop the fop.war into the webapps directory of Tomcat. +Then access a URL as follows:

http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo

http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl

The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.

- - Some browsers have problems handling the PDF result sent back to - the browser. IE is particularly bad and different versions behave - differently. Having a ".pdf" on the end of the URL may help. - + + Some versions of Internet Explorer will not automatically show the PDF. +This is well-known to be a limitation of Internet Explorer, and is not a problem with the servlet. +However, Internet Explorer can still be used to download the PDF so that it can be viewed later. Also, appending ".pdf" to the end of the URL may help. + +

+ Using FOP in a Servlet with an XSLT Transformation +

+ If both the source XML and XSL are read from files, use the TraxInputHandler: +

+ response.setContentType("application/pdf"); +XSLTInputHandler input + =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl")); +Driver driver=new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +driver.render(input.getParser(), input.getInputSource()); +

+ This code snippet has the same problems as the one from the section above. +

+ If your source XML is generated on the fly (for example from a database, a web service, or another servlet), create a transformer object explicitly, and use a SAX event stream to feed the transformation result into FOP: +

+ response.setContentType("application/pdf"); +Driver driver =new Driver(); +driver.setOutputStream(response.getOutputStream()); +driver.setRenderer(Driver.RENDER_PDF); +Transformer transformer=TransformerFactory.newInstance() + .newTransformer(new StreamSource("foo.xsl")); +transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); +

+ You don't have to call run() or render() on the driver object. +

+ The xmlsource is a placeholder for your actual XML source. +If you have to read the XML from a string, supply a new StreamSource(new StringReader(xmlstring)). +Constructing and reparsing an XML string is generally less desirable than using a SAXSource if you generate your XML. +You can alternatively supply a DOMSource as well. +You may also use dynamically generated XSL if you like. +

+ Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run. +

Examples

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index 3573c1b74..b208327b4 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -601,23 +601,8 @@ How do I use FOP in a servlet? -

Look at the servlet example.

- A rather minimal code snippet to demonstrate the basics: -

- response.setContentType("application/pdf"); -Driver driver=new Driver( new InputSource("foo.fo"), - response.getOutputStream()); -driver.setRenderer(Driver.RENDER_PDF); -driver.run(); -

- Caveat: Internet Explorer will not automatically show the PDF. Thats a - well known IEx problem, not with the servlet. You can download the PDF - with IEx and view it later. There are other problems with this code. -

- Please look into Embedding FOP - for all kinds of details. + See Using FOP in a Servlet.

@@ -626,54 +611,7 @@ driver.run(); transformation?

- Use the TraxInputHandler if both the source XML and XSL are read from - files. -

- A demonstration: -

- response.setContentType("application/pdf"); -XSLTInputHandler input - =new XSLTInputHandler(new File("foo.xml"), new File("foo.xsl")); -Driver driver=new Driver(); -driver.setOutputStream(response.getOutputStream()); -driver.setRenderer(Driver.RENDER_PDF); -driver.render(input.getParser(), input.getInputSource()); -

- This minimal code snippet has the same problems as the one from the - question above. Please inform yourself about the details. -

- If your source XML is generated on the fly, for example from a - database, a web service, or another servlet, you have to create a - transformer object explicitely and use a SAX event stream to feed the - transformation result into FOP. -

- A demonstration: -

- response.setContentType("application/pdf"); -Driver driver =new Driver(); -driver.setOutputStream(response.getOutputStream()); -driver.setRenderer(Driver.RENDER_PDF); -Transformer transformer=TransformerFactory.newInstance() - .newTransformer(new StreamSource("foo.xsl")); -transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); -

- You don't have to call run() or render() on the driver object. -

- The xmlsource is a placeholder for your actual XML - source. You can supply a new StreamSource( new - StringReader(xmlstring)) if you have to read the XML from a - string. Constructing an XML string and reparse it is not always a - good idea, consider to use a SAXSource if you generate your XML. You - can, of course, supply a DOMSource or whatever you like. You can also - use dynamically generated XSL if you want to. -

- Because you have an explicit transformer object, you can set - parameters for the transformation run too. + See Using FOP in a Servlet with XSLT Transformation.

@@ -690,9 +628,8 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));

- Declare the fonts in the userconfig.xml file as - usual. See loading the user configuration - file for further steps. + Declare the fonts in the userconfig.xml file as usual. +See loading the user configuration file for further details.