protocol.apt

src版Buffalo最新框架

 -----
 Protocol
 -----
 
Buffalo Protocol
  
  Before buffalo 2.0, buffalo is using the burlap protocol from caucho. From 2.0 version, buffalo have a new protocol 
  definition and implementation which is proper for web and faster. Buffalo is using this xml based lightweight 
  protocol to serialize java object. The javascript client will deserialize  the xml to javascript objects. 
  When making a remote call, buffalo client will serialize the remote call to xml, and 
  the java side will deserialize it. This document will cover the protocol specification. 
  
* Overview of the protocol

  Buffalo protocol is utf-8 protocol. The xml encoding support utf-8 only, otherwise an ProtocolExcption will be thrown
  during parsing. 

*----------------+-----------------+-----------------------+------------------------------+
| <<Tag>>        | <<Description>> | <<Mapped Java Class>> | <<Mapped Javascript Class>>
*----------------+-----------------+-----------------------+------------------------------+
| boolean        | the boolean value, 1 means true and 0 means false | java.lang.Boolean , boolean.class | boolean 
*----------------+-----------------+-----------------------+------------------------------+
| date           | date, ISO8609 format, for example 20061011T230201Z means Oct 11 2006, 23:02:01| java.util.Date        | Date
*----------------+-----------------+-----------------------+------------------------------+
| int            | int value       | java.lang.Integer, java.lang.Short, java.lang.Byte and their primitive types | int
*----------------+-----------------+-----------------------+------------------------------+
| long           | long value      | java.lang.Long and its primitive type | int
*----------------+-----------------+-----------------------+------------------------------+
| null           | null value      | null                  | null or undefined
*----------------+-----------------+-----------------------+------------------------------+
| string         | string          | java.lang.String, java.lang.Character, char.class | String
*----------------+-----------------+-----------------------+------------------------------+
| type           | indicate the type of the list or map | N/A | N/A
*----------------+-----------------+-----------------------+------------------------------+
| length           | indicate the length of the list | N/A | N/A
*----------------+-----------------+-----------------------+------------------------------+
| list           | list or array data structure | java.util.Collection capatible or Array | Array
*----------------+-----------------+-----------------------+------------------------------+
| map            | map or object data structure | java.util.Map assignable or java bean | object
*----------------+-----------------+-----------------------+------------------------------+
| double         | double          | java.lang.Double, java.lang.Float and their primitive types | float
*----------------+-----------------+-----------------------+------------------------------+
| ref            | reference of an object | N/A | N/A
*----------------+-----------------+-----------------------+------------------------------+
| fault          | exception | will NOT convert from client side as throw an exception from client side make no sense | Buffalo.Fault
*----------------+-----------------+-----------------------+------------------------------+
| buffalo-call   | the root element of client remote call | N/A | N/A
*----------------+-----------------+-----------------------+------------------------------+
| method         | the method client want to call | N/A | N/A
*----------------+-----------------+-----------------------+------------------------------+
| buffalo-reply  | the root element of the server reply | N/A | N/A 
*----------------+-----------------+-----------------------+------------------------------+

  A sample request from client to server is: 
 
+---------------------------+
<buffalo-call>
  <method>sum</method>
  <double>1</double>
  <double>2</double>
</buffalo-call>
+---------------------------+

  and the response: 
  
+------------------------------+
<buffalo-reply>
  <double>3.0</double>
</buffalo-call>
+------------------------------+

* list

  Array or java.util.Collection assignable value will be convert to list. 
  
+-----------------------------------+
List list = new ArrayList();
list.add("String#1");
list.add("String#2");
+-----------------------------------+

  will serialize to 
  
+-----------------------------------+
<list>
  <type>java.util.ArrayList</type>
  <length>2</length>
  <string>String#1</string>
  <string>String#2</string>
</list>
+-----------------------------------+
  
  For array: 
  
+-----------------------------------+
String[] strings = new String[]{"String#1", "String#2"}
+-----------------------------------+

  will serialize to 
  
+------------------------------------+
<list>
  <type>[java.lang.String</type>
  <length>2</length>
  <string>String#1</string>
  <string>String#2</string>
</list>
+------------------------------------+

* map
  
  map indicate a map-liked data structure. the java.util.Map assignable value or POJO will use this tag. 
  
+------------------------------------+
Map map = new HashMap()
map.put("key1", "value1");
map.put(new Integer(1), new Double(2.0));
+------------------------------------+

  will serialize to 

+-------------------------------------+
<map>
  <type>java.util.HashMap</type>
  <string>key1</string>
  <string>value1</string>
  <int>1</int>
  <double>2.0</double>
</map>
+--------------------------------------+

  For POJO

+-------------------------------------+
package domain;
class User {
  String name;
  int age;
  boolean gendor;
  
  //getters & setters... 
}

User u = new User("John Smith", 30, true);
+-------------------------------------+

  Will convert to 
  
+-------------------------------------+
<map>
  <type>domain.user</type>
  <string>name</string>
  <string>John Smith</string>
  <string>age</string>
  <int>age</int>
  <string>gendor</string>
  <boolean>1</boolean>
</map>
+-------------------------------------+

* ref

  <ref> means a reference to another object. This tag is really useful dealling with the circular reference, otherwise 
  a StackOverflowException could be easily thrown. Let's have an example. 
    
+-----------------------+
class People...
  
  People getFriend() ...
  // Other fields ommited
  
People john = new People("John");
People michael = new People("Michael");

john.setFriend(michael);
michael.setFriend(josh);

List friends = new ArrayList();
friends.add(john);
friends.add(smith);
+------------------------+

  The result of serializing <friends> is like this: 
  
+------------------------+
<list>
  <type>java.util.ArrayList</type>
  <length>2</length>
  <map>
    <type>domain.People</type>
    <string>friend</string>
    <map>
      <type>domain.People</type>
      <string>friend</friend>
      <ref>1</ref>
    </map>
  </map>
</list>
+------------------------+
  
  ref=1 means that will reference object #1 as its value. each <list>, <map> will treat as an object and have a 
  reference id. 
  
* fault

  <fault> will have the infomation when there is an exception when invoking the service method. <fault> is like map but 
  has 3 property only: code, message, detail. code is the exception class name, message is the exception.getMessage(), 
  if applicable, detail will have the exception.getCause().getMessage(). We design this because the web UI will never 
  want to show the stacktrace to the end user. 
  
* Exceptional class types

  There are some types which has difference serializing method. 
  
  * <<java.sql.Date>>: As the <java.sql.Date> override most of the java.util.Date method, this object will 
  be serialized like this:
  
+--------------------+
<map>
  <type>java.sql.Date</type>
  <string>value</string>
  <date>20061018T211400Z</date>
</map>
+---------------------+
  
  * <<java.math.BigDecimal>> and <<java.math.BigInteger>>. These two types has really complicated internal fields that 
  not useful for the web client. So we serialize them like this
  
+----------------------+
<map>
  <type>java.math.BigDecimal</type> <!-- or java.math.BigInteger--> 
  <string>value</string>
  <string>1234567890</string>
</map>
+-----------------------+
  You can use object.value to get the real value of those objects. When deserializing, it will use the 
  constructor BigDecimal(String) or BigInteger(String) to create a new one. 
  
  [Note:] we don't encourage serialize those data types to the web client.