From: William Victor Mote Date: Mon, 14 Apr 2003 03:14:08 +0000 (+0000) Subject: Move remaining of the servlet examples & verbiage from faq.xml to embedding.xml. X-Git-Tag: Root_Temp_KnuthStylePageBreaking~1628 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=5bc430515c419feb2ebaab6f9bccf9758185ff3e;p=xmlgraphics-fop.git Move remaining of the servlet examples & verbiage from faq.xml to embedding.xml. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196253 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/content/xdocs/embedding.xml b/src/documentation/content/xdocs/embedding.xml index db8fab9b1..b08fe10be 100644 --- a/src/documentation/content/xdocs/embedding.xml +++ b/src/documentation/content/xdocs/embedding.xml @@ -261,6 +261,76 @@ 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.

+
+ Using a Configuration File +

+ To access an external configuration: +

+ org.apache.fop.apps.Options options = new Options(new File("userconfig.xml")); +

+ No further reference to the options variable is necessary. +

+

+ See Multithreading FOP for issues related to changing configuration in a multithreaded environment. +

+
+
+ Setting the Configuration Programmatically +

+ If you wish to set configuration options from within your embedded application, use the Configuration.put method. Here is an example that sets the "baseDir" configuration in a Unix environment: +

+ org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir"); +

+ Here is another that sets baseDir in a Windows environment: +

+ org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir"); +

+ See Multithreading FOP for issues related to changing configuration in a multithreaded environment. +

+
+
+ Multithreading FOP +

+ 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: +

+ +
+
+ Servlet Engines +

+ 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. +

+
+ Tomcat +

+ 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. +

+
+
+ WebSphere 3.5 +

+ 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. +

+
+
Examples

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index b208327b4..679c43d50 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -619,7 +619,7 @@ How do I pass parameters to the XSLT transformation?

- See the end of the answer for the question above. + See Using FOP in a Servlet with XSLT Transformation.

@@ -637,16 +637,7 @@ See loading the user configuration file for further How do I set the baseDir property in a servlet environment?

- Use: -

- org.apache.fop.configuration.Configuration.put("baseDir","/my/base/dir"); -

- or -

- org.apache.fop.configuration.Configuration.put("baseDir","C:\my\base\dir"); -

- See using a user configuration file - for caveats. + See Setting the Configuration Programmatically.

@@ -654,18 +645,7 @@ See loading the user configuration file for further How do I use a user configuration file from a servlet?

- Use: -

- org.apache.fop.apps.Options options = new Options(new File("userconfig.xml")); -

- No further reference to the options variable is - necessary. It is recommended to load the user configuration file only - once, preferably in the init() 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 Using a Configuration File in an Embedded App.

@@ -674,59 +654,14 @@ See loading the user configuration file for further get FOP working for various servlet engines?

- 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. -

-

- 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. -

-

- Websphere 3.5: See next question. -

- - - - FOP in IBM Websphere 3.5 - -

- 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 Servlet Engines.

Can FOP be used in multithreaded environments? -

- 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. -

-

- 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. -

+