| <html> |
| |
| <head> |
| <title>PL/Java readme</title> |
| <style> |
| <!-- |
| h1 { font-size: 18pt } |
| h2 { font-size: 14pt; margin-top: 12; margin-bottom: 3 } |
| h4 { font-size: 12pt; margin-top: 12; margin-bottom: 3 } |
| p { margin-top: 0; margin-bottom: 6 } |
| --> |
| </style> |
| </head> |
| |
| <body> |
| |
| <h1>PL/Java, 1.2.x</h1> |
| <p><font size="2">Java™ is a registered trademark of Sun Microsystems, Inc. in the United States and other countries.</font></p> |
| <p>A source tarball and four of binary builds can be found in the download area. |
| Two for Windows and two for i386 based Linux. Although all |
| pre-compiled binaries must run using a standard JVM, the PL/Java can also be |
| compiled and linked using GNU GCJ. PL/Java has no pre-compiled binaries for GCJ but the make system |
| contain what's needed to make the build easy.</p> |
| <p>Please note that all use of GCJ should be regarded as experimental. Due to limitations in |
| the |
| implementation of java.security in some versions of GCJ the PL/Java trusted |
| language implementation is, in fact, not trusted. At present this applies |
| regardless of what GCJ version since the code is conditionally compiled.</p> |
| <h2>Prerequisites</h2> |
| <ul> |
| <li>PostgreSQL >= 8.0.3</li> |
| <li>PostgreSQL JDBC drivers (needed by the client Deployer program).</li> |
| <li>A Java runtime >= Java 1.4 or GCJ >= 4.0.x (Linux only).</li> |
| </ul> |
| <p>Get the binary distribution of PL/Java for your platform. Unzip it into a directory |
| of your own choice.</p> |
| <h2>Postmaster configuration</h2> |
| <p>Get the PostgreSQL environment up and running. You will need to modify the |
| <code>postgresql.conf</code> file. In order to find the PL/Java shared object, you can do one of two things. Either |
| you install the shared object in a directory already searched by the postmaster |
| (such as the data directory) or you tell the postmaster where to find it using the |
| <code>dynamic_library_path</code>. I.e. you have a setting similar to this:</p> |
| <pre>dynamic_library_path = '$libdir:<pljava installation>'</pre> |
| <p>Note that on the win32 platform you need to use a semicolon as a |
| path separator and double backslashes (since backslash is the escape character in |
| the postgresql.conf file) as directory separators.</p> |
| <p>In order to see the logging from the tests add the following:</p> |
| <pre><code>log_min_messages</code> = <code>info</code></pre> |
| <p>Add the following entry:</p> |
| <pre>custom_variable_classes = 'pljava'</pre> |
| <h4>System classpath</h4> |
| Normally, all Java code is loaded into the database using the install_jar/replace_jar |
| SQL functions. Most of PL/Java (those functions included) is however implemented in Java. |
| Unless you use GCJ, where this Java code is compiled and linked with the pljava shared |
| object module, this hen and egg problem needs to be resolved using the system classpath. |
| Add the following entry to the <code> |
| postgresql.conf</code> file:</p> |
| <pre>pljava.classpath = <pljava installation>/pljava.jar</pre> |
| <h3>Shared object issues</h3> |
| <p>Unless you use GCJ, the postmaster must be made aware of the location |
| of the shared objects used by the Java Runtime Environment (JRE). Please note that this applies to the |
| <i>postmaster</i>, i.e. the <i>backend process</i>, and not to the client. The |
| client will not need these settings.</p> |
| <h4>Linux/Unix</h4> |
| <p>Setting the <code>LD_LIBRARY_PATH</code> environment will work on most Linux/Unix platforms:</p> |
| <pre><code>export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/client</code>.</pre> |
| <p>Apparently, on some Linux platforms you will also need to include <code>$JAVA_HOME/jre/lib/i386/native_threads.</code></p> |
| <p>An alternative to use <code>LD_LIBRARY_PATH</code> is to edit the <code>/etc/ld.so.conf</code> |
| file and then use /sbin/ldconfig on some Linux/Unix systems.</p> |
| <h4>zlib conflict</h4> |
| <p>On some platforms there will be a conflict between the libzip.so included in the |
| JRE and the libz.so used by PostgreSQL (the JRE libzip.so includes a libz.so). |
| The symptom is an InternalError in the java.util.zip.Inflater.init when an attempt |
| is made to load the first class. You can verify the version of libzip.so |
| using the following command:</p> |
| <pre><code>strings libzip.so | fgrep Copyright</code></pre> |
| <p>The problem can be resolved in one of the following ways depending on your needs |
| and ability to recompile:<ul> |
| <li>Check if you can use a newer version of your JRE where the versions match. If so, |
| that's probably the best solution.</li> |
| <li>Set the environment LD_PRELOAD in effect for the postmaster process to point to |
| the libzip.so present in the JRE. That will force the JRE version to be used. This |
| might break postgres own use of compression for the affected processes.</li> |
| <li>Reconfigure PostgreSQL with <code>--without-zlib</code>, recompile and reinstall. |
| This will effetively disable all compression support in PostgreSQL.</li> |
| <li>Obtain a zlib version from somewhere that corresponds to the version used by the |
| JRE and relink your PostgreSQL executables with that version.</li> |
| </ul> |
| <h4>Windows</h4> |
| <p>A standard install on a Windows box would be to add the following |
| entries to you <code>PATH</code> environment:</p> |
| <pre><code>set PATH=%PATH%;%JAVA_HOME%\jre\bin;%JAVA_HOME%\jre\bin\client</code></pre> |
| <p>You are now ready to start the postmaster.</p> |
| <h2>Deploying the PL/Java</h2> |
| <p>PL/Java adds a schema named SQLJ to the database (the naming is from the proposed |
| SQL standard for Java backend mapping) and adds a couple of tables and functions |
| to that schema. The deployment can be done in one of two ways. The simplest way |
| is probably to just execute the file <code>install.sql</code> as a super user (the |
| <code>uninstall.sql</code> will remove the PL/Java installation). PL/Java also comes with |
| deploy program that lets you install, reinstall, or uninstall PL/Java. This |
| program will assert that you indeed are a super user and then execute the |
| correct commands using jdbc. In |
| order to run this program, you must see to that the PostgreSQL jdbc driver package |
| <code>postgresql.jar</code> and the <code>deploy.jar</code> file is in your |
| <code>CLASSPATH</code>, then run:</p> |
| <pre>java org.postgresql.pljava.deploy.Deployer</pre> |
| This will result in a list of options. Typically you would use something like: |
| <pre>java org.postgresql.pljava.deploy.Deployer -install</pre> |
| <p>That's all there's to it. You are now ready to start using the PL/Java |
| system.</p> |
| <h2>Run the example tests</h2> |
| <p>The tests are divided into two jar files. One is the client part found in the <code>test.jar</code>. It contains some methods that executes |
| SQL statements and prints the output (all contained there can of course also be |
| executed from psql or any other client). The other is the <code>examples.jar</code> |
| which contains the sample code that runs in the backend. The latter must be installed |
| in the database in order to function. An easy way to do this is to use psql and |
| issue the command:</p> |
| <pre>SELECT sqlj.install_jar('file:///some/directory/examples.jar', 'samples', true);</pre> |
| <p>Please note that the deployment descriptor stored in examples.jar will attempt |
| to create the schema <code>javatest</code> so the user that executes the <code>sqlj.install_jar</code> |
| must have permission to do that. If this command succeeds, everything is working correctly. You may get a couple |
| of errors here though.</p> |
| <ul> |
| <li>A complaint that the class <code>org.postgresql.pljava.</code><something> |
| cannot be found. <br /> |
| The probable cause of this is that the <code>CLASSPATH</code> seen by the <u>postmaster</u> |
| is incorrect so that the pljava.jar is not found.</li> |
| <li>A complaint that the libpljava.so or pljava.dll cannot be found. Probable |
| cause is that the <code>dynamic_library_path</code> in the <code>postgresql.conf</code> |
| file is incorrect.</li> |
| </ul> |
| <p>Once loaded, you must also set the classpath used by the PL/Java runtime. This |
| classpath is set per schema (namespace). A schema that lacks a classpath will default |
| to the classpath that has been set for the public schema. The tests will use the |
| schema <code>javatest</code>. To define the classpath for this schema, simply use |
| psql and issue the command:</p> |
| <pre>SELECT sqlj.set_classpath('javatest', 'samples');</pre> |
| <p>The first argument is the name of the schema, the second is a colon separated |
| list of jar names. The names must reflect jars that are installed in the system.</p> |
| <p>NOTE: If you don't use schemas, you must still issue the set_classpath |
| command to assign a correct classpath to the 'public' schema. This can only be |
| done by a super user.</p> |
| <p> </p> |
| <p>Now, you should be able to run the tests:</p> |
| <pre>java org.postgresql.pljava.test.Tester</pre> |
| </code> |
| |
| <h2>Building</h2> |
| <p>Building should be very stright forward:</p> |
| <ul> |
| <li>No PosgreSQL source is needed. |
| Your path must be set to find the pg_config binary. The 'pgxs' concept in |
| PostgreSQL will take care of the rest.</li> |
| <li>If you are using GCJ, you must supply USE_GCJ=1 to the make command.</li> |
| <li>If you are using a normal Java VM, be sure to set the JAVA_HOME |
| environment variable.</li> |
| </ul> |
| |
| </body> |
| |
| </html> |