# PLJava, 1.0.0

A source tarball and a variety of binaries can be found in the download area. Two for Windows (one win32 native for PostgreSQL 8.0 and one cygwin based for older PostgreSQL versions). On Linux PLJava also comes in a GNU Java (GCJ) flavor where the actual pljava.jar is compiled into the pljava shared object.

## Prerequisites

- PostgreSQL >= 7.4.2
- PostgreSQL JDBC drivers (needed by the client Deployer program).
- A Java runtime >= Java 1.4 or GCJ >= 3.4.1 (Linux only).

Get the binary distribution of PLJava for your platform. Unzip it into a directory of your own choice.

## Postmaster configuration

Get the PostgreSQL environment up and running. You will need to modify the `postgresql.conf` file.

With PostgreSQL 7.4.x you must make the postmaster accept TCP/IP connections (needed by the client JDBC driver). So ensure that you have:

    tcpip_socket = true

In order to find the PLJava 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 `dynamic_library_path`. I.e. you have a setting similar to this:

    dynamic_library_path = '$libdir:<pljava installation>'

Note that on the win32 platform (not cygwin) 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.

In order to see the logging from the tests add the following:

    log_min_messages = info

PostgreSQL 8.0 adds the ability do define custom variable classes to the `postgresql.conf` file. Add the following entry:

    custom_variable_classes = 'pljava'

#### System classpath

Normally, all Java code is loaded into the database using the install_jar/replace_jar SQL functions. Most of PLJava (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. If you have PostgreSQL 8.0 or later, you add the following entry to the `postgresql.conf` file:

    pljava.classpath = <pljava installation>/pljava.jar

Using PostgreSQL 7.4, the `postgresql.conf` have no entry to configure Java specific environment variables so you will need use an external environment setting:

    export CLASSPATH=<pljava installation>/pljava.jar.

#### Shared object issues

Unless you use GCJ, the postmaster must be made aware of the location of the shared objects used by the Java Runtime Environment (JRE). This accomplished by setting the `LD_LIBRARY_PATH` (Unix) or `PATH` (Windows). A standard install on an Intel Linux box will need:

    export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/client.

Apparently, on some Linux platforms you will also need to include `$JAVA_HOME/jre/lib/i386/native_threads.`

#### zlib conflict

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:

    strings libzip.so | fgrep Copyright

The problem can be resolved in one of the following ways depending on your needs and ability to recompile:

- Check if you can use a newer version of your JRE where the versions match. If so, that's probably the best solution.
- 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.
- Reconfigure PostgreSQL with `--without-zlib`, recompile and reinstall. This will effetively disable all compression support in PostgreSQL.
- Obtain a zlib version from somewhere that corresponds to the version used by the JRE and relink your PostgreSQL executables with that version.

You are now ready to start the postmaster.

## Deploying the PLJava

PLJava 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. A deploy program exists that should be used for this purpose. In order to run this program, you must see to that the PostgreSQL jdbc driver package `postgresql.jar` and the `deploy.jar` file is in your `CLASSPATH`, then run:

    java org.postgresql.pljava.deploy.Deployer

This will result in a list of options. Typically you would use something like:

    java org.postgresql.pljava.deploy.Deployer -install

That's all there's to it. You are now ready to start using the PLJava system. If the server runs on a Cygwin system you will need to add the option `-windows`. The reason for this is that PostgreSQL and Java dynamic loading uses different naming on Windows.

## Run the example tests

The tests are divided into two jar files. One is the client part found in the `test.jar`. 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 `example.jar` 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:

    SELECT sqlj.install_jar('file:///some/directory/example.jar', 'samples',  true);

If this command succeeds, everything is working correctly. You may get a couple of errors here though.

- A complaint that the class `org.postgresql.pljava.`<something> cannot be found.
  The probable cause of this is that the `CLASSPATH` seen by the postmaster is incorrect so that the pljava.jar is not found.
- A complaint that the libpljava.so or pljava.dll cannot be found. Probable cause is that the `dynamic_library_path` in the `postgresql.conf` file is incorrect.

Once loaded, you must also set the classpath used by the PLJava 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 `javatest`. To define the classpath for this schema, simply use psql and issue the command:

    SELECT sqlj.set_classpath('javatest', 'samples');

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.

NOTE: If you don't use schemas, you must still issue the set_classpath command to assign a correct classpath to the 'public' schema.

Now, you should be able to run the tests:

    java org.postgresql.pljava.test.Tester

## Building

Building should be very stright forward:

- If you are using PostgreSQL 8.0 or later, no PosgreSQL source is needed. Your path must be set to find the pg_ctl binary. The new 'pgxs' concept in PostgreSQL will take care of the rest.
- In order to build for versions prior to 8.0, you will need the complete source. You must then issue the make command like this:
  make PGSQLDIR=<full path to PostgreSQL 7.4.x source>
- If you are using GCJ, you must supply USE_GCJ=1 to the make command.
- If you are using a normal Java VM, be sure to set the JAVA_HOME environment variable.