PHP/Java Bridge SvnRepo

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

  The PHP/Java Bridge is a network protocol which can be used to
  connect PHP with a Java or ECMA 335 VM.

  Please read the ABOUT.HTM contained in the download archive or
  http://php-java-bridge.sf.net for more information.


Overview
--------

  Although it is possible to start Java manually or automatically as
  a sub-component of the HTTP server (see below), it is recommended to
  start the Java VM via a J2EE application server or servlet engine:

* When a native HTTP server (Apache or IIS) is not available, the
  bridge can run PHP applications within a pure Java application server
  or servlet engine using the PHP FastCGI SAPI:

   internet 
  clients 
        \                    
         \ jsp/servlet/php req.                     .
           \                                        .
            ---- :8080 -- J2EE AS                   .
           /                 |                      .
          |                  |                      .
          |                  ---- servlet         /------ :9667
          |                  ---- FastCGIServlet /  .   PHP FastCGI Server
          |                  ---- jsp               .        |
          |                  ->-- PhpJavaServlet    .        \--- php
          |                  ---- ...            \ ------->--\--- php -->|
          |                                         .  P-J-B      ...    |
          |                                         .  PROTOCOL          |
          ------------------------------<--------------------------------|
                                   P-J-B PROTOCOL   .

  * When Apache or IIS is available, the administrator may set up the
  mod_jk adapter to forward JSP/Servlet requests to the J2EE AS. In
  this setup the J2EE port is not visible to internet clients and the
  Apache/IIS document root is not used:

  internet
  clients  <->  :80---> Apache or IIS                        ----> J2EE AS
                             | |                            / /     |
                             |  mod_jk -->----------------/  /      |
                             |                              /     servlet
                             --- php                       /   PhpJavaServlet
                             --> php  ---------->---------/        jsp     |
                             /   ...      P-J-B PROTOCOL           ...     |
                           /                                               |
                          ----------------------<--------------------------|
                                          P-J-B PROTOCOL

  * Or the HTTP server and the J2EE server are both connected to the
  internet. In this setup the Apache/IIS and J2EE ports are accessible
  from the internet, they share the same document root:

              :80---> Apache or IIS
            /                |
           / php req.        ---- php
          /                  ---- php  -->----------|
                               /  ...               |
  internet                    |                     |
  clients                     -------<--------|     |
          \                    P-J-B PROTOCOL |     |
           \jsp/servlet req.                  |     |
            \                                 |     |
             |--> :8080--> J2EE AS            |     |
              /                |              |     |
             /                 \--- servlet   |     |
             |                 \--- PhpJavaServlet  |
             |                 \--- jsp             |
             |                      ...             |
             -------------<-------------------------|
                    P-J-B PROTOCOL
  

Build and execution instructions:
---------------------------------

  NOTE: The folder "java" contains a pure PHP implementation of the
  PHP/Java Bridge. It is currently 10 times slower than the C based
  implementation but easier to install. See the java/README for
  details. The following describes the C based implementation.

  NOTE: If you run Security Enhanced Linux, you must update the policy
  and tag the files with the correct SEL contexts, please see below, or 
  please install the binary RPM instead.


  In the directory php-java-bridge-p.x.y type:

          java -version        # 1.4.2 or above (JDK or JRE >= 1.6 recommended)
          gcc --version        # 3.2.3 or above (4.1.x recommended)
          apachectl -version   # Apache 1.3 or above (2.x recommended)
          php-config --version # PHP 4.3.4 or above (5.x or 6.x recommended)
          make null --version  # GNU make
          autoconf --version   # GNU autoconf 2.57 or higher
          automake --version   # GNU automake 1.6.3 or higher
          libtool --version    # GNU libtool 1.4.3 or higher

          phpize &&
          ./configure --with-java=<JDK_HOME>[,<JRE_HOME>] &&
          make &&
          su -c "sh install.sh"

  Example:
       
          phpize &&./configure --with-java=/opt/jdk1.4 && make && sh install.sh


  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.

  Please see the output of ./configure --help=recursive for further
  configure options.

  Please see the INSTALL document for detailed instructions.

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

  The bridge consists of two parts, the "front-end", usually Apache,
  PHP and our PHP java extension, and a "back-end". The following
  describes how to start the back-end (if necessary) and how to configure
  PHP so that it connects to the back-end.

  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 ;; php_java.dll on windows


  To direct the extension to a specific back-end, add the following 
  options to the global php.ini file. Or add a file java-<backend>.ini,
  e.g. "java-tomcat.ini" or "java-standalone.ini" to the directory that
  contains the PHP module descriptions, usually /etc/php.d/, with the
  following content. Options:

  1) java.socketname, java.hosts and java.servlet not set: local
  back-end which starts automatically (default). Example #1:

  ;; empty


  Example #2 uses java.java_home, java.java to set the java
  executable.
 
  [java]
  java.java_home = /opt/jdk1.5
  java.java      = /opt/jdk1.5/bin/java
  java.log_file  = /var/log/php-java-bridge.log
  java.log_level = 2
 
 
  2) java.socketname set: local system back-end started by the
  system "php-java-bridge" service script. Deprecated: You need a
  service script for your operating system.
 
 
  3) java.hosts set: external back-end(s) on different server
  machines. The back-ends can be started on these servers with e.g.:
  java -jar JavaBridge.jar. Example:
 
  [java]
  java.hosts     = 192.168.5.203:9267 192.168.5.204:9267
  java.log_level = 3
 
 
  4) java.hosts=127.0.0.1:<port> and java.servlet=User: user
  back-end(s) deployed into a local j2ee application server with a shared
  document root directory (see DocumentRoot setting in the
  httpd.conf). Several JavaBridge back-ends, e.g. "MyBridge.war" or
  "Bridge31.war", can coexist in the same j2ee server. If the Apache or
  IIS server uses the same document root as the j2ee server, the
  front-end automatically connects to the associated "MyBridge" or
  "Bridge31" back-end. Example:
 
  [java]
  java.hosts     = 127.0.0.1:8080
  java.servlet   = User
  java.log_level = 3
 
 
  5) java.hosts set and java.servlet=On: "JavaBridge.war" back-end
  deployed into a j2ee application server or servlet engine. Example:
 
  [java]
  java.hosts     = 127.0.0.1:8080
  java.servlet   = On
  java.log_level = 3

 
  6) Standalone java application (see JSR223) or AS or servlet engine
  without Apache or IIS front-end. A PHP server can be started with the
  command (e.g.): X_JAVABRIDGE_OVERRIDE_HOSTS="/" PHP_FCGI_CHILDREN="20"
  PHP_FCGI_MAX_REQUESTS="5000" php-cgi -c java.ini -b 127.0.0.1:9667. 
  php-cgi starts automatically if no PHP server is listening on port 9667.
  Usually the bridge uses the official HTTP port to connect PHP with the 
  server. However, when no official HTTP port exists or if the init-param
  "override_hosts" is switched off in the servlet's WEB-INF/web.xml, the
  the bridge can use a dedicated local port# to connect PHP with Java:
  
  Example tomcat conf/server.xml setting which opens the local port 9157:

  <Service name="Catalina">
     [...]
     <!-- Local communication port used by the PHP/Java Bridge -->
     <Connector port="9157" address="127.0.0.1"  />
     [...]
  </Service>
 
  The corresponding php.ini setting uses this port:

  [java]
  java.hosts = 127.0.0.1:9157
  java.servlet = User


  After you have created the correct .ini entries, start the
  back-end. Example for option:

  #1: Not needed, back-end starts automatically
  #2: <depends on the operating system>
  #3: java -jar JavaBridge.jar INET:9267 3 php-java-bridge.log
  #4: service tomcat5 restart
  #5: service tomcat5 restart
  #6: Not needed, back-end is the calling VM 

  The Linux RPM binaries use the following options:

  php-java-bridge*.rpm            : Option #1
  php-java-bridge-tomcat*.rpm     : Option #5
  php-java-bridge-devel*.rpm      : Option #6
   

  Check the status:

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

  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.jar>
  java.java_home = <system dependent path to the java install dir>
  java.java      = <system dependent path to the java binary>
  java.socketname= <local ("unix domain") communication channel>
  java.hosts     = <add. back-ends e.g.: server1:9267 server2:9268>
  java.servlet   = <On/Off/User>, see NEWS for version 3.0.2
  java.wrapper   = Reserved for OS vendor

  java.persistent_connections = <On/Off>, see NEWS for version 3.1.0
  java.security_policy        = <On/Off/Path>, see NEWS for version 3.1.0

  Please first look at the output of phpinfo() to see the original
  values.  

---------------------------------------------
  Starting the PHP/Java Bridge automatically
  ------------------------------------------

  When the java.socketname and java.hosts options are not set, the web
  server will start or re-start the bridge (and a VM, if necessary)
  automatically as a sub component when the HTTP service is started or
  re-started.

  However, when running the bridge in a production environment, it is
  recommended to start Java from a separate service script. Tomcat5 for
  example contains such a service script for Windows and Linux/Unix.

---------------------------------------------
  Translating Java into PHP PEAR classes
  --------------------------------------

  Java libraries can be translated into PEAR classes using the command:

    java -jar JavaBridge.jar --convert /path/to/PEAR/repository ARCHIVE.JAR

  or, if you have configured the PHP/Java extension to run without Java:

    modules/java --convert /path/to/PEAR/repository ARCHIVE.JAR


  Example for Apache/Lucene:

     modules/java --convert /usr/share/pear /usr/share/java/lucene.jar

  <?php
     require_once("lucene/All.php")
     $searcher = new org_apache_lucene_search_IndexSearcher(getcwd());
     $term = new org_apache_lucene_index_Term("name", "test.php");
     $phrase = new org_apache_lucene_search_PhraseQuery();
     $phrase->add($term);

     $hits = $searcher->search($phrase);
     $iter = $hits->iterator();

     while($iter->hasNext()) {
       $next = $iter->next();
       $name = $next->get("name");
       echo "found: $name\n";
     }
  ?>

------------------------------------
  Sample settings for Apache/Tomcat
  ---------------------------------

  Assuming that tomcat is installed (e.g. in /opt/tomcat5),
  MyJavaBridge.war is deployed (e.g. in /opt/tomcat5/webapps), java.so
  (or php_java.dll) is installed in the php modules directory (e.g. in
  /usr/lib/php/modules/), mod_jk and php5 are installed in the apache modules
  directory (e.g. in /usr/lib/httpd/modules/), we recommend following
  settings:


  The following settings in httpd.conf direct all .jsp requests to the
  tomcat servlet engine and all .php requests to the php module:

    httpd.conf:
    ----------
    LoadModule php5_module        modules/libphp5.so
    LoadModule jk_module          modules/mod_jk.so

    AddType application/x-httpd-php .php
    JkAutoAlias /opt/tomcat5/webapps
    JkMount /MyJavaBridge/*.jsp ajp13
    JkMount /MyJavaBridge/ ajp13


  The following settings in php.ini direct all php "Java(...)" calls to
  the tomcat servlet engine:

    php.ini:
    --------
    extension = java.so
    ;; on windows: extension = php_java.dll
    [java]
    java.hosts     = "127.0.0.1:8080"
    java.servlet   = User ;; or: /MyJavaBridge/JavaBridge.phpjavabridge

  To check the above settings, please visit http://localhost/MyJavaBridge/
  and run the sessionSharing.jsp and sessionSharing.php examples.

  Please don't misunderstand the role of the mod_jk adapter. 
  It is only used to "mount" the tomcat webapps directory into apache and
  to forward requests for .jsp files.  The mod_jk adapter does this by
  "copying" the non jsp files from the tomcat webapps directory into
  the apache document root directory at run-time.

  A more reasonable approach would be to remove mod_jk, to create a
  shared web directory for tomcat and apache and to forward to the
  "back-end", when necessary:

              :80---> Apache or IIS
            /                |
           / php req.        ---- php
          /                  ---- php  -->----------|
              |                /  ...               |
  internet    | forward       |                     |
  clients     v               -------<--------|     |
          \                    P-J-B PROTOCOL |     |
           \jsp/servlet req.                  |     |
            \                                 |     |
             |--> :8080--> J2EE AS            |     |
              /                |              |     |
             /                 \--- servlet   |     |
             |                 \--- PhpJavaServlet  |
             |                 \--- jsp             |
             |                      ...             |
             -------------<-------------------------|
                    P-J-B PROTOCOL
  
  Most modern frameworks, Java Server Faces for example, require that
  you manually forward to the "back-end", anyway. The code would look
  like:

  <?php
   ...
   function jsfValidateEntry($ctx, $arg, $value) { ...}

   // check if we're called from the framework, forward if call failed.
   java_context()->call(java_closure()) || header("Location: index.jsf");
  ?>
   
  So you probably won't miss mod_jk's automatic forward.

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

          phpize && ./configure --with-java=$JAVA_HOME
          make CFLAGS="-m64"
  
  The scripts expect that the default JVM found in
  $JAVA_HOME/bin/java is a 64 bit VM. Unfortunately this is not true
  for the SUN JDK (Linux and Solaris) installation. The SUN JDK
  installs the 64 bit 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 no 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.

---------------------------------------------
  AS/Servlet with PHP CGI
  -----------------------

  Read the following instructions only if you don't want to use
  Apache or IIS.

  Please follow the AS or Tomcat installation instructions above, then
  visit http://localhost:8080/JavaBridge and run the supplied JSP and PHP
  examples.

  If the parameter name "use_fast_cgi" is set to "Autostart" in the
  web.xml and a fcgi server does not listen on port 9667 and a fcgi
  binary can be found as either /usr/bin/php-cgi or c:/php/php-cgi.exe,
  then the back-end automatically starts the Fast- CGI server on this
  computer, with the command:

    cd $HOME
    export X_JAVABRIDGE_OVERRIDE_HOSTS="/"
    export PHP_FCGI_CHILDREN="20"
    export PHP_FCGI_MAX_REQUESTS="5000"
    /usr/bin/php-cgi -b 127.0.0.1:9667

  On Windows the php-cgi.exe doesn't support the -b flag. Therefore an
  external "launcher.exe" is required; IBM Websphere users can find such
  a binary in the "PHP Integration Kit for Windows":
  PHPIntKitForWindows.zip, available from alphaworks. The command is:

    set X_JAVABRIDGE_OVERRIDE_HOSTS "/"
    set PHP_FCGI_CHILDREN "20"
    set PHP_FCGI_MAX_REQUESTS "5000"
    launcher.exe -a "c:\php\php-cgi" -b 9667


  The PHP FastCGI server starts when the VM or the web context starts,
  and stops when the VM or web context terminates.


  If that failed, the bridge searches for a CGI binary called:
  
    php-cgi-<architecture>-<os>.exe or

    php-cgi-<architecture>-<os>.sh or

    php-cgi-<architecture>-<os>

  in the directory WEB-INF/cgi/. On Unix the binary must be executable, it
  is therefore recommended to always use a wrapper .sh script, for example:

  #!/bin/sh
  # This wrapper script reconstructs the executable permissions
  # which some zip or .war implementations do not preserve
  chmod +x ./php-cgi-i386-linux
  exec ./php-cgi-i386-linux

  Please see the README located in the directory WEB-INF/cgi/ for
  details.

  The <architecture> and <os> values are calculated as follows:

    System.getProperty("os.arch").toLowerCase();
    System.getProperty("os.name").toLowerCase();

  Please see the output of test.php for details.


  It is also possible to adjust the php_exec setting (see
  WEB-INF/web.xml), for example:

      <param-name>php_exec</param-name>
      <param-value>/usr/local/bin/php-cgi</param-value>

  or

      <param-name>php_exec</param-name>
      <param-value>c:/PHP/php-cgi.exe</param-value>

  In case your application server denies calling the CGI binary,
  either start apache or IIS or start a fast CGI server on port 9667
  as a separate process, for example from a service script. 

  On Unix the bridge uses named pipes. On Windows, where standard
  named pipes are not available, the bridge uses TCP sockets. If your
  application server denies socket accept/resolve, please either run the
  AS on a Unix operating system or add the following lines to your AS
  policy file (for example ...\domains\domain1\config\server.policy):

    grant {
      permission java.net.SocketPermission  "*", "accept,resolve";
    };


------------------------------------
  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 safe mode (which switches
  off the dl() function) and to activate all modules in the global
  PHP ini file.

------------------------------------
  Recognized CFLAGS
  -----------------

  During compilation you can use the following CFLAGS.

   * -DJAVA_COMPILE_DEBUG: Enables the assert() statement and other
     debug code.
   
   * -DJAVA_COMPILE_DEBUG -O0 -g3: Include full debug information into
     the binary.

   * -m64: Build 64 bit code. Required if you run a 64 bit JVM.

   * -m32: Build 32 bit code. Required if you run a 32 bit JVM on a 64
     bit system.

   * -DCFG_JAVA_SOCKET_INET: Disables local ("unix domain") sockets on
      systems which support them. 

  Example: make CFLAGS="-O0 -g3"

------------------------------------
  Log level
  ---------

  You can set the java.log_level to 7 values:

   0: Log nothing, not even fatal errors.

   1: Log fatal system errors such as "out of memory error".

   2: Log java exceptions.

   3: Log verbose, e.g.: "JavaBridge version x.y.z started"

   4: Log debug messages, including the c/s communication protocol.

   5: Log method invocations, including method selection.

   6: Reserved for internal use. Log messages which may be useful
      to debug certain parts of the bridge.

  The default log level is 2.  If java.log_level is missing, the
  back-end uses the "default" log level supplied when the back-end was
  started (the second argument after java -jar JavaBridge.jar ...).

  The log4j viewer "Chainsaw" can be used to automatically capture the
  log from the bridge, regardless in which environment it is
  running. log4j.jar must be in the Java VM's java.ext.dirs (usually
  jre/lib/ext), Chainsaw must be running and the back end must have
  been started without a log file argument or with the .ini option
  java.log_file="@127.0.0.1:4445". Chainsaw can be started with e.g.:

   /opt/jdk1.5/bin/java -cp /opt/jdk1.5/jre/lib/ext/log4j.jar \
                                               org.apache.log4j.chainsaw.Main

---------------------------------------------
  GCJ/GNU Java issues
  -------------------
  
  Running the PHP/Java Bridge under GCJ ("GNU Java") is supported on Linux
  and Solaris only.  If you run FreeBSD 5.3, please use Sun, Blackdown
  or IBM java instead.

------------------------------------
  Security Enhanced Linux
  -----------------------

  SELinux is an implementation of a flexible and fine-grained
  mandatory access control architecture implemented in the Linux kernel.

  A system component running on a SELinux kernel must declare
  exactly a) which resources of the operating system it needs in order
  to function properly and b) what it provides to other components.

  The PHP/Java Bridge distribution contains two policy files,
  "php-java-bridge.te" and "php-java-bridge.fc". The
  "php-java-bridge.te" declares the javabridge_t domain and the
  resources it requires.  httpd and user domains are granted connect, 
  read and write to the PHP/Java Bridge server socket, which is
  "@var/run/.php-java-bridge_socket" in the Linux abstract name-space,
  and file create/read/write in the tmp_t.  Everything else (connections
  to other servers, file access, ...) is currently denied.

  The "php-java-bridge.fc" contains the file contexts for the PHP/Java
  Bridge and the log.

  Installation instructions for RHEL 4 and Fedora Core 4:
  -------------------------------------------------------

   1. Install selinux-policy-targeted-sources-*.rpm, for example with
      the command:

        rpm -i selinux-policy-targeted-sources-1.17.30-2.19.noarch.rpm

   2. Update the policy files with the PHP/Java Bridge policy:

        su -c "sh security/update_policy.sh /etc/selinux/targeted/src/policy"

  Installation instructions for RHEL 5, Fedora Core 5 or above:
  -------------------------------------------------------------

  1. Create the binary policy with the command:

        cd security/module; make

  2. Inject the rules into the kernel, either the php-java-bridge-tomcat.pp 
     or the php-java-bridge.pp. For example:

        semodule -i php-java-bridge.pp 

  3. The rules apply to the javabridge_t domain. Another rule
     specifies that when an executable is called from the httpd_t domain
     and the executable is tagged as javabridge_exec_t, a domain transition
     to javabridge_t occurs. It is therefore important that RunJavaBridge
     is tagged with javabridge_exec_t and that it is called from the
     httpd_t domain. Furthermore the java executable must be a binary:

        chcon -t javabridge_exec_t /usr/lib/php/modules/RunJavaBridge
        chcon -t bin_t /usr/lib/php/modules/java

  4. The policy module can be removed with the command:
  
        semodule -r javabridge
  
  If the default policy is too restrictive and e.g. you want to use
  the PHP/Java Bridge to connect to your J2EE server, you can
  temporarily set the policy to "permissive", for example with the
  command "setenforce Permissive". Connect to the server, then extract
  the permissions from the audit log, for example with the command
  "audit2allow -l -i /var/log/audit/audit.log", then append them at the
  end of the "php-java-bridge.te" file and load the updated policy into
  the kernel. Don't forget to switch back, for example with "setenforce
  Enforcing".

  Please note that SEL security is orthogonal to the standard Unix 
  security. For example you could also put the java process into 
  a "jail"; set up a user account with restricted rights, change the 
  owner of RunJavaBridge and set the SUID bit:

        chown apache:apache /usr/lib/php/modules/RunJavaBridge
        chmod 6111 /usr/lib/php/modules/RunJavaBridge

  The java process would run with the limited rights of apache *and* be 
  protected by the SEL policy.

------------------------------------
  Security issues
  ---------------

  The bridge uses abstract local sockets, named pipes (located in
  /dev/shm/ or /tmp/) or local TCP sockets as communication channels.

  It is recommended to use the local back-end on a Unix machine which
  supports abstract local ("unix domain") sockets or named pipes. On
  these systems the communication channel is not visible and cannot be
  attacked. If you are running a Security Enhanced Linux kernel, which
  is standard since RHEL4 or FC3, the back-end is also protected by the
  SEL policy. The servlet back-end uses a HTTP tunnel to execute one
  statement and then switches to named pipes for the rest of the
  communication.

  On other systems, such as Windows and Mac OSX, the bridge opens a
  local TCP port on 9167 (MonoBridge.exe) or 9267 (JavaBridge.jar), 9567
  (JavaBridge.war) or 9667 (FastCGI). Please make sure that the ports in
  the range [9167, ..., 9667] cannot be accessed from the interned.

------------------------------------
  Loading user classes and libraries
  ----------------------------------

  Java libraries should either be translated into PEAR classes (see
  above) or be installed in one of the following directories:
  /usr/share/java/ext or extension_dir/lib or, for the J2EE/servlet
  back-end, WEB-INF/lib. Libraries in these directories are
  automatically loaded by a static loader whenever the JVM starts. --
  The location of the extension_dir depends on the PHP .ini
  extension_dir setting, it is usually /usr/lib/php/modules or c:\php.

  Impure java libraries (=libraries which use the java native interface)
  must be stored in /usr/share/java/ext or in the PHP extension_dir/lib
  directory. Shared libraries (on windows: "DLL's") required by the
  impure java libraries must be stored in the java.library.path, which
  is usually the PHP extension_dir directory.

  Java libraries can also be loaded or re-loaded on demand by a
  dynamic loader. They should have the following file name:
  <name>-<version>.jar and be stored in a sub directory of the PHP
  extension_dir/lib/ directory or in a sub directory of
  /usr/share/java directory. For example:

    /usr/share/java/batStore/batStore-1.0.jar.

  Java libraries can be created from .class files with the following
  command:

    jar cvf myLibrary-0.1.jar my/package/*.class 

  The dynamic loader can link java libraries into PHP files at
  run-time, if the PHP files contain the command:

    java_require("<library1>;<libraryN>");

  Note that <library> can also be a directory containing .jar files.

  For example:

    <?php
      // process order
      java_require("j2ee.jar;myProject/myLibrary-0.1.jar");

      $proc = new Java("my.package.InputProcessor", ...);
      $proc->doSomething($_POST);
      ...
    ?>

  Minor upgrades of dynamic-loaded libraries can be installed at
  run-time. When the dynamic loader detects that the time stamp or the
  version number of the .jar file has changed, it automatically loads
  the new version.

  Disadvantages of the dynamic loader:

  * An attempt to load an impure java library immediately throws an
    UnsatisfiedLinkError.

  * Class loading via the dynamic loader is slower, because it
    cannot use the global VM class cache.

  * Libraries must be explicitly required by using the php
    java_require() procedure.

  Disadvantages of the static loader:

  * All java libraries are loaded when the Java- or Mono VM
    starts. For the PHP CLI component, which usually starts a new VM for
    each PHP invocation (unless java.hosts or java.socketname is set),
    this may cause a noticeable delay (a few 100 ms).

  * The static loader can only load libraries which are stored in the
    /usr/share/java/ext or in the PHP extension_dir/lib directory. Hot
    deployment is not possible because all classes are loaded when the
    VM starts.

  It is recommended to store Java libraries which are API stable or
  use the java native interface into the PHP extension_dir/lib directory
  or into /usr/share/java/ext. All other libraries can go into a project
  specific directory within extension_dir/lib/ or /usr/share/java/ and
  be loaded on-demand.

------------------------------------
  Sun java platform issues
  ------------------------

  The sun java platform does not support java "modules". This causes
  certain problems when running java programs. When you compile a class
  foo which references a class bar and ship the class foo without
  providing bar, the sun java platform will not complain unless the user
  accidentally calls a method which references the non-existing class. If
  this happens, a "NoClassDefFound" error is thrown. This error may
  not(!) indicate which class is missing and it certainly does not
  indicate which external library is missing. The tests.php4 folder
  contains two tests, noClassDefFound.php and noClassDefFound2.php which
  demonstrate this.

  To avoid this problem please document *exactly* (including the
  version number) which external libraries (.jar files) your software
  needs. If you have written software where certain methods require an
  optional library, please document this in the method header.

  If receive this error when using a Java library, this may mean the
  following:

    * an old or different JDK than expected by the library is used,
      for example GNU Java instead of SUN or IBM Java.

    * java_require("foo.jar"); java_require("bar.jar"); was used instead of
      java_require("foo.jar;bar.jar"); to load two interconnected libraries.

    * the library is simply broken or it expects certain parameters in
      its environment (applet parameter or system property or property file).

    * the library may only work within a J2EE environment from a
      certain vendor, for example the WebSphere Application server or
      the Sun Java Application server.

------------------------------------
  PHP issues
  ------------

  All PHP versions between 4.4.1 and 5.0.3 crash when the dl()
  function is used.

  If you use one of these versions, please add an entry to the
  php.ini, see install instructions above.

------------------------------------
  UTF-8
  -----
  
  Since PHP does not support Unicode, the PHP/Java Bridge uses UTF-8 to
  convert characters into the host representation. All strings are
  created with new String(..., "UTF-8") and all internal String->byte[]
  conversions use getBytes("UTF-8").
  
  If you have old PHP files which are not UTF-8 encoded, you can
  change the default encoding with java_set_file_encoding().  For
  example:

    java_set_file_encoding("ISO-8859-1");

  For a list of available encodings please see the documentation of
  the JVM's file.encoding system property.

  The java_set_file_encoding() primitive only affects java.lang.String
  creation and internal conversions, it does not alter the JVM's
  file.encoding system property nor does it change the behaviour of
  methods which use the file.encoding property, getBytes() for
  example.  If you use:
  
    $str=new Java ("java.lang.String", "Cze????! -- ???????? -- Gr");
    echo $str->getBytes();

  the output conversion depends on the file.encoding system property
  which in turn depends on the process' LANG environment variable. You
  can check the file.encoding with the test.php script, see above.

  To be portable please do not use conversions which depend on the
  JVM's file.encoding. They are easy to avoid, the above example
  should be written as:

    $str=new Java ("java.lang.String", "Cze????! -- ???????? -- Gr");
    echo (string)$str;  // in PHP5 or higher
    echo $str->toString(); // in PHP4

------------------------------------
  Creating thread dumps in Java 6
  -------------------------------

  * Become "super user" or "admin user" and start the program jconsole
    located in the JDK 1.6 bin directory, for example with the following
    command:

      su -c "/opt/jdk1.6/bin/jconsole"

    On Windows make sure you have admin privileges before starting
    jconsole.
     
  * In the "Create new connection" dialog select "local process" and
    click on the "JavaBridge" entry. -- If the JavaBridge doesn't appear
    there, check if the JavaBridge is running within a Java 1.6 VM and if
    the jconsole has been started with sufficient permissions.

  * Click "connect".

  * Open the "Threads" tab and click on the thread you're interested in.

------------------------------------
  Creating thread dumps in Java < 6
  ---------------------------------

  Older Java VM must be started with the following options:
  
  -Xdebug -Xrunjdwp:transport=dt_socket,address=9147,server=y,suspend=n
  
  The following description assume that Java is running as a sub
  component of Apache or IIS:

  * On Windows set the "java.java" php .ini option (in the global php.ini
    file) to:
  
    extension=php_java.dll
    [java]
    java.java="javaw -Xdebug -Xrunjdwp:transport=dt_socket,address=9147,server=y,suspend=n"
  
  * On Unix add the "java.wrapper" php .ini option (in the global php.ini
    file or in /etc/php.d/java.ini):
  
    extension = java.so
    [java]
    java.wrapper = /tmp/java.wrapper
  
    Create the file /tmp/java.wrapper with the following content:
  
    #!/bin/sh
    set -x
    java=$1; shift
    exec $java "-Xdebug -Xrunjdwp:transport=dt_socket,address=9147,server=y,suspend=n" "$@"
  
    Add the required permissions; in a command window type (as super user):
    
    chmod +x /tmp/java.wrapper
    /usr/sbin/setenforce 0     # Security Enhanced Linux only
  
  * On Windows or Unix: restart the web server, for example with:

    apachectl restart
  
  * Open a command window and type the following commands:
  
    jdb -attach 127.0.0.1:9147
    suspend
    where all
    resume

------------------------------------
  Mailing List
  ------------

  Please report bugs/problems to the mailing list:

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