What is the PHP/Java bridge? ---------------------------- The PHP/Java Bridge is a PHP module which connects the PHP object system with the Java object system. 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 does not detect a running java application server, it starts a private java process to serve further requests. The bridge adds the following primitives to PHP: * new java("CLASSNAME"): References and instanciates the class CLASSNAME. After script execution the referenced classes may be garbage collected. To access classes within other classes the class$innerClass syntax must be used instead of the normal dot notation. Examples: $String = new java("java.lang.String"); print $String->valueOf(null); $hello = new java("java.lang.String", "hello"); print $hello; $inner = new java("package.testClass$innerClass"); $inner->value = 2; * new java_class("CLASSNAME"): References the class CLASSNAME but does not call a constructor. The object returned is the class object. After script execution the referenced classes may be garbage collected. Example: $Class = new java_class("java.lang.String"); $obj = $Class->newInstance(); * java_set_library_path("JAR1;JAR2"): Makes additional libraries available to the current script. JAR can either be a "http:", "ftp:", "file:" or a "jar:" location. Example: $file=new java("java.io.File", "WEB_INF/web.xml"); java_set_library_path("file:c:/xerces.jar;http://localhost/jdom.jar"); $builder = new java("org.jdom.input.SAXBuilder"); $doc = $builder->build($file); $root = $doc->getRootElement(); $servlets = $root->getChildren("servlet"); java_set_library_path(""); echo "this file has " . $servlets->size() . " servlets\n"; * java_exception: A java exception class. Available in PHP 5 and above only. Example: try { new java("java.lang.String", null); } catch(java_exception $ex) { $trace = new java("java.io.ByteArrayOutputStream"); $ex->printStackTrace(new java("java.io.PrintStream", $trace)); print "java stack trace: $trace\n"; } * java_instanceof(OBJECT, CLASS): Tests if the java object OBJECT is an instance of the java class CLASS or not. Example: foreach($list as $key=>$value) { if($value instanceof java) if(java_instanceof($value, $ListClass)) ... } * java_last_exception_get(): Returns the last exception instance or null. Example: if(java_last_exception_get()) java_last_exception_get()->getMessage(); * java_last_exception_clear(): Clears the error condition. Example: java_last_exception_clear(); while(!java_last_exception_get()) { ... } 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 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. The module has been tested on a Mandrake Linux System (Version 9.2), on RedHat Enterprise 3, RedHat Fedora Core 1 and 2, Solaris9 (Sparc, 64 Bit JVM) and Windows98 with RedHat Cygwin, but it should run on all Unix-like operating systems including HP-UX, MacOS-X, WinXP/Cygwin. Custom java libraries (.jar files) can be stored in the following locations: 1. Somewhere on a HTTP or FTP server, see PHP function java_set_library_path. 2. In the sub-directory "lib" of the PHP extension directory, if it exists and is accessible when the JVM starts the bridge. This is usually "`php-config --extension-dir`/lib". 3. In the /usr/share/java/ directory, if it exists and is accessible when the JVM 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 PHP. This is not recommended because it requires a compilation of the entire PHP library. 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 in the global php.ini file with an external java process. Recommended for web servers, see below. This mode is used by the 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. 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 JVM recommended) gcc --version # 3.2.3 or above. apachectl -version # Apache 1.3 or above. php-config --version # PHP 4.3.2 or above. phpize && ./configure --with-java=/opt/IBMJava2-14 make CFLAGS="-DNDEBUG" su 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 ------------------------------- 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=1 java.log_file=/var/log/php-java-bridge.log # It is recommended to enable the following option and # to start a JVM as a separate process. #java.socketname=/var/run/.php-java-bridge_socket After the module is activated verify that the module is running by typing: echo "" | 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 = java.classpath = java.java_home = java.java = java.socketname= If you change the above values, please first look at the output of phpinfo() to see the original values. --------------------------------------------- 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= \ -Djava.library.path= -Djava.class.path= -Djava.awt.headless=true JavaBridge 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 \ /var/run/.php-java-bridge_socket \ 1 \ "" | tee /var/log/php-java-bridge.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. ------------------------------------ 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 For example: `php-config --extension-dir`/java /var/run/.php-java-bridge_socket 1 "" | tee /var/log/php-java-bridge.log Then direct the bridge to the server-socket by hard-coding the java.socketname to /var/run/.php-java-bridge_socket (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. It should contain the files "java", "libnatcJavaBridge.so", "java.so" (autoconf/libtool creates other files, you can delete them). 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". They should be installed on the target system. Additional shared libraries can be copied into the php extension directory (see command "php-config --extension-dir"), additional java libraries (.jar files) can be installed in the sub-directory lib/ of the php extension directory. GNU Java still has some limitations. Because the SUN java classes are not free software, all GNU java classes had to be written from scratch. It may happen that the GNU java classes contain bugs or have certain limitations. For example con.getContentLength() constantly returns -1; length not available. However, GNU java is already good enough to be used as a bridge between PHP and the "real" java application server such as BEA WebLogic. It can be used to implement the presentation- and, depending on the project, even the service layer. | -----------------WEB SERVER --------------------- | -- APP SERVER --| Web-Server || PHP/Java Bridge || Java Apps php <-low level communication -> gnu jvm <- value objects -> sun jvm ------------------------------------ 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 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. ------------------------------------ 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. ------------------------------------ Loading on-demand with dl() --------------------------- It is possible to load the bridge for each new request, for example with: 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. ------------------------------------ Recognized CFLAGS ----------------- During compilation you can use the following CFLAGS. * -DNDEBUG: Disables the assert() statement and other debug code. * -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_ANON: Use the BSD/Linux abstract namespace instead of creating a socket file. Will only work on modern Linux/BSD implementations but not on MacOS X for example (struct ucred is non-standard). Experimental. * -DCFG_JAVA_INPROCESS: Do not use exec() but call the JVM directly. Experimental. Example: make CFLAGS="-m64 -DNDEBUG" ------------------------------------ Log levels ---------- You can set the java.log_level to 5 values: 0: Log nothing, not even fatal errors. 1: Log fatal system errors such as "out of memory error". 2: Log java errors and java exceptions. 3: Log info messages such as "loading jar xyz.jar from http://xy.com" 4: Log debug messages, including the c/s communication protocol. The default log level is 1.