Using PDFlib with J2EE servers 
==============================


Using the JSP and Servlet examples under the "j2ee" subdirectory
================================================================

A prerequisite for running the JSP and Servlet examples in the "j2ee"
directory is that the desired application server has been prepared
for PDFlib usage as described below.


Using PDFlib with J2EE-compliant servers
========================================

Since PDFlib is based on a native library, the JAR file and native library
must be loaded when starting the server and not from individual
server applications.

In order to use PDFlib with J2EE do the following:

- Use the deployment tool to add pdflib.jar to the project as an external
  JAR. pdflib.jar must be placed in the %J2EE_HOME%/lib directory;
  It is crucial to place pdflib.jar into the global class path instead
  of the classpath of the Web application (see below).

- pdf_java.dll or libpdf_java.so must be accessible in some system path,
  e.g. \winnt\system32 or /usr/local/lib, or via PATH/LD_LIBRARY_PATH, or it
  must be put in a path that is configured for the JVM at startup with the
  "java.library.path" system property.

If the native library is loaded from individual server applications,
an error occurs because the native library must only be loaded
once within the server. In this case you will run into the following
exception:

java.lang.UnsatisfiedLinkError: Native Library
C:\WINNT\system32\pdf_java.dll already loaded in another classloader

This is caused by multiple classloaders trying to load the PDFlib class,
and therefore the PDFlib native libary, into the server's address space
simultaneously.


Tomcat
------
For Tomcat consider the following directories for pdflib.jar: 
bad:    WEB-INF/lib           (inside the web application)
good:   $CATALINA_HOME/lib
  
  
Sun Glassfish
-------------
In order to use PDFlib with Glassfish, put the PDFlib shared library or DLL
(e.g. pdf_java.dll) and the pdflib.jar file into the directory
<glassfish-install-dir>/lib. Glassfish will pick up the PDFlib JNI library
from the lib directory without further configuration. 


Jetty
-----
In order to use PDFlib with Jetty, put the pdflib.jar file into the
directory <jetty-install-dir>/lib. The PDFlib shared library or DLL can be
put in any convenient location, but the location must be made known to
Jetty at start-up time. So if the PDFlib shared library or DLL is for 
example also put into <jetty-install-dir>/lib, start Jetty like this:

java -Djava.library.path=<jetty-install-dir>/lib -jar start.jar


IBM WebSphere
-------------
To locate the pdflib.jar file in the app server's classpath, place the jar 
file in the \<WAS app-server's path>\lib directory and edit the 
admin.config file.  In the admin.config file add the path to the jar file 
to the setting labeled:

com.ibm.ejs.sm.adminserver.classpath

If you use the Websphere Application Assembly Tool you can add pdflib.jar
to your project. 

The DLL or .so must be located somewhere on the machine's path.
The winnt\system32 directory works for Windows, the bin directory
of WAS on Solaris.

On iSeries make sure that the PDFLIB and PDF_JAVA SRVPGM can be
found in the library list of the jobs running your Java apps. The
easiest way to achieve this is to copy these SRVPGMs to the QGPL
library. In most cases this library is found in every LIBL.


Development Tools
=================

Ant
---
With the files under the "j2ee" directory comes an Ant "build.xml" file
that can be used to create a deployable WAR file. For this to work, edit 
build.xml and supply the path to the JAR file that contains the Java
Servlet API in the property named "servlet.jar". Then run "ant". This will
build a WAR file "pdflib-j2ee-samples.war".


Eclipse
-------
The "j2ee" directory is also prepared to be loaded directly into the Eclipse
IDE as a "Dynamic Web Project". In order to load the project correctly,
the "Eclipse IDE for Java EE Developers" edition must be used:

- Copy the "<pdflib-install-dir>/bind/data" directory to 
  "<pdflib-install-dir>/bind/java/j2ee/WebContent/WEB-INF/data".
  
- Open up the desired Eclipse workspace, click "File", "Import...". In the
  dialog that opens, select "General","Existing Projects into Workspace...",
  then click "Next". Check the "Select root directory" option, and browse to
  the directory "<pdflib-install-dir>/bind/java/j2ee". The 
  "pdflib-j2ee-samples" project will show up under "Projects:". Check the 
  project and click "Finish".

- The project will show compilation errors on all Java Servlet and JSP files
  because the build path must be configured to include the PDFlib JAR file 
  and the Servlet API. To fix this do the following:
  
  a) Open the Eclipse Preferences, click on "Java", "Build Path", 
     "User Libraries". Click "New" and enter "PDFlib" in the "User library 
     name" field in the "New User Library" dialog that pops up. Click "Ok".
     Keep the "PDFlib" entry selected and click on "Add Jars...". Browse to
     the directory "<pdflib-install-dir>/bind/java" and select the 
     "pdflib.jar" file.
    
  b) To resolve the references to the Servlet API, add a "Server Runtime 
     Environment" to the Java build path of the "pdflib-j2ee-samples" project.
     If no server runtime environment is configured yet, this must be done by
     opening the Eclipse preferences, clicking on "Server", "Runtime
     Environments" and by then adding a runtime environment for the desired 
     Java servlet container by clicking "Add...". For adding the desired 
     runtime environment to the Java build path of the "pdflib-j2ee-samples"
     project, open the properties of the project, click on "Java Build Path",
     switch to the "Libraries" tab, click "Add Library...". In the dialog
     that pops up, select "Server Runtime" and press "Next". In the next
     step, select the desired Server Runtime and press "Finish".

  Make sure the "Build Automatically" option is checked in the "Project"
  pulldown menu. Then after completing steps a) and b) all compile errors 
  should vanish. In the "Java EE" Eclipse perspective, configure a server
  in the "Servers" view, and add the "pdflib-j2ee-samples" to the server.


