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(""): Instanciates the java class. * java_set_library_path(";"): Makes additional libraries available to the current script. The 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: add(1, 2); ?> ==> 3 ==> 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 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 | 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= /bin/java \ -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 \ /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 = java.classpath = java.java_home = java.java = java.socketname= 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 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: 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.