PHP to Java bridge

When to use the PHP to Java bridge

Note: Using the bridge requires PHP developers to read and understand the Javadoc for the classes that they are accessing. This requires PHP developers to understand the Java class.

If you do not want PHP developers to have to understand the Java class you can write an extension to the PHP language using the extension interfaces described in the Extending PHP article. This enables you to provide a PHP view of the function provided by the Java class.

Example

<?php
$date = new Java("java.util.Date", 70, 9, 4);
var_dump($date->toString());

$map = new Java("java.util.HashMap");
$map->put("title", "Java Bridge!");
$map->put("when", $date);
echo $map->get("when")->toString()."\n";
echo $map->get("title")."\n";
$array = array(1,2,3,4,5);
$map->put("stuff", $array);
var_dump($map->get("stuff"))."\n";

$system = new Java("java.lang.System");
echo "OS: ".$system->getProperty("os.name")."\n";

$math = new Java("java.lang.Math");
echo "PI: ".$math->PI."\n";
?>

The new Java("java.util.HashMap") call creates a Java hash map. The script puts the date, a string, and an array into this collection and then retrieves them. Although the script creates a PHP array, what gets put into the hash map is a standard Java Map. The same applies to strings. The Java bridge converts a PHP string (essentially a byte array) into a java.lang.String string so that the Java class receives argument types that it would normally expect if the caller were another Java class.

The new Java("java.lang.System") call provides access to the java.lang.System class. Static methods can then be called on the class. The example invokes $system->getProperty(). The same applies to the java.lang.Math class although in this case the example code is accessing a public static field (PI) rather than a static method.

Using new Java()

Accessing a member

Overload resolution is in general a hard problem given the differences in types between the two languages. The Java to PHP bridge employs a simple, but fairly effective, metric for determining which overload is the best match. It chooses the method that has the best matching number of arguments (types are ignored). If there is not an exact match, then if a method exists that has less arguments than provided by the script it will be used. The opposite does not hold true, the Java to PHP bridge will not invoke a Java method that has more arguments than the script provides because Java does not have default arguments. Note that method names in PHP are not case sensitive, potentially increasing the number of overloads from which to select.

Once a method is selected, the parameters are coerced if necessary, possibly with a loss of data (example: double precision floating point numbers could be converted to boolean if that is what the Java method is expecting).

Exception handling

Since Java exceptions are not the same as PHP exceptions, there is some conversion required. All Java exceptions get converted into a generic PHP exception class called JavaException. The JavaException class allows a catch handler to find out the cause (to find out the Java exception that was thrown). All PHP exceptions inherit from the base PHP Exception class a message and code; for JavaException exceptions the code will always be zero and the message is the message extracted from the native Java exception.

The following sample code passes an invalid argument to getProperty() and then catches the java.lang.IllegalArgumentException.

<?php

try { 
        $system = new Java("java.lang.System");
        $system->getProperty(FALSE);
} catch (JavaException $exception) { 
        echo "Cause: ".$exception->getCause()."\n";
        echo "Message: ".$exception->getMessage()."\n";
}

?>

The cause is a simple text string containing the class name of the causing exception. The message in the exception is copied directly from the Java exception message (in this example the IllegalArgumentException contains no message and so displays nothing).