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.

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.