Using BasicAPI

The Specification

In this section, we examine some of the high-level details of the Burlap Web Service Protocol specification, including serialization and the <burlap:call> and <burlap:reply> tags. For a full discussion of the specification, visit www.caucho.com/burlap/burlap-draft-spec.xtp.

Serialization

As we mentioned earlier, the primary focus of the Burlap protocol is to transfer information between beans and/or applications. Since this is its most vital function, the task of serialization is very important. The current protocol defines nine serialization "primitives," two constructs to handle array-type data structures, one for null, and one for shared object references:

<boolean>	<data>
<int>	<remote>
<long>	<list>
<double>	<map>
<base64>	<null>
<string>	<ref>
<xml>

Let's examine each of these constructs and the resulting SML produced by the Burlap protocol when serialized.

<boolean>

The Java boolean is represented as the integer value 0 (for false) or 1 (for true). As a result, the Burlap tags are:

 <boolean>0</boolean> <boolean>1</boolean> 

<int>

A 34-bit integer is represented in Burlap using the <int> tag. An integer can be positive, negative, or zero. For example:

 <int>-34394</int> <int>0</int> <int>38943</int> 

<long>

The <long> Burlap tag is used to represent all 64-bit integers. For example:

 <long>2134445432</long> <long>0</long> <long>-2198748944</long> 

<double>

The <double> tag represents 64-bit floating-point numbers. The floating-point number can be represented using formal IEEE notation. For example:

 <double>2344.398e9</double> <double>0.0</double> <double>-3.1415924</double> 

<date>

All dates passed using Burlap are converted to an ISO8609-encoded date. For example:

 <date>20020709TO93848Z</date> 

<string>

Strings passed in Burlap are encoded in UTF-8. Some escapes are allowed, including &lt, &gt, &amp and all &#xx values. All spaces in the string are also preserved.

 <string>This is a string</string <string>This string has escapes in it - 5 &lt; 9</string> <string>How about another escape &#14;</string> 

<xml>

The <xml> tag is used to encode an XML document using the same rules as <string>. All special characters are escaped, like the < and > of the XML document's tags. For example:

 <xml>      <accounts>           <account id='99910'>                <name>Steve</name>           </account>           <account id='99920'>                <name>Pam</name>           </account>      </accounts> </xml> 

<base64>

Since binary date will also need to be passed between beans and applications, the Burlap protocol uses base 64 encoding to convert a binary stream to an alphanumeric string. For example:

 <base64> Aje8xc9Z9 </base64> 

<remote>

The Burlap protocol is designed to allow both local and remote object reference. The remote references are particularly important for distributed beans and Web service implementation. Remote objects are distinguished using their type and the URL to the remote object. A remote reference is defined within Burlap as:

 <remote>      <type></type>      <string></string> </remote> 

For example, suppose you have a Web service that exposes an Account object. The Burlap reference is:

 <remote>      <type>act.account</type>      <string>http://www.mycompany.com/accounting</string> </remote> 

<list>

Other than the <remote> tag used for remote object references, all of the data structures have been primitive in nature. Burlap has the ability to represent two complex data structures: the list and the map.

A list is basically an array of a particular data type. It is represented by several characteristics:

• Type —The type of list.

• Length —The total number of elements in the list.

• Objects —The actual elements contained in the list.

For example, we might have an array of doubles:

 <list>       <type>double</type>      <length>4</length>      <double>3.455</double>      <double>1.3244e3</double>      <double>34.344</double>      <double>9393.44</double> </list> <ref> 

<map>

The <map> tag is used to represent Hashtables and general serialized objects. An object or map is characterized by:

• <type> —The map type or object.

• objects —The elements that make up the map or object.

For example, you can create a HashMap() object and map account types to local application values:

 HashMap acctMap - new HashMap(); acctMap.put(new Integer(455), "checking"); acctMap.put(new Integer(643), "savings"); 

You can pass the HashMap object to a client using the <map> tag:

 <map>      <type>java.util.HashMap</type>      <int>455</int><string>checking</string>      <int>643</int><string>savings</string> </map> 

You might also have a class for an account that needs to be passed to a client. You can define the class:

 public class Account implements Serializable {      String name; int accountType; } Account newAccount = new Account("James", 643); 

Notice that the class must implement the Serializable interface in order for Burlap to convert it to the following <map> tag:

 <map>      <type>Account</type>      <string>name</string><string>James</string>      <type>accountType</type><int>643</int> </map> 

<null>

The <null> tag is used to represent an object with no value or null pointer. Since SML doesn't allow the </null> tag, the null is represented as:

 <null></null> 

The <null> tag can be used to replace other burlap tags, including <string>, <xml>, <base64>, <list>, <map>, and <remote> as appropriate.

<ref>

When lists and maps are passed between the client and server, there might be references to the list or map in <tags> that come later. These references are typically circular, meaning that one of them will refer to the previously defined object itself. All references must be matched to the proper list or map sent between the systems. For example:

 SpecialMap sm = new SpecialMap(); s.first = 5; s.last = sm; 

Here, the list attribute of the SpecialMap object sm is a reference back to itself. This object might be translated into the following map:

 <map>      <type>SpecialMap</type>      <string>first</string><int>5</int>      <string>last</string><ref>sm</ref> </map> 

The <burlap:call> Tag

Since the Burlap protocol is designed to handle remote invocations in bean or Web services arenas, it includes a way to invoke a method on a remote object: the <burlap:call> tag. As you saw with the <remote> tag, an object is defined by its URL, and all parameters to a method call on the object are serialized using the <burlap:call> tag. For example, suppose one of the methods of your Account object is called deposit(double). A call to this object is serialized by Burlap using the following:

 <burlap:call>      <method>deposit</method>      <double>50.0</double> </burlap:call> 

Notice there is nothing in the <burlap:call> tag to specify the object on which the method should be invoked. This is handled by the code using Burlap, as you will see shortly.

The <burlap:reply> Tag

Of course, if you are able to make calls to a remote object, you need to be prepared for a response. There are basically two reponses Burlap is able to handle. The first is returning the object defined in the remote method's signature. The deposit(double) method returns a double indicating the new balance. The reply from the previous call is:

 <burlap:reply>           <double>4353.40</double> </burlap:reply> 

If the remote method fails, the system returns an error by way of the <fault> tag. The format of the <fault> tag is:

 <burlap:reply>   <fault>     <string>code</string>     <string>[code type]</string>     <string>message</string>     <string>[what failed]</string>     <string>detail</string>     <map>       <type>[java exception]</type>     </map>   </value> </burlap:reply>