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

* Install a J2EE application server or servlet engine, for example
  Tomcat 5.5.9, Oracle 10g or WebSphere 6.

* Extract the files from the php-java-bridge J2EE download and deploy
  JavaBridge.war into your J2EE server, example for tomcat:
  
    cp JavaBridge.war $CATALINA_HOME/webapps/

* Visit http://localhost:<port>/JavaBridge and click on test.php.
  The <port> is 8888 (Oracle), 9080 (WebSphere) or 8080 (Tomcat).


Installing and testing the front-end on Linux, Unix, Windows
-----------------------------------------------------------

NOTE: Linux RPMs contain Security Enhanced Linux contexts. If you want
to install software on a SEL system (RHEL, Fedora, ...), please use
the RPM build system instead, see INSTALL.LINUX.

* Install Apache or IIS. Install PHP, for example PHP 5.1.x.

* Check if your php extension_dir contains the java extension. If not,
  copy the appropriate java-<architecture>-<os>.so or
  java-<architecture>-<os>.dll from the JavaBridge.war file to your php
  extension directory and rename it to java.so (Unix) or
  php_java.dll (Windows). Check if the java .ini entry (usually
  /usr/local/lib/php.ini or /etc/php.d/java.ini or c:\windows\php.ini
  or c:\winnt\php.ini) loads the java extension and connects php to
  the servlet back-end, e.g.:
  
    extension = java.so
    ; extension = php_java.dll
    [java]
    java.hosts   = 127.0.0.1:8080 ;or 8888 for Oracle, 9080 for WebSphere
    java.servlet = User

* Check if the HTTP document root directory is shared with the AS
  "webapps" directory. If not, change the java.servlet option to "On":

    extension = java.so
    ; extension = php_java.dll
    [java]
    java.hosts   = 127.0.0.1:8080 ;or 8888 for Oracle, 9080 for WebSphere
    java.servlet = On

  Then re-start Apache or IIS and check "java status" and "java server":

    http://yourHost.com/<userContext>/test.php

  e.g.:

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

* On production systems set the following flags in your php ini file
  so that the back-end can generate standard error pages.

    log_errors     = On
    display_errors = Off
    html_errors    = Off

* Please report bugs/problems to the mailing list:

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


* It is possible to create distributable web applications, please see
the WEB-INF/cgi/README and the FAQ for details.

* When Apache or IIS is not available, the administrator may start a
PHP standalone FastCGI 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 -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".

* If you want to allow clients to access your back-end from a remote
  host, set java.servlet=On and set allow_http_tunnel to On in the
  web.xml.

* A standalone FastCGI server is currently only available on
  Unix/Linux. When Apache or IIS is not available, the bridge uses the
  CGI interface. This is more than 5 times slower than FastCGI.

------------------------------------
Oracle 10g AS
-------------

  The following description assumes that you have the Oracle
  Application Server Containers for J2EE 10g installed, for example in
  /opt/10gAS and that the $J2EE_HOME points to the /opt/10gAS/j2ee/home
  directory.

  If you want to download the Oracle 10g AS, please only download the
  pure java implementation called "oc4j_extended.zip". It has a download
  size of less than 30MB. The complete Oracle 10g AS has a download size
  of more than 1GB and includes Apache and other software you don't need
  during development.

  Install the PHP/Java Bridge and copy the JavaBridge.war to the
  $J2EE_HOME/applications directory.

  Edit $J2EE_HOME/config/application.xml so that it contains the
  following line:

    <web-module id="JavaBridge" path="../../home/applications/JavaBridge.war"/>

  Edit $J2EE_HOME/config/http-web-site.xml so that it contains the
  following line:

    <web-app application="default" name="JavaBridge" root="/JavaBridge"/>


  Start the Oracle 10g application server, for example with:

    cd $J2EE_HOME
    java -jar oc4j.jar

  Run the PHP/Java Bridge examples, for example:

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

  or 

    http://localhost:8888/JavaBridge/sessionSharing.php

  If there are problems, please check if oracle has created the
  $J2EE_HOME/applications/JavaBridge directory and read
  $J2EE_HOME/applications/JavaBridge/WEB-INF/cgi/README.

  The log output appears in $J2EE_HOME/log/global-application.log.


  For production systems it is recommended to install the complete
  Oracle Application Server, which includes Apache, and to install
  PHP as a Apache module.

------------------------------------
IBM WebSphere AS
----------------

  The following description assumes that you have the IBM WebSphere
  6.x Application Server installed and that $WAS_HOME points to the
  /opt/IBM/WebSphere/AppServer directory.

  Install the PHP/Java Bridge. Start the application server, for
  example with the command:

    $WAS_HOME/bin/startServer.sh  server1

  Log into your application server, for example via: 

    http://localhost:9060/ibm/console/secure/logon.do

  Click on Applications -> Install New Application -> Browse
  and select JavaBridge.war. 

  Enter /JavaBridge as "Context root" and click Next.
  Click Next
  Click Continue
  Click Next
  Select JavaBridge.war and click Next
  Select JavaBridge.war and click Next
  Click Finish
  Click on "Save to Master Configuration"
  Click Save

  Click on Applications -> Enterprise Applications and select JavaBridge.war
  Click Start
  
  Run the PHP/Java Bridge examples, for example:

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

  or 

    http://localhost:9080/JavaBridge/sessionSharing.php

  If there are problems, please check if websphere has created the
  $WAS_HOME/profiles/default/installedApps/[...]/JavaBridge_war.ear/
  directory and read
  $WAS_HOME/[...]/JavaBridge_war.ear/JavaBridge.war/WEB-INF/cgi/README.

  The log output appears in the
  $WAS_HOME/profiles/default/logs/server1/ directory.


  For production systems it is recommended to install the IBM
  HttpServer (a Apache variant) and to install PHP as a Apache
  module.
