Read Me

What is the PHP/Java bridge?

         The PHP/Java bridge allows one to access java based
         applications running in a java application server running 
         on the local host.  The PHP/Java bridge communicates with 
         the application server through local sockets using an 
         efficient communication protocol.  This means that only one 
         JVM runs to serve all clients within a multi-process HTTP-Server.  
         Each client process communicates with a corresponding thread 
         spawned by the running application server.

         If the bridge detects that a java application server is not
         already running, it starts one to serve further requests.

         There is one example provided: test.php.  You can either invoke
         the test.php by typing ./test.php or copy the example into the
         document root of you web-server and invoke the file using the
         browser.

         The PHP/Java bridge is meant as a replacement for the ext/java
         bridge shipped with PHP 4.  It is not possible to run the 
         build-in bridge and the PHP/Java bridge at the same time.


Build and execution instructions:

          In the directory php-java-bridge_1.x.y type:

          php --version  # must be PHP 4.3.2 or above! For PHP5 see below.
          phpize && ./configure --with-java=/opt/IBMJava2-141/ && make

          su <password>
          make install

          and then activate the extension by adding the following lines to
          the php.ini or add a file java.ini to the directory that
          contains the php module descriptions (usually /etc/php.d/) with
          the following content:

          extension = java.so
          [java]
          java.log_level=5
          java.log_file=/tmp/java.log
          #java.socketname=/tmp/.php_java

          After the module is activated, verify that the module is running
          by typing:

          echo "<?php phpinfo()?>" | php | fgrep "java status"

          If you want to test the extension in the Web-Server, you must
          restart the Web-Server after you have installed the extension.

          This module has been tested on a Mandrake Linux System (Version
          9.2), on RedHat Enterprise 3, RedHat Fedora Core 1 and 2, but 
          it should run on all Unix-like operating systems including 
          Solaris, Mac.   

          However, the extension currently does not compile on systems
          which do not support fork()/exec().  On these systems you must
          disable the code in bind.c and start the java application server
          yourself.  Fortunately all modern operating systems -- except
          Windows -- support fork()/exec()


          Other configuration options which should have been set up by the
          configure script but which can be changed later are:

          java.libpath   = <system dependent path to natcJavaBridge.so>
          java.classpath = <system dependent path to JavaBridge.class>
          java.java_home = <system dependent path to the java install dir>
          java.java      = <system dependent path to the java binary>
          java.socketname= <hard-coded socketname for debugging>

          If you change the above values, please fist look at the output
          of phpinfo() so see the original values.

          For debugging you can also start a external java application 
          with the following command:

            JAVA_HOME=<java.home> <java.home>/bin/java \
                                        -Djava.library.path=<java.libpath>
                                        -Djava.class.path=<java.classpath> 
                                        -Djava.awt.headless=true  
                                        JavaBridge 
                                        <java.socketname>
                                        <loglevel>
                                        <log-file>

          For example in a gnome-terminal type:

            JAVA_HOME=/opt/jdk1.4 $JAVA_HOME/bin/java \
                    -Djava.library.path=/usr/lib/php4 \
                    -Djava.class.path  =/usr/lib/php4 \
                    -Djava.awt.headless=true \
                     JavaBridge \
                     /tmp/.php_java \ 
                     5 \
                     "" | tee /tmp/java.log

         Then point the bridge to the socket /tmp/.php_java by 
         hard-coding the java.socketname to /tmp/.php_java and
         re-start the apache service.

------------------------------------
         QUICK INSTALL

           su - -c "service httpd stop"
           INST=/usr/local

           gunzip < httpd_2.x.y.tar.gz | tar xf -
           cd httpd_2.x.y
           ./configure --prefix=$INST
           make && su -c "make install"
           cd ..

           bunzip2 < php-4.3.x.tar.bz2 | tar xf -
           cd php-4.3.x
           ./configure --prefix=$INST \
                       --with-mysql \
                       --without-java \
                       --with-apxs2=$INST/bin/apxs
           make && su -c "make install"
           # now activate php in the httpd.conf
           su -c "echo 'AddType application/x-httpd-php .php' >>$INST/conf/httpd.conf"
           cd ..

           bunzip2 < php-java-bridge_1.x.y.tar.bz2 | tar xf -
           cd php-java-bridge_1.x.y
           export PATH=$INST/bin:$PATH 
           export LD_LIBRARY_PATH=$INST/lib:$LD_LIBRARY_PATH
           phpize
           ./configure --prefix=$INST \
                       --with-java=/opt/IBMJava2-141
           make && su -c "make install"
           # now activate the bridge in php.ini
           su -c "touch $INST/lib/php.ini && echo -e 'extension=java.so\n[java]' >>$INST/lib/php.ini"
           cd ..

           # test
           su -c "echo '<?php phpinfo() ?>' >$INST/htdocs/phpinfo.php; chmod +xr $INST/htdocs/phpinfo.php; apachectl restart"

           # checking cli
           echo '<?php phpinfo() ?>' | php | fgrep "java status"

           # checking web
             wget -olog -O-  http://localhost/phpinfo.php|fgrep "java status"
 
------------------------------------
   Using GNU Java

   In case you don't want to ship a JVM or JRE with your product
   you can use GNU gcc to compile the java part and your classes
   into native code. 
   In the directory php-java-bridge_1.x.y/modules type:

   gcj --version  # must be gcj 3.2.3 or above!
   gcj -fjni -oJavaBridge.srv --main=JavaBridge JavaBridge.class \
                                          -L`pwd` -lnatcJavaBridge

   This creates a native executable in the current directory which
   does not need java anymore.  It can be started with the command:

      ./JavaBridge.srv <java.socketname> <loglevel> <log-file>

   For example:

      ./JavaBridge.srv /tmp/.php_java 5 "" | tee /tmp/java.log


   Then point the bridge to the socket /tmp/.php_java by hard-coding 
   the java.socketname to /tmp/.php_java (as described in the install
   instructions) and re-start the apache service.

   If you now invoke the test.php file, you should see the
   output from GNU Java (e.g.):

   ./test.php | fgrep java.vendor
     java.vendor -> Free Software Foundation, Inc.
     java.vendor.url -> http://gcc.gnu.org/java/

   You can package the JavaBridge.srv and the libraries it needs
   (at least libnatcJavaBridge.so, libgcc_s.so.1 and libgcj.so.3, see
   output of ldd command) into an RPM and make sure that your client
   starts the JavaBridge before the httpd service gets started. -- On
   RedHat the init.d/httpd is started as 85/15, so it should be
   sufficient to start the JavaBridge executable as #84 and stop it
   as #16.

------------------------------------
  PHP 5 support

  The PHP/Java bridge currently does not support the new PHP 5 object 
  system.

  Zend is working with Sun Microsystems to define a standard
  script interface for java, please see 

    http://www.jcp.org/en/jsr/detail?id=223

  for details.  When available this interface will allow PHP 5 to
  communicate with the JVM more efficiently; e.g. it will be possible 
  to compile and then execute code multiple times.
  However, it may take some time (a few years probably) until a stable
  solution is available.

  Until an official PHP5/Java binding based on JSR-223 doesn't
  exist, please use PHP 4 with the PHP/Java Bridge.
------------------------------------

        
   This module is based on the ext/java module written by Sam Ruby.
   His original comments follow.

   A few things to note:

     1) new Java() will create an instance of a class if a suitable constructor
        is available.  If no parameters are passed and the default constructor
        is useful as it provides access to classes like "java.lang.System"
        which expose most of their functionallity through static methods.

     2) Accessing a member of an instance will first look for bean properties
        then public fields.  In other words, "print $date.time" will first
        attempt to be resolved as "$date.getTime()", then as "$date.time";

     3) Both static and instance members can be accessed on an object with
        the same syntax.  Furthermore, if the java object is of type
        "java.lang.Class", then static members of the class (fields and
        methods) can be accessed.

     4) Exceptions raised result in PHP warnings, and null results.  The
        warnings may be eliminated by prefixing the method call with an
        "@" sign.  The following APIs may be used to retrieve and reset
        the last error:

          java_last_exception_get()
          java_last_exception_clear()

     5) Overload resolution is in general a hard problem given the
        differences in types between the two languages.  The PHP Java
        extension employs a simple, but fairly effective, metric for
        determining which overload is the best match.  

        Additionally, method names in PHP are not case sensitive, potentially
        increasing the number of overloads to select from.

        Once a method is selected, the parameters are cooerced if necessary, 
        possibly with a loss of data (example: double precision floating point
        numbers will be converted to boolean).

     6) In the tradition of PHP, arrays and hashtables may pretty much
        be used interchangably.  Note that hashtables in PHP may only be
        indexed by integers or strings; and that arrays of primitive types
        in Java can not be sparse.  Also note that these constructs are
        passed by value, so may be expensive in terms of memory and time.