quercus.xtp

RESIN 3.2 最新源码

makes any java class available to the PHP script with it's unqualified name.
</p>

<example title="Example: creating a Java class with import">
&lt;?php

  import java.util.Date;

  $a = new Date(123);

  echo $a->time;
?>
</example>

<p>
User classes can be placed in the webapp's WEB-INF/classes directory.
</p>

<example title="Example: WEB-INF/classes/example/MyBean.java">
package example;

public class MyBean
{
  int _value;

  public MyBean(int value)
  {
    _value = value;
  }

  public int getValue()
  {
    return _value;
  }

  public String makeMessage()
  {
    return "Hello, my value is " + _value;
  }
}
</example>

<example title="mybean.php">
&lt;?php

  import example.MyBean;

  $bean = new MyBean(123);

  var_dump($bean);
  var_dump($bean->value);
  var_dump($bean->makeMessage());
?>
</example>

<p>The <code>import</code> keyword will also work on PHP classes but it has a
different functionality than for Java classes.  <code>import</code> will try to
autoload PHP classes by including  the file WEB-INF/classes/<i>classname</i>.php
from the application's WEB-INF/classes directory.</p>

</s3>
</s2>

<s2 title="Calling Java Methods">

<p>
PHP syntax is used for invoking methods.
PHP property syntax can be used for invoking getters and setters of Java objects.
</p>

<example>
&lt;?php

  import java.util.Date;

  $a = new Date(123);

  echo $a->getTime();    # calls getTime()
  echo $a->setTime(456); # calls setTime(456)

  echo $a->time;      # calls getTime()
  $a->time = 456;     # calls setTime(456)
?>
</example>

<s3 title="Static members and methods">

<p>Static methods and members are available using PHP syntax if the Java class has been imported.</p>

<example>
&lt;?php

import java.util.Calendar;

$calendar = Calendar::getInstance();

var_dump($calendar);
?>

</example>

<p>An alternative to <code>import</code> is to use <code>java_class()</code> to access static members and methods.</p>

<example>
&lt;?php

  $class = java_class("java.lang.System");

  # System.in
  $in = $class->in;
  
  # System.currentTimeInMillis();
  $time = $class->currentTimeInMillis();

?>
</example>

</s3>

<s3 title="Java method overloading">

<p>Quercus allows overloaded Java methods to be called from within PHP code.
The number of arguments is most important, followed by the argument
types.  Quercus will use the method whose arguments are the most easily
marshaled (i.e. a PHP string easily goes into a Java String whereas a
PHP array is a mismatch for a Java int).</p>

<p>Because the PHP language itself does not support overloading, the
Quercus overloading of Java methods may not be exact.  Therefore, it's
best to keep overloading to a minimum.  Overloading by the number of
arguments will always work, but overloading by types is trickier.</p>


<example title="Example: MyModule.java">
import com.caucho.quercus.module.AbstractQuercusModule;

public class MyModule extends AbstractQuercusModule
{
  public static void foo(String a, boolean b)
  {
  }

  public static void foo(String a, String b)
  {
  }
}
</example>

<example title="example.php">
&lt;?php

  foo('abc', false);

?>
</example>

<p>In the example above, the first Java method <code>public static void foo(String a, boolean b)</code> is called because it requires the least amount of type coercion.</p>

<note>Only Java methods with the same amount of arguments will be considered.</note>

</s3>

</s2>

<s2 name="module" title="Modules: Adding PHP functions">

<p>The core PHP functions are implemented inside Quercus modules.  Quercus modules are the Java equivalent of PHP modules.  </p>

<p>All Quercus modules need to implement AbstractQuercusModule.  Functions defined in your modules are callable from within PHP script by using just the function name.  Function names need to be distinct in order to prevent name collisions, though Quercus does support function overloading (for Java functions only).</p>

<p>A typical Quercus module looks like:</p>

<example title="WEB-INF/classes/example/HelloModule.java">
package example;

import com.caucho.quercus.env.Env;
import com.caucho.quercus.module.AbstractQuercusModule;

public class HelloModule extends AbstractQuercusModule
{
  /**
   * @param env provides Quercus environment resources.
   * @param str
   */
  public void hello_test(Env env, String str)
  {
    // 'echos' the string
    env.println("hello " + str);
  }
}
</example>

<example title="example.php">
&lt;?php

  // PHP 5 is case-insensitive
  // just prints "hello me" to the browser.
  hello_test("me");

?>
</example>

<p>For a tutorial on how to implement your own Quercus module, see the <a href="../examples/quercus-module/index.xtp">Quercus module tutorial</a>.</p>

</s2>

<s2 title="Marshalling: PHP to Java conversions">

<s3 title="PHP types">
<p>For every PHP type, there is a Java type that is used
internally to represent the corresponding PHP value. All of the Java types extend
<code>Value</code>.</p>

<deftable>
<tr>
  <th>PHP type</th>
  <th>Quercus class</th>
</tr>
<tr>
  <td>null</td>
  <td>NullValue</td>
</tr>
<tr>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>string (php6, binary)</td>
  <td>BinaryBuilderValue</td>
</tr>
<tr>
  <td>string (php6, unicode)</td>
  <td>UnicodeBuilderValue</td>
</tr>
<tr>
  <td>bool</td>
  <td>BooleanValue</td>
</tr>
<tr>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>float</td>
  <td>DoubleValue</td>
</tr>
<tr>
  <td>array</td>
  <td>ArrayValue</td>
</tr>
<tr>
  <td>object</td>
  <td>ObjectValue</td>
</tr>
<tr>
  <td>ref/var</td>
  <td>Var</td>
</tr>
</deftable>

</s3>

<s3 title="Java method arguments">

<p>In Quercus, Java methods can be called from within PHP.  Java arguments for
Java methods are marshaled to the correct type from the PHP parameters
that were passed in.</p>

<p>When the Java argument type is declared to be Object, the value will
be marshaled to a Java object.  For example, a PHP int (LongValue) will be
marshaled to an Integer.  The only exceptions are PHP arrays and objects: they
are passed in as-is without marshaling.</p>

<p>When the Java argument type is declared to be a Quercus Value, the PHP value
is passed in directly without marshaling.</p>

<p>If the Java argument type is an object, passing in a PHP <code>NULL</code> will
result in a null Java argument.</p>

<deftable title="Java to PHP conversion">
<tr>
  <th width="50%">Java Type</th>
  <th>PHP Type</th>
  <th>Quercus Type</th>
</tr>
<tr>
  <td>null</td>
  <td>NULL</td>
  <td>NullValue</td>
</tr>
<tr>
  <td>boolean</td>
  <td>bool</td>
  <td>BooleanValue</td>
</tr>
<tr>
  <td>Boolean</td>
  <td>bool</td>
  <td>BooleanValue</td>
</tr>
<tr>
  <td>byte</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>Byte</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>short</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>Short</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>int</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>Integer</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>long</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>Long</td>
  <td>int</td>
  <td>LongValue</td>
</tr>
<tr>
  <td>float</td>
  <td>float</td>
  <td>DoubleValue</td>
</tr>
<tr>
  <td>Float</td>
  <td>float</td>
  <td>DoubleValue</td>
</tr>
<tr>
  <td>double</td>
  <td>float</td>
  <td>DoubleValue</td>
</tr>
<tr>
  <td>Double</td>
  <td>float</td>
  <td>DoubleValue</td>
</tr>
<tr>
  <td>String</td>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>String</td>
  <td>unicode (php6)</td>
  <td>UnicodeBuilderValue</td>
</tr>
<tr>
  <td>char</td>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>char</td>
  <td>unicode (php6)</td>
  <td>UnicodeBuilderValue</td>
</tr>
<tr>
  <td>Character</td>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>Character</td>
  <td>unicode (php6)</td>
  <td>UnicodeBuilderValue</td>
</tr>
<tr>
  <td>char[]</td>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>char[]</td>
  <td>unicode (php6)</td>
  <td>UnicodeBuilderValue</td>
</tr>
<tr>
  <td>byte[]</td>
  <td>string (php5)</td>
  <td>StringBuilderValue</td>
</tr>
<tr>
  <td>byte[]</td>
  <td>string (php6)</td>
  <td>BinaryBuilderValue</td>
</tr>
<tr>
  <td>Object[] (any other array)</td>
  <td>array</td>
  <td>ArrayValue</td>
</tr>
<tr>
  <td>Calendar</td>
  <td>effectively int (getTimeInMillis())</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>Date</td>
  <td>effectively int (getTime())</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>URL</td>
  <td>effectively string (toString())</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>Collection</td>
  <td>array</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>List</td>
  <td>array</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>Map</td>
  <td>array</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>other Java Objects</td>
  <td>object</td>
  <td>JavaValue</td>
</tr>
<tr>
  <td>Value</td>
  <td>any</td>
  <td>Value</td>
</tr>
</deftable>

<p>Java objects like Calendar and Map are placed inside JavaValues and then
returned to the PHP environment.  A JavaValue is a wrapper that exposes
the object's Java methods to PHP.  For example, if <code>$url</code> is holding
a Java URL object, then we can use <code>$url->getHost()</code> to call the
URL's <code>getHost()</code> method.</p>

<p>Some Java objects may have an effective PHP value.  Take for instance, Date.
A Date object is, for practical purposes, a PHP int with it's value pegged to
Date.getTime().</p>

<p>Collection, List, and Map behave just like PHP arrays.  Suppose
<code>$map</code> holds a Java HashMap, then it's certainly valid to do
<code>$map["foo"] = "bar"</code>.  However, there are some limitations that
are dependent on the underlying Java type.  For example,
<code>$list[-1] = 5</code> will not be possible for a Java List because List
indexes start at 0.</p>

</s3>
</s2> <!-- marshal -->

<s2 title="HttpServletRequest and HttpSession">

<p>
QuercusServlet automatically creates the <code>$request</code> variable for PHP
scripts.  It contains the <a href="javadoc|javax.servlet.http.HttpServletRequest"/>
object.
</p>

<p>
PHP sessions are not shared with servlet sessions.  The <code>$request</code>
variable can be used to obtain the servlet session if required.
</p>

<example title="$request->getSession(true) HttpSession">
&lt;?php