Installation Instructions For Linux Users:
==========================================
 
1. To install PL/Java for use with a standard JVM on a Linux system, you must first 
confirm that a Java Runtime Environment (JRE) (version 1.6 or later) is installed 
on your machine. Installation of a Java Development Kit (JDK) provides a JRE; you 
will also find a JRE shipped with the installation of Postgres Plus Advanced Server.

In the examples that follow, references to JRE_HOME or <jre_home> indicate 
the installation directory of your JRE. If you have a JDK, substitute the location 
of $JDK_HOME/jre for JRE_HOME.

To use a 64 bit JRE on Linux, references to i386, and i386/client must be replaced
with amd64, and amd64/server respectively.

2. Edit the <EDB_HOME>/data/postgresql.conf file and add (or modify) the 
following settings:

        pljava.classpath='<EDB_HOME>/lib/pljava.jar'

3. If your Java installation is not located in the system default location, you must 
ensure that the JRE shared libraries can be located by the edb-postmaster backend.  To 
instruct the server where to find the Java libraries, modify the Advanced Server service 
startup script or the user profile, setting the path to the Java library.  Please note:
	
    * If you include the command that sets the path in the service startup script, any 
      user that invokes the startup script will set the path when the service restarts.

    * If you include the command that sets the path in a user profile, the path will only 
      be set for the session that belongs to the user that connects using that profile.

You can use your editor of choice to open the Advanced Server service script.  The script 
is named: 

    ppas-9.x

  and is located in:

    /etc/init.d

After opening the service script, locate the following line in the script:

    $SU -l enterprisedb -c "$PGENGINE/edb-postmaster -p '$PGPORT' -D '$PGDATA' ${PGOPTS} 
    &" >> "$PGLOG" 2>&1 < /dev/null

Modify the line to read:

    $SU -l enterprisedb -c "LD_LIBRARY_PATH=<path_to_libjvm.so>:\$LD_LIBRARY_PATH 
    $PGENGINE/edb-postmaster -p '$PGPORT' -D '$PGDATA' ${PGOPTS} &" >> "$PGLOG" 2>&1 < /dev/null

Where path_to_libjvm.so specifies the location of the libjvm.so file.  After saving the file, 
restart the server with the command:

    service ppas-9.x restart

To set the path in a user profile, use your editor of choice to edit the bash profile 
for that user.  For example, to edit the bash profile of the user named enteprisedb, 
open a command line and enter:

    gedit ~enterprisedb/.bash_profile

When the user profile opens, add the following line to the file:

    export LD_LIBRARY_PATH=<path_to_libjvm.so>:$LD_LIBRARY_PATH

Where path_to_libjvm.so specifies the location of the libjvm.so file.  After saving 
the file and exiting, you must reconnect as that user to set the path to the Java 
library files, and restart the database server so that all settings take effect.

    service ppas-9.x restart

4. You can install PL/Java using either the install script or the PL/Java 
Deployer application. Deployer is a Java client program that deploys PL/Java 
in the database.

The easiest method is to use the install script. To run the install script,
login to the database in which you want to install PL/Java and run the file
using the following command:

    edb-psql=# \i <EDB_HOME>/share/pljava_install.sql

Alternatively, you can use the PL/Java Deployer application.

To use the Deployer application you must use a classpath that includes deploy.jar 
(from <EDB_HOME>/lib) and edb-jdbc14.jar (from <EDB_HOME>/connectors/jdbc). 
The former contains the code for the deployer command and the second includes 
the EnterpriseDB JDBC driver. Then, run the deployer with the following command:

    java -cp <your classpath> org.postgresql.pljava.deploy.Deployer [ options ]

Option                  Description
----------              -------------
-install                Installs the Java language along with the sqlj 
                        procedures. The deployer will fail if the language is
                        installed already.
                
-reinstall              Reinstalls the Java language and the sqlj procedures. 
                        This will effectively drop all jar files that have been 
                        loaded.

-remove                 Drops the Java language and the sqlj procedures and 
                        loaded jars.
                        
-user <user name>       Name of user that connects to the database. Default is 
                        the current user.
                        
-password <password> 	Password of user that connects to the database. Default 
                        is no password.
                        
-database <database>    The name of the database to connect to. Default is edb.

-host <host name>       Name of the host. Default is "localhost".

-port <port number>     Port number. Default is 5444.


The following is an example of a PL/Java install command:

    java -cp 
    <EDB_HOME>/connectors/jdbc/edb-jdbc14.jar:<EDB_HOME>/lib/deploy.jar
    org.postgresql.pljava.deploy.Deployer -install -user enterprisedb -password
    password -database edb -host localhost -port 5444

Because of the complexity of this command line, we recommend storing the command 
line in a shell script or a .bat script.

7. Start edb-psql and connect to the database in which PL/Java was installed.
Run the following command. This will show two rows indicating that Java and 
"Java Untrusted" have been installed in the database

    select * from pg_language where lanname like 'java%';


USAGE:
========
A Java function is declared with the name of a class and a static method on that
class. The class will be resolved using the classpath that has been defined for 
the schema where the function is declared. If no classpath has been defined for 
that schema, the "public" schema is used. If no classpath is found there either,
the class is resolved using the system classloader.

The following function can be declared to access the static method getProperty
on java.lang.System class:

  CREATE FUNCTION getsysprop(VARCHAR)
    RETURNS VARCHAR
    AS 'java.lang.System.getProperty'
    LANGUAGE java;
  SELECT getsysprop('user.home');


EXAMPLE:
========
Follow these steps to write a basic HelloWorld example: 

1. Write the following code in a file and save it as HelloWorld.java 
 
     package com.mycompany.helloworld;

     public class HelloWorld 
     { public static String helloWorld() 
         { return "Hello World"; 
         }
     }

2. Compile the file:

     > javac HelloWorld.java

   and save it in a folder hierarchy as:

     com/mycompany/helloworld/HelloWorld.class

3. Create a jar file: 
   
     > jar cf helloworld.jar com/mycompany/helloworld/HelloWorld.class

4. Start edb-psql and install the jar file using: 
 
     =# SELECT sqlj.install_jar('file:///<file_path>/helloworld.jar', 
        'helloworld', true);
 
If you look up the tables sqlj.jar_entry and sqlj.jar_repository, you can 
see that that the JAR file has been loaded correctly. 

5. Set the classpath as: 
 
   =# SELECT sqlj.set_classpath('public', 'helloworld');

Look up the table sqlj.classpath_entry to see the entry for helloworld.

6. Create a function using language Java. This will call the static function 
declared in the JAR file: 
 
    CREATE OR REPLACE FUNCTION helloworld()

      RETURNS "varchar" AS

       'com.mycompany.helloworld.HelloWorld.helloWorld'

    LANGUAGE 'java' VOLATILE;  

7. Execute the function: 
   
    =# SELECT * FROM helloworld();

You should see the output:

    helloworld

    -------------

    Hello World

    (1 row)


The pl/Java official distribution is shipped with examples and documentation. The 
examples are available at the JAR hierarchy level: org.postgresql.pljava.example

For more information on usage, please see the pl/Java User Guide at: 

    http://wiki.tada.se


Installation Instructions For Windows Users:
============================================

1. To install PL/Java on Windows, you must first make sure that a Java Runtime
Environment (JRE) (version 1.6 or later) is installed on your machine. 
Installation of a Java Development Kit (JDK) provides a JRE, or you can find a JRE
shipped with the installation of Postgres Plus Advanced Server.

References to JRE_HOME or <jre_home> below indicate the installation directory 
of your JRE. If you have a JDK, JRE_HOME is equal to $JDK_HOME/jre.

2. Edit the file <EDB_HOME>\data\postgresql.conf and add (or modify) the
following settings:

    pljava.classpath='<EDB_HOME>\\lib\\pljava.jar'

3. Restart the database server so that all settings take effect.

4. Modify the PATH setting used by the edb-postmaster backend (if it runs as a
service, you will normally change the System Environment setting) so that it
contains the following two entries:

	%JRE_HOME%\bin;%JRE_HOME%\bin\client

JRE_HOME specifies the installation directory of your JRE. If you have a JDK
installed, JRE_HOME will be equal to %JAVA_HOME%\jre.

5.  You can install PL/Java using either the install script or the PL/Java
Deployer application. This is a Java client program that helps you deploy
PL/Java in the database.

The simpler way is to use the install script. To use the install script, login 
to the database in which you want to install PL/Java and run the file with the 
following command:

    edb-psql=# \i <EDB_HOME>/share/pljava_install.sql

Alternatively, you can use the PL/Java Deployer application.

To use the Deployer application, you must specify a classpath that includes deploy.jar
(from <EDB_HOME>/lib) and edb-jdbc14.jar (from <EDB_HOME>/connectors/jdbc). The 
former contains the code for the deployer command and the latter includes the 
EnterpriseDB JDBC driver. Then, invoke the deployer with the following command:

    java -cp <your classpath> org.postgresql.pljava.deploy.Deployer [ options ]

Option 	        	Description
----------      	-------------
-install                Installs the Java language along with the sqlj 
                        procedures. The deployer will fail if the language is
                        installed already.
                
-reinstall              Reinstalls the Java language and the sqlj procedures. 
                        This will effectively drop all jar files that have been 
                        loaded.

-remove                 Drops the Java language and the sqlj procedures and 
                        loaded jars.
                        
-user <user name>       Name of user that connects to the database. Default is 
                        the current user.
                        
-password <password> 	Password of user that connects to the database. Default 
                        is no password.
                        
-database <database>    The name of the database to connect to. Default is edb

-host <host name>       Name of the host. Default is "localhost".

-port <port number>     Port number. Default is 5444.


The following is an example of a PL/Java install command:

    java -cp 
    "<EDB_HOME>\\connectors\\jdbc\\edb-jdbc14.jar;<EDB_HOME>\\lib\\
    deploy.jar" org.postgresql.pljava.deploy.Deployer -install -user enterprisedb 
    -password password -database edb -host localhost -port 5444

Because of the complexity of this command line, we recommend storing the command 
line in a shell script or a .bat script.

6. Start edb-psql and connect to the database in which PL/Java was installed
Run the following command. This will show two rows indicating that Java and 
"Java Untrusted" have been installed in te database

    select * from pg_language where lanname like 'java%';
  
    
USAGE:
========
A Java function is declared with the name of a class and a static method on that
class. The class will be resolved using the classpath that has been defined for 
the schema where the function is declared. If no classpath has been defined for 
that schema, the "public" schema is used. If no classpath is found there either,
the class is resolved using the system classloader.

The following function can be declared to access the static method getProperty
on java.lang.System class:

    CREATE FUNCTION getsysprop(VARCHAR)
      RETURNS VARCHAR
      AS 'java.lang.System.getProperty'
      LANGUAGE java;
    SELECT getsysprop('user.home');


EXAMPLE:
========
Follow these steps to write a basic HelloWorld example: 

1. Write the following code in a file and save it as HelloWorld.java 
 
    package com.mycompany.helloworld;

    public class HelloWorld 
    { public static String helloWorld() 
        { return "Hello World"; 
        }
    }

2. Compile the file:

    > javac HelloWorld.java

and save it in a folder hierarchy as:

    com\mycompany\helloworld\HelloWorld.class

3. Create a jar file: 
   
    > jar cf helloworld.jar com\mycompany\helloworld\HelloWorld.class

4. Start edb-psql and install the jar file using: 
 
    =# SELECT sqlj.install_jar('file:///<file_path>/helloworld.jar', 
       'helloworld', true);
 
If you look up the tables sqlj.jar_entry and sqlj.jar_repository, you can 
see that that the JAR file has been loaded correctly 

5. Set the classpath as: 
 
    =# SELECT sqlj.set_classpath('public', 'helloworld');

Look up the table sqlj.classpath_entry to see the entry for helloworld

6. Create a function using language Java. This will call the static function 
declared in the JAR file: 
 
   CREATE OR REPLACE FUNCTION helloworld()

     RETURNS "varchar" AS

       'com.mycompany.helloworld.HelloWorld.helloWorld'

    LANGUAGE 'java' VOLATILE;  

7. Execute the function: 
   
    =# SELECT * FROM helloworld();

You should see the output:

    helloworld

    -------------

    Hello World

    (1 row)


The pl/Java official distribution is shipped with examples and documentation. The 
examples are available at the JAR hierarchy level: org.postgresql.pljava.example

For more information about using pl/Java, please see the pl/Java User Guide at: 

    http://wiki.tada.se

