Overview
--------

On Linux Java libraries can be:

* compiled into native code and be called directly or

* they can be installed into a Java application server and be accessed
  via RPC, as usual.


Installing the PHP/Java Bridge native Component
-----------------------------------------------

NOTE: The Linux RPM files are for RedHat Linux and compabile
distributions (WhiteBox, Fedora, ...).

* Check if the Java libraries you're interested in are available as
  native binaries. If not, you need to install Java and the J2EE
  component, see below.

* Download and install the PHP/Java Bridge base and the libraries. For
  example:

    rpm -i php-java-bridge-x.y.z-1-i386.rpm
    rpm -i lucene4php-x.y.z-1.i386.rpm
    rpm -i itext4php-x.y.z-1.i386.rpm

* Each native library contains at least one PHP example in

    /usr/share/doc/<libname>/example.

* Please report bugs/problems to the mailing list:

    php-java-bridge-users@lists.sourceforge.net


Installing the PHP/Java Bridge J2EE Component
---------------------------------------------

* Download and install a J2EE application server or servlet engine,
  for example Apache Tomcat:

    rpm -i tomcat5-5.0.30-5jpp_6fc.i386.rpm

* Download and install the PHP/Java Bridge base:

    rpm -i php-java-bridge-x.y.z-1-i386.rpm

* Either download and install the precompiled PHP/Java Bridge component
  for tomcat:

    rpm -i php-java-bridge-tomcat-x.y.z-1.i386.rpm

  This creates a file /etc/php.d/java-servlet.ini which contains the
  following settings:

     [java]
     java.hosts     = 127.0.0.1:8080
     java.servlet   = On

  Or install the J2EE component "JavaBridge.war" manually: disable
  Security Enhanced Linux (if enabled), deploy the JavaBridge.war into
  your J2EE server, example for Tomcat:
  
    setenforce Permissive
    cp JavaBridge.war /usr/share/tomcat5/webapps

  Create the file /etc/php.d/java-servlet.ini with the following content:

     [java]
     java.hosts     = 127.0.0.1:8080 ;or 8888 for Oracle, 9080 for WebSphere
     java.servlet   = On

* If the HTTP document root should be shared with the J2EE or
  servlet webapps directory, change /etc/php.d/java-servlet.ini; set
  java.servlet to User:

     java.hosts     = 127.0.0.1:8080; or 8888 for Oracle, 9080 for WebSphere
     java.servlet   = User

   and change the DocumentRoot and Directory setting in the Apache httpd
   configuration file /etc/httpd/conf/httpd.conf. Old lines are marked
   with a -, added lines with a +:

    # DocumentRoot: The directory out of which you will serve your
    # documents. By default, all requests are taken from this directory, but
    # symbolic links and aliases may be used to point to other locations.
    #
  - DocumentRoot "/var/www/html"
  + DocumentRoot "/usr/share/tomcat5/webapps"
  [...]
    # This should be changed to whatever you set DocumentRoot to.
    #
  - <Directory "/var/www/html">
  + <Directory "/usr/share/tomcat5/webapps">

  The above example assumes that the shared webapps directory is
  /usr/share/tomcat5/webapps. Change it accordingly.

* Restart the HTTP server and the J2EE back-end, for example:

    service tomcat5 restart
    service httpd restart

* Visit http://localhost:<port>/JavaBridge and click on test.php.
  The <port> is 8888 (Oracle), 9080 (WebSphere) or 8080 (Tomcat/Geronimo).

* If the HTTP document root is shared with the J2EE or servlet webapps
  directory, browse to http://your.host.com/JavaBridge and click on
  test.php. Otherwise copy test.php to the document root of the web 
  server (/var/www/html) and browse to http://your.host.com/test.php.

* Copy your java libraries (.jar files) into the extension_dir/lib [1]
  directory and your native shared libraries into extension_dir [1].

* Please report bugs/problems to the mailing list:

    php-java-bridge-users@lists.sourceforge.net

---
[1] The extension_dir is the PHP extension directory, usually
/usr/lib/php/modules. It can be set in the php .ini file [2] with
(example): extension_dir="/usr/local/lib/php/modules".

[2] The php .ini file is the global PHP configuration file. It
consists of a main file /etc/php.ini and several module specific files
located in /etc/php.d/. The two relevant files are /etc/php.d/java.ini
and /etc/php.d/java-servlet.ini.


Known Linux Issues 
------------------

* Only the precompiled php-java-bridge-tomcat-x.y.z-1.i386.rpm contains 
  Security Enhanced Linux contexts. When the J2EE component "JavaBridge.war"
  has been installed manually, Security Enhanced Linux must be switched off
  or the SEL modules must be installed separately, see the README.

* On Linux the default Java VM is GNU Java. If you want to use the SUN
  or IBM Java VM, set the JAVA_HOME option in /etc/tomcat5/tomcat5.conf.

* The precompiled php-java-bridge*.rpm binaries are 32 bit binaries
  for the x86 architecture. It is possible to build sparc, powerpc or
  64 bit binaries with the following command: 

    rpmbuild --rebuild php-java-bridge-x.y.z-1.src.rpm

  or, if you have downloaded the source archive:

    rpmbuild -tb php-java-bridge_x.y.z.tar.bz2

