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) 2006 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

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


Generated on Sun Sep 10 13:04:05 2006 for php-java-bridge by  doxygen 1.4.2