mirror of
https://github.com/php/php-src.git
synced 2024-09-22 10:27:25 +00:00
244 lines
9.8 KiB
Plaintext
244 lines
9.8 KiB
Plaintext
What is PHP4 ext/java?
|
|
|
|
PHP4 ext/java provides a simple and effective means for creating and
|
|
invoking methods on Java objects from PHP. The JVM is created using JNI,
|
|
and everything runs in-process.
|
|
|
|
Two examples are provided, jver and jawt, to illustrate usage of this
|
|
extension. 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.
|
|
|
|
Build and execution instructions:
|
|
|
|
Given the number of platforms and providers of JVMs, no single set of
|
|
instructions will be able to cover all cases. So in place of hard and
|
|
fast instructions, below are a working examples for a number of free and
|
|
commercial implementations and platforms. Please adjust the paths to
|
|
suit your installation. Also, if you happen to get this to work on
|
|
another JVM/platform combination, please let me know, particularly if
|
|
a unique build or execution setup was required.
|
|
|
|
Note for Windows users: semi-colons (";") mark the beginning of
|
|
comments in php.ini files, so if you wish to add to the classpath,
|
|
make sure that the entire string is in quotes. See the JDK 1.1.8
|
|
instructions below for an example.
|
|
|
|
This function has been tested in both CGI and Apache (apxs) modes. As
|
|
the current design requires shared libraries, this support can not be
|
|
linked statically into Apache.
|
|
|
|
With ext/java, no Java Virtual Machines are created until the first
|
|
Java call is made. This not only eliminates unnecessary overhead if
|
|
the extension is never used, it also provides error messages directly
|
|
back to the user instead of being burried in a log some place.
|
|
|
|
For people interested in robustness, performance, and more complete
|
|
integration with Java, consider using the sapi/servlet interface which
|
|
is built upon the Java extension. Running PHP as a servlet enables PHP
|
|
to utilize the existing JVM and threads from the servlet engine, and
|
|
provides direct access to the servlet request and response objects.
|
|
|
|
Finally, the bottom of this readme contains some guidance for how to
|
|
approach situations in which these instructions don't work on your
|
|
machine.
|
|
|
|
========================================================================
|
|
=== JVM=Kaffe 1.0.4 (as delivered with OS), OS=Redhat Linux 6.1 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
./configure --with-java
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.library.path=/usr/lib/kaffe:/home/rubys/php4/modules
|
|
java.class.path=/usr/share/kaffe/Klasses.jar:/home/rubys/php4/modules/php_java.jar
|
|
extension_dir=/home/rubys/php4/modules
|
|
extension=java.so
|
|
|
|
========================================================================
|
|
=== JVM=Kaffe 1.0.5 (built from source), OS=Redhat Linux 6.1 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
./configure --with-java
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.library.path=/usr/local/lib/kaffe:/home/rubys/php4/modules
|
|
java.class.path=/usr/local/share/kaffe/Klasses.jar:/home/rubys/php4/modules/php_java.jar
|
|
extension_dir=/home/rubys/php4/modules
|
|
extension=java.so
|
|
|
|
========================================================================
|
|
=== JVM=IBM 1.1.8, OS=Redhat Linux 6.1 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
./configure --with-java
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.class.path=/home/jdk118/lib/classes.zip:/home/rubys/php4/modules/php_java.jar
|
|
extension_dir=/home/rubys/php4/modules
|
|
extension=java.so
|
|
|
|
========================================================================
|
|
=== JVM=Blackdown 1.2.2 RC4, OS=Redhat Linux 6.1 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
./configure --with-java
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.class.path=/home/rubys/php4/lib/php_java.jar
|
|
extension_dir=/home/rubys/php4/modules
|
|
extension=java.so
|
|
|
|
========================================================================
|
|
=== JVM=Sun JDK 1.2.2, OS=Linux ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
./configure --with-java
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.class.path=/home/rubys/php4/lib/php_java.jar
|
|
java.library.path=/home/rubys/php4/modules
|
|
extension_dir=/home/rubys/php4/modules
|
|
extension=java.so
|
|
|
|
========================================================================
|
|
=== JVM=Sun JDK 1.1.8, OS=Windows NT 4 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
SET JAVA_HOME=D:\jdk1.1.8
|
|
msdev ext\java\java.dsp /MAKE "java - Win32 Debug_TS"
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.class.path="D:\jdk1.1.8\lib\classes.zip;F:\PHP4\Debug_TS\php_java.jar"
|
|
extension=php_java.dll
|
|
|
|
========================================================================
|
|
=== JVM=Sun JDK 1.2.2, OS=Windows NT 4 ===
|
|
========================================================================
|
|
|
|
build instructions:
|
|
|
|
SET JAVA_HOME=D:\jdk1.2.2
|
|
msdev ext\java\java.dsp /MAKE "java - Win32 Debug_TS"
|
|
|
|
php.ini:
|
|
|
|
[java]
|
|
java.class.path=F:\PHP4\Debug_TS\php_java.jar
|
|
extension=php_java.dll
|
|
|
|
=========================================================================
|
|
|
|
Guidance for when these instructions don't work.
|
|
|
|
JDK vendors don't typically document their internal workings, and are
|
|
typically very reliant on code inside of the JAVA main program and the
|
|
installation directory structure. For this reason, running PHP as a
|
|
servlet is typically much easier to get working. But if for some reason
|
|
this is not appropriate for you, and the instructions above don't work,
|
|
then read on.
|
|
|
|
The first thing to realize is that the directory structure of the JDK is
|
|
very important. Some users (particularly on Windows) get a message about
|
|
a DLL or shared library not being available and proceed to find that file
|
|
and copy it into a system directory. This typically just gets you to the
|
|
next problem - for example, it appears that many JDKs attempt to locate
|
|
the runtime Java classes (rt.jar) in a directory relative to these system
|
|
libraries. So unless you are inclined to copy your entire Java
|
|
installation, you are much better adjusting your PATHs.
|
|
|
|
Not documented above, but useful for many JDK's is ability to specify the
|
|
library path via java.library.path in the php.ini. On many Unix machines,
|
|
determining the initial value for this can be done by changing directory
|
|
to where you find a shared library that can't be loaded (example:
|
|
libjava.so), and executing "ld libjava.so". If you see some modules
|
|
listed as "not found", add the necessary directories to LD_LIBRARY_PATH
|
|
and repeat until successful. On my system, I require the following
|
|
two directories.
|
|
|
|
/home/jdk1.2.2/jre/lib/i386/native_threads
|
|
/home/jdk1.2.2/jre/lib/i386/classic
|
|
|
|
Note: this only determines the statically loaded libraries. Additional
|
|
libraries (such as libzip.so) may be loaded dynamically. On my system,
|
|
libzip.so is located in
|
|
|
|
/home/jdk1.2.2/jre/lib/i386
|
|
|
|
Another php.ini variable which may be helpful is java.home.
|
|
|
|
If java.library.path doesn't work for you (it won't on any JDK 1.1
|
|
implementations, for example), then try setting the system PATH or the
|
|
LD_LIBRARY_PATH before starting your web server. For Apache on Linux
|
|
systems, this can be accomplished by editing the Root's .bashrc and
|
|
adding the necessary export LD_LIBRARY_PATH statement.
|
|
|
|
If that doesn't work, try dividing an (hopefully) conquering by temporarily
|
|
eliminating items such as Apache from the process by adjusting the
|
|
arguments passed to the ./configure command (i.e., removing --with-apxs).
|
|
|
|
If all else fails, "man dlopen" on Unix systems will give more insight on
|
|
what the system is trying to do internally.
|