# java.c File Reference

## Detailed Description

This is the main entry point for the java extension.

It contains the global structures and the callbacks required for zend engine 1 and 2.

`#include <sys/types.h>`
`#include <sys/wait.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <assert.h>`
`#include <errno.h>`
`#include "php_java.h"`
`#include "php_globals.h"`
`#include "ext/standard/info.h"`
`#include "java_bridge.h"`
`#include "api.h"`
`#include "zend_interfaces.h"`
`#include "zend_exceptions.h"`
`#include "zend_extensions.h"`

## Defines

#define | API_CALL(proc)
| try calling the procedure again with a new connection, if persistent connections are enabled
#define | EXT_ARRAY EXTC##Array

## Functions

| PHP_RINIT_FUNCTION (EXT)
| Called when a new request starts.
| PHP_RSHUTDOWN_FUNCTION (EXT)
| Called when the request terminates.
PHP_FUNCTION | last_exception_get ()
| Proto: object java_last_exception_get(void).
PHP_FUNCTION | last_exception_clear ()
| Proto: void java_last_exception_clear(void).
PHP_FUNCTION | set_file_encoding ()
| Proto: void java_set_file_encoding(string).
PHP_FUNCTION | require ()
| Proto: void java_require(string path) or java_set_library_path(string path).
PHP_FUNCTION | instanceof ()
| Proto: bool java_instanceof(object object, object clazz).
PHP_FUNCTION | get_session ()
| Proto: object java_session([string], [bool]) or object java_get_session([string], [bool]).
PHP_FUNCTION | get_context ()
| Proto: object java_context(void) or object java_get_context(void).
PHP_FUNCTION | get_server_name ()
| Proto: string java_server_name(void) or string java_get_server_name(void).
PHP_FUNCTION | reset ()
| Proto: void java_reset(void);.
PHP_FUNCTION | begin_document ()
| Proto: void java_begin_document(void).
PHP_FUNCTION | end_document ()
| Proto: void java_end_document(void).
PHP_FUNCTION | get_values ()
| Proto: mixed java_values(val) or mixed java_get_values(object ob) Evaluates the object and fetches its content, if possible.
PHP_FUNCTION | get_closure ()
| Proto: object java_closure([object],[array|string],[object]) or object java_get_closure([object],[array|string],[object]).
PHP_FUNCTION | exception_handler ()
| Only for internal use.
PHP_FUNCTION | call_with_exception_handler ()
| Only for internal use.
PHP_FUNCTION | inspect ()
| Proto: void java_inspect(object);.
PHP_FUNCTION | construct ()
| Proto: object Java::Java (string classname [, string argument1, . . . ]) or object Java::Java (array arguments) or object Java::java_exception (string classname [, string argument1, . . . ]) or object Java::JavaException (string classname [, string argument1, . . . ]);.
PHP_FUNCTION | construct_class ()
| Proto: object Java::JavaClass ( string classname) or object java::java_class ( string classname);.
PHP_METHOD | __call ()
| Proto: mixed Java::__call ( string procedure_name [, array arguments ]).
PHP_METHOD | __tostring ()
| Proto: object Java::__toString (void).
PHP_METHOD | __set ()
| Proto: void Java::__set(object, object).
PHP_METHOD | __destruct ()
| Proto: void Java::__destruct().
PHP_METHOD | __get ()
| Proto: object Java::__get(object).
PHP_METHOD | __sleep ()
| Proto: string Java::__sleep().
PHP_METHOD | __wakeup ()
| Proto: string Java::__wakeup().
PHP_METHOD | offsetExists ()
| Proto: bool Java::offsetExists().
PHP_METHOD | offsetGet ()
| Proto: object Java::offsetGet().
PHP_METHOD | offsetSet ()
| Proto: void Java::offsetSet(object, object);.
PHP_METHOD | offsetUnset ()
| Proto: string Java::offsetUnset().
| PHP_MINIT_FUNCTION (EXT)
| Called when the module is initialized.
| PHP_MINFO_FUNCTION (EXT)
| Displays the module info.
| PHP_MSHUTDOWN_FUNCTION (EXT)
| Called when the module terminates.

## Variables

cfg * | cfg = 0
| Holds the global configuration.
function_entry | functions []
zend_module_entry | module_entry
| PROTOCOL.TXT doesn't have a way to send hex numbers, if backward compatibility is enabled.
int | ini_override
| Holds the flags set/unset for all overridden java ini entries these are U_HOST, U_SERVLET and U_SOCKNAME.
int | ini_updated
| Holds the flags set/unset for all java ini entries.
int | ini_user
| The options set by the user.
int | ini_set
| The options which carry a value.
zend_class_entry * | class_entry
| Represents the java class struct.
zend_class_entry * | array_entry
| Represents the java class array struct.
zend_class_entry * | class_class_entry
| Represents the java_class class struct.
zend_class_entry * | class_class_entry_jsr
| Represents the javaclass class struct.
zend_class_entry * | exception_class_entry
| Represents the javaexception class struct.
zend_object_handlers | handlers
| The object handlers, see create_object.
function_entry | class_functions []

## Define Documentation

#define API_CALL | ( | proc |  | ) |

Value:

    EXT_GLOBAL(proc)(INTERNAL_FUNCTION_PARAM_PASSTHRU) ||   \
      (EXT_GLOBAL(cfg)->persistent_connections &&           \
       shutdown_connections(TSRMLS_C) &&                    \
       EXT_GLOBAL(proc)(INTERNAL_FUNCTION_PARAM_PASSTHRU))

try calling the procedure again with a new connection, if persistent connections are enabled

## Function Documentation

PHP_METHOD __call | ( |  | ) |

Proto: mixed Java::__call ( string procedure_name [, array arguments ]).

Calls a Java procedure Example:

     # The JPersistenceAdapter makes it possible to serialize java values.
     #
     # Example:
     # $v=new JPersistenceAdapter(new Java("java.lang.StringBuffer", "hello"));
     # $id=serialize($v);
     # $file=fopen("file.out","w");
     # fwrite($file, $id);
     # fclose($file);
     #

     class JPersistenceProxy {
      var $java;
      var $serialID;

      function __construct($java){
        $this->java=$java;
        $this->serialID;
      }
      function __sleep() {
        $buf = new Java("java.io.ByteArrayOutputStream");
        $out = new Java("java.io.ObjectOutputStream", $buf);
        $out->writeObject($this->java);
        $out->close();
        $this->serialID = base64_encode((string)$buf->toByteArray());
        return array("serialID");
      }
      function __wakeup() {
        $buf = new Java("java.io.ByteArrayInputStream",base64_decode($this->serialID));
        $in = new Java("java.io.ObjectInputStream", $buf);
        $this->java = $in->readObject();
        $in->close();
      }
      function getJava() {
        return $this->java;
      }
      function __destruct() {
        if($this->java) return $this->java->__destruct();
      }
     }

     class JPersistenceAdapter extends JPersistenceProxy {
      function __get($arg)       { if($this->java) return $this->java->__get($arg); }
      function __put($key, $val) { if($this->java) return $this->java->__put($key, $val); }
      function __call($m, $a)    { if($this->java) return $this->java->__call($m,$a); }
      function __toString()      { if($this->java) return $this->java->__toString(); }
     }

PHP_METHOD __destruct | ( |  | ) |

Proto: void Java::__destruct().

Example:

     # The JSessionAdapter makes it possible to store java values into the
     # $_SESSION variable.

     # Example:
     # $vector = new JSessionAdapter(new Java("java.util.Vector"));
     # $vector->addElement(...);
     # $_SESSION["v"]=$vector;

     class JSessionProxy {
      var $java;
      var $serialID;

      function __construct($java){
        $this->java=$java;
        $this->serialID = uniqid("");
      }
      function __sleep() {
        $session=java_get_session("PHPSESSION".session_id());
        $session->put($this->serialID, $this->java);
        return array("serialID");
      }
      function __wakeup() {
        $session=java_get_session("PHPSESSION".session_id());
        $this->java = $session->get($this->serialID);
      }
      function getJava() {
        return $this->java;
      }
      function __destruct() {
        if($this->java) return $this->java->__destruct();
      }
     }

     class JSessionAdapter extends JSessionProxy {
      function __get($arg)       { if($this->java) return $this->java->__get($arg); }
      function __put($key, $val) { if($this->java) return $this->java->__put($key, $val); }
      function __call($m, $a)    { if($this->java) return $this->java->__call($m,$a); }
      function __toString()      { if($this->java) return $this->java->__toString(); }
     }

PHP_METHOD __get | ( |  | ) |

Proto: object Java::__get(object).

The getter. Example:

     echo (string) $object->property;

If no property exists, the bean properties are examined and the getter is called, example:

     $object->getProperty()

.

PHP_METHOD __set | ( |  | ) |

Proto: void Java::__set(object, object).

The setter

Example:

     $obj->property = "value";

If no property exists, the bean properties are examined and a setter is called:

     $object->setProperty(value)

PHP_METHOD __sleep | ( |  | ) |

Proto: string Java::__sleep().

Serializes the object. Example:

       $vector=new JPersistenceAdapter(new Java("java.lang.StringBuffer", "hello"));
      $v=array (
        "test",
        $vector,
        3.14);
      $id=serialize($v);
      $file=fopen("test.ser","w");
      fwrite($file, $id);
      fclose($file);

PHP_METHOD __tostring | ( |  | ) |

Proto: object Java::__toString (void).

Displays the java object as a string. Note: it doesn't cast the object to a string, thus echo $ob displays a string representation of $ob, e.g.:

     [o(String)"hello"]

Use a string cast or java_values(), if you want to display the java string as a php string, e.g.:

     echo (string)$string; // explicit cast
     echo "$string"; // implicit cast

PHP_METHOD __wakeup | ( |  | ) |

Proto: string Java::__wakeup().

Deserializes the object. Example:

      try {
        $v=unserialize($id);
      } catch (JavaException $e) {
        echo "Warning: Could not deserialize: ". $e->getCause() . "\n";
      }

PHP_FUNCTION begin_document | ( |  | ) |

| Proto: void java_begin_document(void). Enters stream mode (asynchronuous protocol). The statements are sent to the back-end in one XML stream.

PHP_FUNCTION construct | ( |  | ) |

Proto: object Java::Java (string classname [, string argument1, . . . ]) or object Java::Java (array arguments) or object Java::java_exception (string classname [, string argument1, . . . ]) or object Java::JavaException (string classname [, string argument1, . . . ]);.

Java constructor. Example:

     $object = new Java("java.lang.String", "hello world");
     echo (string)$object;

     $ex = new JavaException("java.lang.NullPointerException");
     throw $ex;

     require_once("rt/java_util_LinkedList.php");
     class org_apache_lucene_search_IndexSearcher extends php_Java {
       __construct() {
         $args = func_get_args();
         array_unshift($args, "org.apache.lucene.search.IndexSearcher");
         $java = new Java($args);
       }
     }
     class org_apache_lucene_search_PhraseQuery extends php_Java {
       __construct() {
         $args = func_get_args();
         array_unshift($args, "org.apache.lucene.search.PhraseQuery");
         $java = new Java($args);
       }
     }
     class org_apache_lucene_index_Term extends php_Java {
       __construct() {
         $args = func_get_args();
         array_unshift($args, "org.apache.lucene.index.Term");
         $java = new Java($args);
       }
     }
     $searcher = new org_apache_lucene_search_IndexSearcher(getcwd());
     $term = new org_apache_lucene_index_Term("name", "test.php");
     $phrase = new org_apache_lucene_search_PhraseQuery();
     phrase->add($term);
     $hits = $searcher->search($phrase);
     $iter = $hits->iterator();
     $list = new java_util_LinkedList();
     while($iter->hasNext()) {
     $next = $iter->next();
     $name = $next->get("name");
     $list->append($name);
     }
     echo $list;

PHP_FUNCTION construct_class | ( |  | ) |

Proto: object Java::JavaClass ( string classname) or object java::java_class ( string classname);.

References a java class. Example:

     $Object = new JavaClass("java.lang.Object");
     $object = $Object->newInstance();

     $Thread = new JavaClass("java.lang.Thread");
     $Thread->sleep(1000);

PHP_FUNCTION end_document | ( |  | ) |

| Proto: void java_end_document(void). Ends stream mode.

PHP_FUNCTION get_closure | ( |  | ) |

Proto: object java_closure([object],[array|string],[object]) or object java_get_closure([object],[array|string],[object]).

Closes over the php environment and packages it up as a java class. Example:

     function toString() {return "helloWorld";};
     $object = java_get_closure();
     echo "Java says that PHP says: $object\n";

When a php instance is supplied as a argument, that environment will be used instead. When a string or key/value map is supplied as a second argument, the java procedure names are mapped to the php procedure names. Example:

     function hello() {return "hello";};
     echo (string)java_get_closure(null, "hello");

When an array of java interfaces is supplied as a third argument, the environment must implement these interfaces. Example:

     class Listener {
       function actionPerformed($actionEvent) {
       ...
       }
     }
     function getListener() {
       return java_get_closure(new Listener(), null, array(new Java("java.awt.event.ActionListener")));
     }

PHP_FUNCTION get_context | ( |  | ) |

Proto: object java_context(void) or object java_get_context(void).

Returns the jsr223 script context handle.

Example which closes over the current environment and passes it back to java:

     java_get_context()->call(java_closure()) || die "Script should be called from java";

It is possible to access implicit web objects (the session, the application store etc.) from the context. Please see the JSR223 documentation for details. Example:

     java_get_context()->getHttpServletRequest();

See also:
  get_session()

PHP_FUNCTION get_server_name | ( |  | ) |

Proto: string java_server_name(void) or string java_get_server_name(void).

Returns the name of the back-end or null, if the back-end is not running. Example:

     $backend = java_get_server_name();
     if(!$backend) wakeup_administrator("back-end not running");
     echo "Connected to the back-end: $backend\n";

PHP_FUNCTION get_session | ( |  | ) |

Proto: object java_session([string], [bool]) or object java_get_session([string], [bool]).

Return a session handle. When java_session() is called without arguments, the session is shared with java. Example:

     java_get_session()->put("key", new Java("java.lang.Object"));
     [...]

The java components (jsp, servlets) can retrieve the value, for example with:

     getSession().getAttribute("key");

When java_get_session() is called with a session handle, the session is not shared with java and no cookies are set. Example:

     java_get_session("myPublicApplicationStore")->put("key", "value");

When java_get_session() is called with a second argument set to true, a new session is allocated, the old session is destroyed if necessary. Example:

     java_get_session(null, true)->put("key", "val");

.

See also:
  get_context()

PHP_FUNCTION get_values | ( |  | ) |

Proto: mixed java_values(val) or mixed java_get_values(object ob) Evaluates the object and fetches its content, if possible.

A java array, Map or Collection object is returned as a php array. An array, Map or Collection proxy is returned as a java array, Map or Collection object, and a null proxy is returned as null. All values of java types for which a primitive php type exists are returned as php values. Everything else is returned unevaluated. Please make sure that the values do not not exceed php's memory limit. Example:

     $str = new java("java.lang.String", "hello");
     echo $str;
     => [o(String):"hello"]
     echo java_values($str);
     => hello
     $chr = $str->toCharArray();
     echo $chr;
     => [o(array_of-C):"[C@1b10d42"]
     $ar = java_values($chr);
     print $ar;
     => Array
     print $ar[0];
     => [o(Character):"h"]
     print java_values($ar[0]);
     => h

PHP_FUNCTION inspect | ( |  | ) |

Proto: void java_inspect(object);.

Returns the contents (public fields, public methods, public classes) of object as a string. Example:

     echo java_inspect(java_get_context());

PHP_FUNCTION instanceof | ( |  | ) |

Proto: bool java_instanceof(object object, object clazz).

Tests if object is an instance of clazz. Example:

     return($o instanceof Java && $c instanceof Java && java_instanceof($o, $c));

PHP_FUNCTION last_exception_clear | ( |  | ) |

Proto: void java_last_exception_clear(void).

Clear last java extension.

Deprecated:
  Use PHP5 try/catch instead.

PHP_FUNCTION last_exception_get | ( |  | ) |

Proto: object java_last_exception_get(void).

Get last Java exception

Deprecated:
  Use PHP5 try/catch instead.

PHP_METHOD offsetExists | ( |  | ) |

Proto: bool Java::offsetExists().

Checks if an object exists at the given position. Example:

     $System = new Java("java.lang.System");
     $props = $System->getProperties();
     if(!$props["user.home"]) die("No home dir!?!");

PHP_METHOD offsetGet | ( |  | ) |

Proto: object Java::offsetGet().

Get the object at a given position.

Example:

     $System = new Java("java.lang.System");
     $props = $System->getProperties();
     echo $props["user.home"]);

PHP_METHOD offsetSet | ( |  | ) |

Proto: void Java::offsetSet(object, object);.

Set the object at a given position. Example:

     $Array = new JavaClass("java.lang.reflect.Array");
     $testobj=$Array->newInstance(new JavaClass("java.lang.String"), array(2, 2, 2, 2, 2, 2));

     $testobj[0][0][0][0][0][1] = 1;
     $testobj[0][0][0][0][1][0] = 2;
     $testobj[0][0][0][1][0][0] = 3;
     $testobj[0][0][1][0][0][0] = 4;
     $testobj[0][1][0][0][0][0] = 5;
     $testobj[1][0][0][0][0][0] = 6;

PHP_METHOD offsetUnset | ( |  | ) |

| Proto: string Java::offsetUnset(). Remove the entry at a given position. Used internally.

PHP_MINIT_FUNCTION | ( | EXT |  | ) |

Called when the module is initialized.

Creates the Java and JavaClass structures and tries to start the back-end if java.socketname, java.servlet or java.hosts are not set. The back-end is not started if the environment variable X_JAVABRIDGE_OVERRIDE_HOSTS exists and contains either "/" or "host:port//context/servlet". When running as a Apache/IIS module or Fast CGI, this procedure is called only once. When running as a CGI binary, it is called whenever the CGI binary is called.

PHP_MSHUTDOWN_FUNCTION | ( | EXT |  | ) |

| Called when the module terminates. Stops the back-end, if it is running. When running in Apache/IIS or as a FastCGI binary, this procedure is called only once. When running as a CGI binary this is called whenever the CGI binary terminates.

PHP_RINIT_FUNCTION | ( | EXT |  | ) |

| Called when a new request starts. Opens a connection to the back-end, creates an instance of the proxyenv structure and clones the servlet, hosts and ini_user flags.

PHP_RSHUTDOWN_FUNCTION | ( | EXT |  | ) |

| Called when the request terminates. Closes the connection to the back-end, destroys the proxyenv instance.

PHP_FUNCTION require | ( |  | ) |

Proto: void java_require(string path) or java_set_library_path(string path).

Set the library path. Example:

     java_require("foo.jar;bar.jar");

The .jar files should be stored in /usr/share/java or extension_dir/lib one of its sub-directories. However, it is also possible to fetch .jar files from a remote server, for example:

     java_require("http://php-java-bridge.sf.net/kawa.jar;...");

Note that the classloader isolates the loaded libraries: When you call java_require("foo.jar"); java_require("bar.jar"), the classes from foo cannot see the classes loaded from bar. If you get a NoClassDefFound error saying that one of your classes cannot access the library you have loaded, you must reset the back-end to clear the loader cache and load your classes and the library in one java_require() call.

PHP_FUNCTION reset | ( |  | ) |

Proto: void java_reset(void);.

Tries to reset the back-end to its initial state. If the call succeeds, all caches are gone.

Example:

     echo "Resetting back-end to initial state\n";
     java_reset();

This procedure does nothing when the back-end runs in a servlet environment or an application server.

PHP_FUNCTION set_file_encoding | ( |  | ) |

Proto: void java_set_file_encoding(string).

Set the java file encoding, for example UTF-8 or ASCII. Needed because php does not support unicode. All string to byte array conversions use this encoding. Example:

     java_set_file_encoding("ISO-8859-1");

## Variable Documentation

struct cfg* cfg = 0

| Holds the global configuration. This structure is shared by all php instances

function_entry class_functions[]

Initial value:

     {
      ZEND_FENTRY(__construct, EXT_FN( construct ), NULL, 0)

      {NULL, NULL, NULL}
    }

int ini_override

Holds the flags set/unset for all overridden java ini entries these are U_HOST, U_SERVLET and U_SOCKNAME.

See also:
  X_JAVABRIDGE_OVERRIDE_HOSTS

zend_module_entry module_entry

Initial value:

     {
      STANDARD_MODULE_HEADER,
      EXT_NAME(),
       functions ,
      EXT_MINIT(EXT),
      EXT_MSHUTDOWN(EXT),
      EXT_RINIT(EXT),
      EXT_RSHUTDOWN(EXT),
      EXT_MINFO(EXT),
      NO_VERSION_YET,
      STANDARD_MODULE_PROPERTIES
    }

PROTOCOL.TXT doesn't have a way to send hex numbers, if backward compatibility is enabled.