Menu
▾
▴
Tree [r567] / branches / PHP-5 / php-java-bridge / History
Read Me
What is the PHP/Java bridge?
----------------------------
The PHP/Java Bridge is a PHP 4 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"): Instanciates or references the class
CLASSNAME. After script execution the referenced classes may be
garbage collected. That means that static classes cannot be used to
hold session data unless the session keeps a reference to them. In any
case it is better to use a java.util.Properties object or a database
instead to store session data.
<?php
java_set_library_path("file:c:/mytest.jar");
$mytest = new java("mytest");
// count() increments and returns value of a static variable
print $mytest->count();
print $mytest->count();
java_set_library_path("");
$mytest = new java("mytest");
print $mytest->count();
?>
==> 1 2 3
<?php
java_set_library_path("file:c:/mytest.jar");
$mytest = new java("mytest");
print $mytest->count();
?>
==> Result undefined, may either be 1 or 4.
* 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.
* 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 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. For PHP5 see below.
phpize && ./configure --with-java=/opt/IBMJava2-14
make CFLAGS="-DNDEBUG"
su <password>
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 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.class>
java.java_home = <system dependent path to the java install dir>
java.java = <system dependent path to the java binary>
java.socketname= <hard-coded socketname to start the VM separately>
If you change the above values, please first look at the output of
phpinfo() so 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=<java.java_home> <java.java> \
-Djava.library.path=<java.libpath>
-Djava.class.path=<java.classpath>
-Djava.awt.headless=true
JavaBridge
<java.socketname>
<java.log_level>
<java.log_file>
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 <java.socketname> <loglevel> <log-file>
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, and 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 which 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.
------------------------------------
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:
<?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 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.
------------------------------------
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.
