Because you have an explicit transformer object, you can also use it to explicitly set parameters for the transformation run.
</p>
</section>
+ <section id="config-external">
+ <title>Using a Configuration File</title>
+ <p>
+ To access an external configuration:
+ </p>
+ <source>org.apache.fop.apps.Options options = new Options(new File("userconfig.xml"));</source>
+ <p>
+ No further reference to the <code>options</code> variable is necessary.
+ </p>
+ <p>
+ See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
+ </p>
+ </section>
+ <section id="config-internal">
+ <title>Setting the Configuration Programmatically</title>
+ <p>
+ If you wish to set configuration options from within your embedded application, use the <code>Configuration.put</code> method. Here is an example that sets the "baseDir" configuration in a Unix environment:
+ </p>
+ <source>org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir");</source>
+ <p>
+ Here is another that sets baseDir in a Windows environment:
+ </p>
+ <source>org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir");</source>
+ <p>
+ See <link href="#multithreading">Multithreading FOP</link> for issues related to changing configuration in a multithreaded environment.
+ </p>
+ </section>
+ <section id="multithreading">
+ <title>Multithreading FOP</title>
+ <p>
+ FOP is not currently completely thread safe.
+Although the relevant methods of the Driver object are synchronized, FOP uses static
+variables for configuration data and loading images.
+Here are some tips to mitigate these problems:
+ </p>
+ <ul>
+ <li>To avoid having your threads blocked, create a Driver object for each thread.</li>
+ <li>If possible, do not change the configuration data while there is a Driver object rendering.
+Setup the configuration only once, preferably in the <code>init()</code> method of the servlet.
+ </li>
+ <li>If you must change the configuration data more often, or if you have multiple servlets within the same webapp using FOP, consider implementing a singleton class to encapsulate the configuration settings and to run FOP in synchronized methods.
+ </li>
+ </ul>
+ </section>
+ <section id="servlet-engine">
+ <title>Servlet Engines</title>
+ <p>
+ When using a servlet engine, there are potential CLASSPATH issues, and potential conflicts with existing XML/XSLT libraries.
+Servlet containers also often use their own classloaders for loading webapps, which can cause bugs and security problems.
+ </p>
+ <section id="tomcat">
+ <title>Tomcat</title>
+ <p>
+ Check Tomcat's documentation for detailed instructions about installing FOP and Cocoon.
+There are known bugs that must be addressed, particularly for Tomcat 4.0.3.
+ </p>
+ </section>
+ <section id="websphere">
+ <title>WebSphere 3.5</title>
+ <p>
+ Put a copy of a working parser in some directory where WebSphere can access it.
+For example, if /usr/webapps/yourapp/servlets is the CLASSPATH for your servlets, copy the Xerces jar into it (any other directory would also be fine).
+Do not add the jar to the servlet CLASSPATH, but add it to the CLASSPATH of the application server which contains your web application.
+In the WebSphere administration console, click on the "environment" button in the "general" tab.
+In the "variable name" box, enter "CLASSPATH".
+In the "value" box, enter the correct path to the parser jar file (/usr/webapps/yourapp/servlets/Xerces.jar in our example here).
+Press "OK", then apply the change and restart the application server.
+ </p>
+ </section>
+ </section>
<section>
<title>Examples</title>
<p>
<question>How do I pass parameters to the XSLT transformation?</question>
<answer>
<p>
- See the end of the answer for the question above.
+ See <link href="embedding.html#servlet-transform">Using FOP in a Servlet with XSLT Transformation</link>.
</p>
</answer>
</faq>
<question>How do I set the baseDir property in a servlet environment?</question>
<answer>
<p>
- Use:
- </p>
- <source>org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir");</source>
- <p>
- or
- </p>
- <source>org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir");</source>
- <p>
- See <link href="#usercfg">using a user configuration file</link>
- for caveats.
+ See <link href="embedding.html#config-internal">Setting the Configuration Programmatically</link>.
</p>
</answer>
</faq>
<question>How do I use a user configuration file from a servlet?</question>
<answer>
<p>
- Use:
- </p>
- <source>org.apache.fop.apps.Options options = new Options(new File("userconfig.xml"));</source>
- <p>
- No further reference to the <code>options</code> variable is
- necessary. It is recommended to load the user configuration file only
- once, preferably in the <code>init()</code> method of the servlet. If
- you have multiple servlets running FOP, or if you have to change the
- configuration often, it is best to place the configuration changing
- code and the FOP driver call into a synchronized method, or perhaps a
- singleton class, in order to avoid problems in multithreaded
- environments.
+ See <link href="embedding.html#config-external">Using a Configuration File in an Embedded App</link>.
</p>
</answer>
</faq>
get FOP working for various servlet engines?</question>
<answer>
<p>
- There are various classpath issues, and possible conflicts with
- existing XML/XSLT libraries. Because servlet containers often use
- their own classloaders for loading webapps, bugs and security problems
- can be bothersome as well.
- </p>
- <p>
- Tomcat comes with detailed instructions for installing FOP and Cocoon,
- check the documentation. There are known bugs to be circumvented, in
- particular in Tomcat 4.0.3.
- </p>
- <p>
- Websphere 3.5: See next question.
- </p>
- </answer>
- </faq>
- <faq id="websphere_3_5">
- <question>FOP in IBM Websphere 3.5</question>
- <answer>
- <p>
- Put a copy of a working parser in some directory where WebSphere can
- access it, for example, if /usr/webapps/yourapp/servlets is the
- classpath for your servlets, copy the Xerces jar into it (any other
- directory would also be fine). Do not add the jar to the servlet
- classpath, but add it to the classpath of the application server which
- contains your web application. In the WebSphere administration
- console, click on the "environment" button in the "general" tab. Fill
- CLASSPATH in the "variable name" box and
- /usr/webapps/yourapp/servlets/Xerces.jar (or whatever your complete
- path is) in the value box, press "OK", then apply the change and
- restart the application server.
+ See <link href="embedding.html#servlet-engine">Servlet Engines</link>.
</p>
</answer>
</faq>
<faq id="multithreaded">
<question>Can FOP be used in multithreaded environments?</question>
<answer>
- <p>
- FOP is not completely thread safe. At the very least you'll have to
- create a Driver object for every thread unless you prefer your threads
- being blocked.
- </p>
- <p>
- Even though the relevant methods of the Driver object are
- synchronized, there are still problems because FOP uses static
- variables for configuration data and loading images. Be sure not
- to change the configuration data while there is a Driver object
- rendering. It is recommended to setup the configuration only
- once while initialising the servlet. If you have to change the
- configuration data more often, or if you have several servlets
- within the same webapp using FOP, consider implementing a
- singleton class encapsulating both the configuration settings
- and running FOP in synchronized methods.
- </p>
+ <p></p>
</answer>
</faq>
</part>
projects / xmlgraphics-fop.git / commitdiff