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

* Download and install a J2EE application server or servlet engine,
  either Oracle 10g, IBM WebSphere6 or Tomcat 4 or higher. For example
  with the command: 

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

* Download and install the PHP/Java Bridge, for example with the
  command: 

    rpm -i php-java-bridge-X.Y.Z-1.i386.rpm 

  On windows you can extract the zip download file in c:\.

* Change the java .ini entry (usually /etc/php.d/java.ini or
  /etc/php.ini) so that php connects to the servlet backend, e.g.:
  
    [java]
    java.hosts   = "127.0.0.1:8080"
    java.servlet = User
  
* Deploy JavaBridge.war into your servlet engine or application
  server. For example with the command: 

    cp JavaBridge.war /usr/share/tomcat5/webapps
    service tomcat5 restart

* Test the AS backend: Browse to http://localhost:<port#>/JavaBridge
  and run the supplied examples. For example:

    http://localhost:8080/JavaBridge/test.php

* Test the Apache or IIS frontent: Check that the apache "htdocs"
  directory is shared with the AS "webapps" directory. If not, symlink
  webapps/JavaBridge to htdocs, for example with the commands:

   cd /var/www/html
   ln -s  /usr/share/tomcat5/webapps/JavaBridge .

  Then re-start apache and check "java status" and "java server":

   http://yourHost.com/JavaBridge/test.php


* Please report bugs/problems to the mailing list:

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


Individual users can create .war files which use their own php
version. Please see the WEB-INF/cgi/README for details.

When Apache or IIS is not available, the administrator may start a PHP
standalone server for all users, for example:

  export X_JAVABRIDGE_OVERRIDE_HOSTS="/"
  export PHP_FCGI_CHILDREN="20"
  export PHP_FCGI_MAX_REQUESTS="500"
  /usr/bin/php-cgi -dlog_errors=On -ddisplay_errors=Off -b 127.0.0.1:9667


When Apache or IIS is available, the administrator may set up the
mod_jk adapter to forward JSP/Servlet requests to the J2EE AS, for
example:

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

    J2EE port not visible to internet clients. Apache/IIS document root
    not used.


or he/she may connect both, apache and the j2ee server to the
internet, example:

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

    Apache/IIS and J2EE ports are accessible from the
    internet. Apache/IIS and the J2EE AS share the same document root.

Known AS Issues 
---------------

* If you see a script exception when running java-server-faces/index.php
  and the name is displayed as "null", check if apache is able to
  execute the script. If not, stop apache or change the script
  location from "@80:/java-server-faces/helloWorld.php" to
  "/java-server-faces/helloWorld.php".

* Remember to set java.servlet=User or java.servlet=<Context>.
  Otherwise session sharing with .jsp will not work and
  java-server-faces/index.php will redirect you to the local backend
  which doesn't understand anything about jsf.
  If you want to allow clients to access your service from a remote
  host, set java.servlet=On and set allow_http_tunnel to On in the
  web.xml.

* The Sun J2EE application server does not allow one to start CGI
  binaries. Start Apache or start a standalone PHP server outside of
  the AS domain instead, for example with the commands:

    cp -r SUNWappserver/domains/domain1/applications/j2ee-modules/JavaBridge/WEB-INF/cgi PHPSERVER
    cd PHPSERVER
    chmod +x ./php-cgi-i386-linux
    export X_JAVABRIDGE_OVERRIDE_HOSTS="/" 
    export PHP_FCGI_CHILDREN="20" 
    export PHP_FCGI_MAX_REQUESTS="500" 
    ./php-cgi-i386-linux -c ./php-cgi-i386-linux.ini -b 127.0.0.1:9667

  On Windows, where the bridge cannot use unix' named pipes, this AS
  needs the following permission (see server.policy usually located in
  domains\domain1\config\):

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