forked from tada/pljava
Hellblazer/pljava-1
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<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>
About
PL/Java is a free add-on module that brings Java™ Stored Procedures, Triggers, and Functions to the PostgreSQL™ backend.
Resources
Stars
Watchers
Forks
Packages 0
No packages published
Languages
- Java 61.2%
- C 37.4%
- Objective-C 1.4%