h1. Phpjao

part of [[Platform]]

h2. Introduction

PHPJAO is lightweight orb, which 

* provide API for remote calls from PHP to Java services, using json as transport.
* for POJO classes build appropriative PHP classes with same fields, to simplify using Java API from PHP.    

h2. Usage:

h3. Call of phpjao via ant file

In project attributes you must have phpjao namespace definifion.
<pre>
 xmlns:phpjao="antlib:ua.gradsoft.phpjao"
</pre>


Load phpjao and depended libraries into ant:

<pre>
 <target name="declare-phpjao"  depends="download-build-libs">
   <path id="phpjao.lib.path">
    <pathelement location="lib/jungle.tools.phpjao-1.2.0.jar" />
    <pathelement location="lib/termware-2.3.3.jar" />
    <pathelement location="lib/termwarePhp-1.0.6.jar" />
    <pathelement location="lib/JavaChecker-2.5.2.jar" />
    <pathelement location="lib/JavaChecker2Annotation-2.5.2.jar" />
    <pathelement location="lib/termwareJPP-1.1.jar" />
   </path>
   <taskdef resource="ua/gradsoft/phpjao/antlib.xml"
            uri="antlib:ua.gradsoft.phpjao" 
            classpathref="phpjao.lib.path"/>
 </target>
</pre>

(Note that versions of depended libraries can changes in future, look at ivy.xml descriptor for details)

And for generation php mapping, use task phpjao:generate.
Example:
<pre>
  <target name="generate-php" depends="declare-phpjao" >
        <phpjao:generate  outputFile="${basedir}/php/generated.php" >
          <includedirs dir="${basedir}/jsrc" />
          <includejars path="${basedir}/lib/javaee-api-${javaee-api.version}.jar" />
          <class name="ua.gradsoft.t1.E1" />
        </phpjao:generate>
    </target>
</pre>

This task has next attributes:
* outputFile - file, where generated php classes and framework procedures will be implemented.
* phpHeader - name of PHPJAO header (default - PHPJAO.php)
* withoutRequireHeader - not insert 'require_once(phpHeader)' statement to generated files
and next nested elements:
* includedirs - ant dirset, which specify where java sources are situated.
* includejars - path, which specify where situated classes in non-source form.
* class - name of class to generate.

h3. Using of generated PHP classes

* Place PHPJAO.php from phpjao distribution to directory, which is listed in  php_inc_dir of you php distribution.
* Use generated PHP file as you want ;)


h2. Mapping

h3. Mapping of primitive types

* boolean -> boolean
* String -> string
* int, Integer    -> integer
* long, Long   -> integer
* short, Short -> short


h3. Mapping of Objects

All objects can be mapped in two forms
* as entity (where on PHP side we have value object, methods are ignored)
* as service (where on PHP side we have proxy which call remote service)

h4. Mapping of Entity Objects

Entity objects are objects with Entity annotations. Generated PHP class have 
* same simple name 
* access for object 'PHPJAOClassDescription', which holds type information for object and all members 
* For each non-transient public property of such object we generate public member variable with the same name

java:
<pre>
package com.org.proj;
import ...

@Entity
public class X implements Serializable
{
  @Id
  public String getName() { ... }
  public void   setName(String name) { ... }
  
  public String getValue() { .. }
  public void   setValue(String name) { ... }

  ....
}
</pre>

 will be mapped to
<pre>
<?php

class XPHPJAOClassDescription extends PHPJAOClassDescription
{
  public function __construct()
  {
   $this->javaClass='com.org.proj.X';
   $this->phpClass='X';
   $this->typesOfFields=array('name'=>'java.lang.String', 'value'=>'java.lang.String');
  }
}

class X extends PHPJAOPOJOBase
{
 public $name;
 public $value;
 public function getPHPJAOClassDescription() 
 { ... }
}
PHPJAO::registerType('com.org.proj.X', ...);
?>
</pre>

in addition, to register mapping in marshalling engine, static methof PHPJAO::registerType(javaClass,phpClass) must be called before using automatically generated type.

h5. Custom Mapping of special objects.

* Java Date class mapped to PHP DateTime. 
* Java BigDecimal mapped to custom BigDecimal class with string value. (note, that usage of BigDecimal require custom jabsorb version with out BigDecimal transformer
 and fix of http://issues.jabsorb.org/show_bug.cgi?id=58
* Java Class class mapped to special PHP class, which hold one public member: name.

It is possible to define own custom JSON mapping for class X, by 
* providing class with name XPHPJAOJSONHelper, which implements JSONHelper interface and provide two static methods:
<pre>
 function toJson($o)
 function  fromJson($o)
</pre>
* call of PHPJAO::registerCustomType(X, XPHPJAOJSONHelper)  can be called (in addition to PHPJAO::registerType)


h4. Mapping of Service Obejcts

 Service objects 

Let method functions of object can be exported if
* visibility of function is public.
* all arguments and return values of such method are known entity objects, primitive types or collections of one

All such service objects are mapped to PHPJAORemoteProxy class, whith
1. static factory method PHPJAO::createRemoteProxy() with URL to remote proxy as endpoint and (optionally) name of type
2. methods for set and get requies uri
3. overloded method __call, which for all functions which can be exported - 

I. e. let we have class

<pre>
package com.org.proj;
....

public class YService()
{

  public X findX(Long id) 
   { ... }

  public List<X> queryX(String expr, Map<String,String> options)
   { ... }

  public void updateX(X x) 
   { ... }

}
</pre>

then we can call 
<pre>

$yService = PHPJAO::createRemoteProxy($uri,$objname)

$x1 = $yService->findX(3);
$x2 = new X;
$x2->name="A";
$x2->value="V";
$yServive->updateX($x2);

</pre>

We can supply array or url-s for service endpoint, instead one for fault tolerance and load balance.
i. e. next code block:
<pre>
$yService = PHPJAO::createRemoteProxy(array($uri1,$uri2),$objname)
$x1 = $yService->findX(3);
</pre>
yService will be called by address, randomly selected from uri1 or uri2.  If endpoint will bot be available, than PHPJAO will try switch to other uri and retry call. 

h4. Mapping of Inheritance:

All interfaces specifications are ignored.  

Specification of extends clause are mapped to PHP extends clause for entities, is superclass is also entity class and passed to phpjao in list of entity classes, otherwise, extends specifications also ignored.

h3. Mapping of Collections

 ArrayList and HashMap-s are mapped as PHP arrays.  

h2. License and download.
 
* GPL
* http://datacenter.gradsoft.ua/public.repository/ua.gradsoft/jungle.tools.phpjao/  (distributive, may be not last)
* http://redmine.gradsoft.ua/repositories/browse/jungleplatform/platform/tools/phpjao (svn browse)