Main Page | Data Structures | File List | Data Fields | Globals | Related Pages

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

Copyright (C) 2003-2007 Jost Boekemeier

This file is part of the PHP/Java Bridge.

The PHP/Java Bridge ("the library") is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

The library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the PHP/Java Bridge; see the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Linking this file statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

`#include "php_java.h"`
`#include <sys/types.h>`
`#include <sys/wait.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <assert.h>`
`#include <errno.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
## 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 | cast ()
| Proto: object java_cast(object, string).
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).
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.
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.

## Define Documentation

#define API_CALL | ( | proc |  | ) |

| Value:
    EXT_GLOBAL(proc)(INTERNAL_FUNCTION_PARAM_PASSTHRU) ||   \
      (can_reconnect(TSRMLS_C) &&                           \
       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 cast | ( |  | ) |

| Proto: object java_cast(object, string). Converts the java object obj into a PHP object. The second argument must be [s]tring, [b]oolean, [i]nteger, [f]loat or [d]ouble, [a]rray, [n]ull or [o]bject (which does nothing). This procedure is for compatibility with the pure PHP implementation, in the C implementation this procedure is called automatically for each type cast or when settype() is called. Example:
     $str = new java("java.lang.String", "12");
     echo $str;
     => [o(String):"12"]
     $phpString = "$str";
     echo $phpString;
     => "12"
     $phpNumber = (integer)$str;
     echo $phpNumber;
     => 12
     $phpNumber2 = java_cast($str, "integer");
     echo $phpNumber2;
     => 12

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 java_Bridge {
       __construct() {
         $args = func_get_args();
         array_unshift($args, "org.apache.lucene.search.IndexSearcher");
         $java = new Java($args);
       }
     }
     class org_apache_lucene_search_PhraseQuery extends java_Bridge {
       __construct() {
         $args = func_get_args();
         array_unshift($args, "org.apache.lucene.search.PhraseQuery");
         $java = new Java($args);
       }
     }
     class org_apache_lucene_index_Term extends java_Bridge {
       __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 an argument, the 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 name, 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

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