docs/xml-docs/fop/embedding.xml - xmlgraphics-fop - Git at Google

 <?xml version="1.0" standalone="no"?>


 <!-- Embedding FOP -->
 <document>
     <header>
         <title>Embedding FOP</title>
         <subtitle>Notes about embedding FOP in your Java application</subtitle>
         <authors>
         </authors>
     </header>

     <body>
 <s1 title="Embedding FOP ">
   <s2 title="Overview">
   <p>Instantiate org.apache.fop.apps.Driver. Once this class is
      instantiated, methods are called to set the
      Renderer to use
      and the OutputStream to use to output the results of the
      rendering (where applicable). In the case of the Renderer and
      ElementMapping(s), the Driver may be supplied either with the
      object itself, or the name of the class, in which case Driver will
      instantiate the class itself. The advantage of the latter is it
      enables runtime determination of Renderer and ElementMapping(s).
   </p>
   </s2>
   <s2 title="Examples">
   <p>The simplest way to use Driver is to instantiate it with the
      InputSource and OutputStream, then set the renderer desired and
      call the run method.
   </p>
   <p>Here is an example use of Driver which outputs PDF:
   </p>
     <source><![CDATA[
    Driver driver = new Driver(new InputSource (args[0]),
                               new FileOutputStream(args[1]));
    driver.setRenderer(RENDER_PDF);
    driver.run();]]></source>

   <p>You also need to set the Logger for logging messages, see
      <jump href="http://jakarta.apache.org/avalon/logkit/index.html">Jakarta Logkit</jump>
      for more information.
   </p>
     <source><![CDATA[
     Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
     PatternFormatter formatter = new PatternFormatter(
        "[%{priority}]: %{message}\n%{throwable}" );

     LogTarget target = null;
     target = new StreamTarget(System.out, formatter);

     hierarchy.setDefaultLogTarget(target);
     log = hierarchy.getLoggerFor("fop");
     log.setPriority(Priority.INFO);
     driver.setLogger(log);]]></source>

   <p>To setup the user config file you can do the following
   </p>
     <source><![CDATA[
    userConfigFile = new File(userConfig);
    options = new Options(userConfigFile);]]></source>

   <p>Once the Driver is set up, the render method
      is called. Depending on whether DOM or SAX is being used, the
      invocation of the method is either render(Document) or
      render(Parser, InputSource) respectively.
   </p>
   <p>
      <strong>Another possibility may be used to build the FO Tree. You can
      call getContentHandler() and fire the SAX events yourself.
      </strong>
   </p>
   <p>Once the FO Tree is built, the format() and render() methods may be
      called in that order.
   </p>
   <p>Here is an example use of Driver:</p>
   <source><![CDATA[
   Driver driver = new Driver();
   driver.setRenderer(Driver.RENDER_PDF);
   driver.setInputSource(new FileInputSource(args[0]));
   driver.setOutputStream(new FileOutputStream(args[1]));
   driver.run();]]></source>
   <p>You can also specify an xml and xsl file for the input.
   </p>
   <p>Here is an example use of Driver with the XSLTInputHandler:</p>
   <source><![CDATA[
   Driver driver = new Driver();
   driver.setRenderer(Driver.RENDER_PDF);
   InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
   XMLReader parser = inputHandler.getParser();
   driver.setOutputStream(new FileOutputStream(outFile));
   driver.render(parser, inputHandler.getInputSource());]]></source>
   <p>Have a look at the classes CommandLineStarter or FopServlet for complete examples.</p>
 <p>
 <note>If your FO files contain SVG then batik will be used. When batik is
 initialised it uses certain classes in <code>java.awt</code> that
 intialises the java AWT classes. This means that a daemon thread
 is created by the jvm and on unix it will need to connect to a
 DISPLAY.
 The thread means that the java application will not automatically quit
 when finished, you will need to call <code>System.exit</code>. These
 issues should be fixed in the upcoming JDK1.4</note>
 </p>
   </s2>
   <s2 title="Hints">
      <p>
 If FOP is going to be used multiple times within your application
 it may be useful to reuse certain objects to save time.
      </p>
      <p>
 The renderers and the driver can both be reused. A renderer is reusable
 once the previous render has been completed. The driver is reuseable
 after the rendering is complete and the reset method is called.
 You will need to setup the driver again with a new OutputStream,
 IntputStream and renderer.
      </p>
   </s2>
   <s2 title="Using Fop in a servlet">
      <p>
 In the directory xml-fop/docs/examples/embedding you can find a working
 example how to use Fop in a servlet. You can drop the fop.war into the
 webapps directory of Tomcat, then go to a URL like this:
      </p>
      <p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p>
      <p>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&amp;xsl=/home/path/to/xslfile.xsl</p>
      <p>You can also find the source code there in the file FopServlet.java</p>
      <p>
         To compile this code you will need servlet_2_2.jar (or compatible), fop.jar and the sax api in your classpath.
      </p>
      <note><p>
          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.
      </p></note>
   </s2>
 </s1>
     </body>
 </document>
	<?xml version="1.0" standalone="no"?>


	<!-- Embedding FOP -->
	<document>
	<header>
	<title>Embedding FOP</title>
	<subtitle>Notes about embedding FOP in your Java application</subtitle>
	<authors>
	</authors>
	</header>

	<body>
	<s1 title="Embedding FOP ">
	<s2 title="Overview">
	<p>Instantiate org.apache.fop.apps.Driver. Once this class is
	instantiated, methods are called to set the
	Renderer to use
	and the OutputStream to use to output the results of the
	rendering (where applicable). In the case of the Renderer and
	ElementMapping(s), the Driver may be supplied either with the
	object itself, or the name of the class, in which case Driver will
	instantiate the class itself. The advantage of the latter is it
	enables runtime determination of Renderer and ElementMapping(s).
	</p>
	</s2>
	<s2 title="Examples">
	<p>The simplest way to use Driver is to instantiate it with the
	InputSource and OutputStream, then set the renderer desired and
	call the run method.
	</p>
	<p>Here is an example use of Driver which outputs PDF:
	</p>
	<source><![CDATA[
	Driver driver = new Driver(new InputSource (args[0]),
	new FileOutputStream(args[1]));
	driver.setRenderer(RENDER_PDF);
	driver.run();]]></source>

	<p>You also need to set the Logger for logging messages, see
	<jump href="http://jakarta.apache.org/avalon/logkit/index.html">Jakarta Logkit</jump>
	for more information.
	</p>
	<source><![CDATA[
	Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
	PatternFormatter formatter = new PatternFormatter(
	"[%{priority}]: %{message}\n%{throwable}" );

	LogTarget target = null;
	target = new StreamTarget(System.out, formatter);

	hierarchy.setDefaultLogTarget(target);
	log = hierarchy.getLoggerFor("fop");
	log.setPriority(Priority.INFO);
	driver.setLogger(log);]]></source>

	<p>To setup the user config file you can do the following
	</p>
	<source><![CDATA[
	userConfigFile = new File(userConfig);
	options = new Options(userConfigFile);]]></source>

	<p>Once the Driver is set up, the render method
	is called. Depending on whether DOM or SAX is being used, the
	invocation of the method is either render(Document) or
	render(Parser, InputSource) respectively.
	</p>
	<p>
	<strong>Another possibility may be used to build the FO Tree. You can
	call getContentHandler() and fire the SAX events yourself.
	</strong>
	</p>
	<p>Once the FO Tree is built, the format() and render() methods may be
	called in that order.
	</p>
	<p>Here is an example use of Driver:</p>
	<source><![CDATA[
	Driver driver = new Driver();
	driver.setRenderer(Driver.RENDER_PDF);
	driver.setInputSource(new FileInputSource(args[0]));
	driver.setOutputStream(new FileOutputStream(args[1]));
	driver.run();]]></source>
	<p>You can also specify an xml and xsl file for the input.
	</p>
	<p>Here is an example use of Driver with the XSLTInputHandler:</p>
	<source><![CDATA[
	Driver driver = new Driver();
	driver.setRenderer(Driver.RENDER_PDF);
	InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile);
	XMLReader parser = inputHandler.getParser();
	driver.setOutputStream(new FileOutputStream(outFile));
	driver.render(parser, inputHandler.getInputSource());]]></source>
	<p>Have a look at the classes CommandLineStarter or FopServlet for complete examples.</p>
	<p>
	<note>If your FO files contain SVG then batik will be used. When batik is
	initialised it uses certain classes in <code>java.awt</code> that
	intialises the java AWT classes. This means that a daemon thread
	is created by the jvm and on unix it will need to connect to a
	DISPLAY.
	The thread means that the java application will not automatically quit
	when finished, you will need to call <code>System.exit</code>. These
	issues should be fixed in the upcoming JDK1.4</note>
	</p>
	</s2>
	<s2 title="Hints">
	<p>
	If FOP is going to be used multiple times within your application
	it may be useful to reuse certain objects to save time.
	</p>
	<p>
	The renderers and the driver can both be reused. A renderer is reusable
	once the previous render has been completed. The driver is reuseable
	after the rendering is complete and the reset method is called.
	You will need to setup the driver again with a new OutputStream,
	IntputStream and renderer.
	</p>
	</s2>
	<s2 title="Using Fop in a servlet">
	<p>
	In the directory xml-fop/docs/examples/embedding you can find a working
	example how to use Fop in a servlet. You can drop the fop.war into the
	webapps directory of Tomcat, then go to a URL like this:
	</p>
	<p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p>
	<p>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl</p>
	<p>You can also find the source code there in the file FopServlet.java</p>
	<p>
	To compile this code you will need servlet_2_2.jar (or compatible), fop.jar and the sax api in your classpath.
	</p>
	<note><p>
	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.
	</p></note>
	</s2>
	</s1>
	</body>
	</document>