# 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 "zend_interfaces.h"`
`#include "zend_exceptions.h"`

## Defines

#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_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
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 []

## 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 backend in one XML stream.

PHP_FUNCTION construct | ( |  | ) |

Proto: object Java::Java (string classname [, string argument1, . . . ]) 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;

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 backend or null, if the backend is not running. Example:

     $backend = java_get_server_name();
     if(!$backend) wakeup_administrator("backend not running");
     echo "Connected to the backend: $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 backend if java.socketname, java.servlet or java.hosts are not set. The backend 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 backend, 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 backend, 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 backend, 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 backend 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 backent to its initial state. If the call succeeds, all caches are gone.

Example:

     echo "Resetting backend to initial state\n";
     java_reset();

This procedure does nothing when the backend 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}
    }

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
    }