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.

TagDescriptionMapped Java ClassMapped Javascript Class
booleanthe boolean value, 1 means true and 0 means falsejava.lang.Boolean , boolean.classboolean
datedate, ISO8609 format, for example 20061011T230201Z means Oct 11 2006, 23:02:01java.util.DateDate
intint valuejava.lang.Integer, java.lang.Short, java.lang.Byte and their primitive typesint
longlong valuejava.lang.Long and its primitive typeint
nullnull valuenullnull or undefined
stringstringjava.lang.String, java.lang.Character, char.classString
typeindicate the type of the list or mapN/AN/A
lengthindicate the length of the listN/AN/A
listlist or array data structurejava.util.Collection capatible or ArrayArray
mapmap or object data structurejava.util.Map assignable or java beanobject
doubledoublejava.lang.Double, java.lang.Float and their primitive typesfloat
refreference of an objectN/AN/A
faultexceptionwill NOT convert from client side as throw an exception from client side make no senseBuffalo.Fault
buffalo-callthe root element of client remote callN/AN/A
methodthe method client want to callN/AN/A
buffalo-replythe root element of the server replyN/AN/A

A sample request from client to server is:


and the response:



Array or java.util.Collection assignable value will be convert to list.

List list = new ArrayList();

will serialize to


For array:

String[] strings = new String[]{"String#1", "String#2"}

will serialize to



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



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

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

Will convert to

  <string>John Smith</string>


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");


List friends = new ArrayList();

The result of serializing friends is like this:


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 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:
  • 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
      <type>java.math.BigDecimal</type> <!-- or java.math.BigInteger--> 

    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.

    we don't encourage serialize those data types to the web client.