PHP/Java Bridge SvnRepo

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. 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 a private java process to serve further requests.

  The bridge adds the following primitives to PHP:

  * new java("<classname>"): Instanciates the java class.

  * java_set_library_path("<jar1>;<jar2>"): Makes additional libraries
    available to the current script.  The <jar> can be either be
    a "http:", "ftp:", "file:" or a "jar:" location.  After the script
    execution the classes used by the script may or may not be garbage
    collected:
     
     <?php
      java_set_library_path("file:c:/mytest.jar");
      $mytest = new java("mytest");
      print $mytest->add(1, 2);
     ?>
     ==> 3

     <?php
      $mytest = new java("mytest");
      print $mytest
     ?>
     ==> Result undefined, mytest may have been garbage collected.

  * java_last_exception_get(): Returns the last exception instance or
    null.

  * java_last_exception_clear(): Clears the error condition.

  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.

  Custom java libraries (.jar files) can be stored in the following
  places:

   1. In the script jar_library_path of the current PHP script, if
       set (see PHP_FUNCTION(java_set_library_path)).

   2. In the sub-directory "lib" of the PHP extension directory:
      "`php-config --extension-dir`/lib" if it exists when the
      java VM starts the bridge.

   3. In the /usr/share/java/ directory, if it exists when the 
      java VM starts the bridge.


  The PHP/Java Bridge can operate in 5 different modes:

   1. Invoked from the dl() function.  This is very slow because it
      starts a new Java VM for each request.  But this mode does not
      require any administrative privileges.

   2. Compiled into the PHP binary or library.  This is not
      recommended because it requires that you mus compile PHP
      yourself.  If you want to do this, please see the Windows
      install description below.

   3. Permanently activated in the global php.ini file.  This is
      recommended, see below.

   4. Permanently activated with the Java VM running as a
      separate process.  Recommended for web servers, see below.
      This mode is used in the binary RPM package available for
      RedHat Enterprise Linux.

   5. Compiled with the GNU Java library.  You can either start
      GNU Java as a separate process (just like a "real" Java VM) or
      compile the GNU Java library into the PHP/Java Bridge.
      You can even compile the PHP/Java Bridge + GNU/Java directly
      into PHP to create a huge PHP binary or library.

  The following sections describe each of these options.
 
------------------------------------
   Permanently activate the module
   -------------------------------

  To permanently activate the extension for all users, please 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"

---------------------------------------------
   Starting the Java VM as a separate process
   ------------------------------------------

  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 be started either via the
  "php-java-bridge" script or by typing 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

  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, Solaris9 (Sparc)
  and Windows98 with RedHat Cygwin, but it should run on all Unix-like
  operating systems including HP-UX, MacOS-X, WinXP/Cygwin.  

  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 type:

   gcj --version  # must be gcj 3.3.3 or above!
   phpize && ./configure --with-java
   make install

   This creates a native, dynamic linked executable in the PHP
   extension directory.  It can be started with the command:

      `php-config --extension-dir`/java <java.socketname> <loglevel> <log-file>

   For example:

      `php-config --extension-dir`/java /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/

   GNU gcc is a "ahead of time" compiler. That means that classes
   which are added after compilation must be interpreted by the
   GNU java interpreter.  There's no "just in time" compiler.
   To compile your classes with the java executable, you can append 
   the classes, java or jar files at the end of the java_SOURCES
   line of the server/Makefile.am.  For example:
    
   java_SOURCES= java.c JavaBridge.java my_file.java

   Then type "make install" to re-install the binary. 

   If you want to compile the server part as a separate component;
   the server sub-directory is driven by autoconf and has been
   configured with the command:

     sh autogen.sh
     dir=../modules
     ./configure --with-java --libdir=$dir --datadir=$dir --bindir=$dir


   After you have created the executables you can distribute the 
   contents of the php-java-bridge-x.y.z/modules directory which
   should contain the files "java", libnatcJavaBridge.so and java.so.
   The java.so is the PHP module, the other files are required
   to start the server part.  The java executable may need other
   system libraries, for example gcj.so and gcc_s.so which should
   be installed on the target system.

------------------------------------
  64 Bit issues
  -------------
  
  It is possible to compile the bridge into 64 bit code:

          phpize && ./configure --with-java=$JAVA_HOME
          make CFLAGS="-DNDEBUG -m64"
  
  The installation expects that the default JVM found in
  $JAVA_HOME/bin/java is a 64 bit VM. Unfortunately this is not the
  case with the SUN JDK (Linux and Solaris) which install the 64bit VM
  in some sub-directory of $JAVA_HOME/bin. On Solaris9 this is
  $JAVA_HOME/bin/sparcv9. The location on Linux may depend on the
  architecture.

  Since there is not standard installation directory and we cannot
  blindly search all sub-directories, it is your job to direct the bridge
  to the 64 bit JVM.  The relevant php.ini entry is java.java, see install
  instructions above.  

------------------------------------
  Windows Installation
  --------------------

  This operating system has some unusal problems with shared libraries
  (DLL's). The autoconf/libtool documentation states:

   - Macro: AC_LIBTOOL_WIN32_DLL
     This macro should be used if the package has been ported to build
     clean dlls on win32 platforms.  Usually this means that any
     library data items are exported with `__declspec(dllexport)' and
     imported with `__declspec(dllimport)'.  If this macro is not used,
     libtool will assume that the package libraries are not dll clean
     and will build only static libraries on win32 hosts.

  Until someone ports the sources to use __declspec, we avoid 
  creating shared libraries on this system.  Instead we will
  compile the extension into PHP:


  1. Install the source code of PHP 4.3.x.

  2. Install RedHat's Cygwin (PHP needs autoconf).

  3. Delete the java sub-directory from php-4.3.x/ext and replace it
     with our php-java-bridge. Rename ext/php-java-bridge to
     ext/java.  Edit the file php-4.3.x/ext/java/config.m4 and replace
     the first 4 lines with these:

      sinclude(ext/java/tests.m4/function_checks.m4)
      sinclude(ext/java/tests.m4/java_check_broken_stdio_buffering.m4)
      sinclude(ext/java/tests.m4/java_check_broken_gcc_installation.m4)


  4. Invoke autoconf to register our java module within the PHP build
     tree and then compile php as usual:
 
      autoconf && ./configure --with-java && make

  This will create a php binary with the PHP/Java Bridge included.
  You can then copy the executable into the CGI directory of your IIS
  Web-Server.

------------------------------------
  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.

------------------------------------
  Loading on-demand with dl()
  ---------------------------

  It is possible to load the bridge for each new request, 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.