php/ext/java/README

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

     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=libphp_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=libphp_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=libphp_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=libphp_java.so

========================================================================
===                    JVM=Sun JDK 1.2.2, OS=Linux                   ===
========================================================================

This compiler is not supported at this time.  At the moment, only green
threads are supported, requiring system calls to be wrapped, which is
incompatible with the JNI Invocation API.  Once native threads are
supported, It is expected that the configuration will be identical to
the Blackdown JDK. 

========================================================================
===                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.