Read Me

What is the PHP/Java bridge?
----------------------------

  The PHP/Java bridge connects the PHP object system with the Java object 
  system. For example it can be used to access java based applications
  running in a java application server which is 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:

          java -version        # 1.3 or above (1.4.2_02 or IBM Java recommended).
          gcc --version        # 3.2.3 or above.
          apachectl -version   # Apache 1.3 or above.
          php-config --version # PHP 4.3.2 or above. For PHP5 see below.

          phpize && ./configure --with-java=/opt/IBMJava2-14
          make CFLAGS="-DNDEBUG"

          su <password>
          make install

   If your administrator allows you to dynamically load extensions, you
   can now test the extension by invoking the test.php with the 
   command: php ./test.php.


------------------------------------
   Permanently activate the module
   -------------------------------

  
  It is recommended to activate the module in the global php ini file.

  To permanently activate the extension add 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
          # It is recommended to enable the following option and
          # to start a JVM as a separate process.
          #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 should enable
  the java.socketname option and start the java VM before you start the
  web-server.  The java VM can then be started as follows

            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

  If you are unsure how to start the java process, please look at the
  output of the above phpinfo() command.  One of the last lines shows
  the command required to start the JVM.  The distribution contains two
  scripts tested on RedHat Enterprise Linux 3.  They start the JVM based
  on the information from phpinfo(). The "php-java-bridge" command
  starts the JVM and the "php-java-bridge.service" can be used on SysV
  based init systems to automatically start and stop the bridge as a
  service.

  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 to start the VM separately>

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

------------------------------------
   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!
   echo "main(int argc,char**argv){java_bridge_main_gcj(argc,argv);}">start.c
   gcj --static -fjni -oJavaBridge.srv start.c \
       ../server/JavaBridge.java \
       ../server/natcJavaBridge.c \
       [...insert additional paths to .java classes here...] \
       -I.. -I$JAVA_HOME/include -I$JAVA_HOME/include/linux


   This creates a native, static linked executable in the current
   directory which does not need any libraries 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/

   It is recommended to compile the executable against shared
   libraries (ommit the above --static).  If you do this, you
   must package the JavaBridge.srv with the libraries it needs
   (at least libnatcJavaBridge.so, libgcc_s.so.1 and libgcj.so.3, see
   output of ldd command).

   On the installation system 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 exists,
  please use PHP 4 with the PHP/Java Bridge.

------------------------------------
  Dynamic module loading
  ----------------------

  It is possible to load the bridge dynamically, for example with:

    <?php
    if (!extension_loaded('java')) {
      if (!dl("java.so")) {
        exit(1);
      }
    }
    phpinfo();
    ?>

  However, this feature is meant for testing, only.  For a production
  system it is recommended to compile PHP in save mode (which switches
  off the dl() function) and to activate all modules in the global
  php ini file.
------------------------------------

        
   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.