📄 burlap-draft-spec.xtp
字号:
<document> <header> <product>resin-ee</product> <resin-2.0>$ee/ejb-ref/burlap-draft-spec.xtp</resin-2.0> <title>Burlap Draft Spec</title> <date>March 15, 2002</date> </header> <body> <summary/><s1 title="Design Goals"><p>The Burlap protocol was created to solve a specific problem:</p><blockquote>AllowJava Enterprise Java Beans (EJB) services to interoperate with non-Javaservers and clients using an XML-based protocol.</blockquote><p>The <a href="http://www.caucho.com/burlap">Burlap home page</a>contains the latest information about Burlap.</p><p>The name "Burlap" was chosed for a simple reason: it's boring.The wire protocol for web services should be invisibleto application writers. Wire protocols should not requireexternal schema or IDL.</p><p>Given the EJB environment, the Burlap protocol has thefollowing requirements:</p><ul><li>It must use the simplest possible subset of XML.</li><li>It must not require external IDL or schema definitions; it should beinvisible to application writers.</li><li>It must have sufficient power to serialize Java.</li><li>It must have sufficient power to support EJB.</li><li>It must allow non-Java clients to use web services.</li><li>It must allow web services to deployed as a Servlet.</li><li>It must be simple so it can be effectively tested.</li><li>It must be as fast as possible.</li><li>It should support transaction contexts.</li></ul><p>The <a href="burlap-notes.xtp">design notes</a> explain someof the design decision in creating the Burlap protocol.</p><p>The leading XML-based RPC protocols do not meet theserequirements. UserLand's <a href="http://www.xmlrpc.com">XML-RPC</a>is insufficiently powerful tosupport Java serialization or EJB. Microsoft's<a href="http://www.w3.org/TR/SOAP">SOAP</a> is overlycomplicated and underdefined. In particular, it requires XMLnamespaces, attributes, overly complicated typing, and external schema.</p></s1><s1 title="SML"><p>Burlap uses SML (Simple Markup Language), a restricted subset of XML:</p><ul><li>Only elements and character data are allowed.</li><li>No namespaces, no attributes, no processing instructions, nocomments, no DTDs, no CDATA sections.</li><li>No mixed content: an element may contain eitherelements or character data, but not both.</li><li>Only UTF-8 encoding is allowed.</li><li>Only numbered character entities, e.g. &#60;, and the standardXML entities (&lt;, &gt;, and &amp;) are allowed asescapes.</li><li>All whitespace in character data is significant.</li></ul><p>The smallness of SML allows less room for bugs, simplifiestesting, and makes reasonably-fast implementations feasible.It forces conformance by eliminating ambiguities.</p><p>The SML grammar needs only six productions:</p><def><var>tag-list</var> ::= (<var>S</var> <var>tag</var>)* <var>S</var><var>tag</var> ::= <<var>name</var>> <var>tag-list</var> </<var>name</var>> ::= <<var>name</var>> <var>cdata</var> </<var>name</var>><var>S</var> ::= (' ' | '\t' | '\r' | '\n')*<var>cdata</var> ::= ([^<&] | &# [0-9]+ ; | &lt; | &gt; | &amp;)*<var>name</var> ::= [a-zA-Z:_] [a-zA-Z0-9.-_:]*</def><note>SML explicitly forbids XML short tags, e.g. <tag/>,and the XML header, e.g. <?xml version='1.0'?></note></s1><s1 title="Serialization"><p>Burlap's object serialization has 9 primitive types:</p><ol><li><var>boolean</var></li><li>32-bit <var>int</var></li><li>64-bit <var>long</var></li><li>64-bit <var>double</var></li><li>ISO-8609 <var>date</var></li><li>16-bit UTF8-encoded <var>string</var></li><li>16-bit UTF8-encoded <var>xml</var></li><li><var>base64</var> binary data</li><li><var>remote</var> objects</li></ol><p>It has 2 combining constructs:</p><ol><li><var>list</var> for lists and arrays</li><li><var>map</var> for objects and hash tables.</li></ol><p>Finally, it has 2 special contructs:</p><ol><li><var>null</var> for null values</li><li><var>ref</var> for shared and circular object references.</li></ol><s2 title="null" type="defun"><p>Null represents a null pointer.The XML short form is forbidden, i.e. <null> must haveseparate open and close tags.</p><p><null> values are allowed in place of any <string>, <xml>,<base64>, <list>, <map>, or <remote>.</p><results> <null></null></results></s2><s2 title="boolean" type="defun"><p>A boolean value expressed as an integer, 0 or 1.</p><results> <boolean>0</boolean></results></s2><s2 title="int" type="defun"><p>A 32-bit signed integer.</p><results><int>-32132</int></results></s2><s2 title="long" type="defun"><p>A 64-bit signed integer.</p><results><long>1000000000</long></results></s2><s2 title="double" type="defun"><p>A 64-bit IEEE floating pointer number.</p><results><double>1234.9431e12</double></results></s2><s2 title="string" type="defun"><p>A 16-bit unicode character string encoded in UTF-8. TheUTF-8 encoding follows from the SML rules. Similarly, the onlyescapes allowed are &#xx;, &lt;, &gt;, and &amp;.All whitespace is significant.</p><results><string>Escape the less than symbol as &lt; orusing the numeric escape &#38;</string></results></s2><s2 title="xml" type="defun"><p>An XML document encoded as a 16-bit unicode characterstring encoded in UTF-8, following the rules for <string>.Special characters, like `<' must be escaped. The only escapes allowedare &#xx;, &lt;, &gt;, and &amp;. All whitespace issignificant.</p><results><xml>&lt;top&gt; &lt;body test='foo'/&gt;&lt;/top&gt;</xml></results><note>Because this document does not define the language mapping,implementations are free to return a string when reading an <xml>entity.</note></s2><s2 title="date" type="defun"><p>An ISO8609-encoded date.</p><results><date>19880508T095231Z</date></results></s2><s2 title="base64" type="defun"><p>A base64-encoded binary stream. The base64 string may havewhitespace after any triplet, but not within a triplet.</p><results> <base64>zxc9Z9m2z8==</base64></results></s2><s2 title="list" type="defun"><p>An ordered list, like an array. The <type>element describes the type of the list and the <length> elementspecifies the number of values in the list. Both <type> and<length> tags are required, but both may be empty. If the <length>is empty, the receiver will determine the list length from theactual number of elements before the </list>.</p><def>list = (type, length, (%object;)*)</def><p>Each <list> item is added to the reference list. See the<ref> element.</p><p>A <list> might also be represented by a <null> or <ref>.Parsers must be prepared to recognize any of those three.</p><results title="serialization of a Java int[]"><list> <type>[int</type> <length>3</length> <int>0</int> <int>1</int> <int>2</int></list></results><results title="serialization of a Java ArrayList"><list> <type></type> <length>3</length> <int>0</int> <double>1.3</double> <string>foobar</string></list></results><note>The valid values of <type> are not specified in thisdocument and may depend on the specific application. For example, aJava EJB server which exposes an Burlap interface can use the <type>information to instantiate the specific array type.On the other hand, a Perl server would likely ignore the contents of <type>entirely and create a generic array.</note></s2><s2 title="map" type="defun"><p>Represents serialized objects and Hashtables. The <type>element describes the type of the map. Objects are represented by amap from field names to their values and <type> is the classof the object itself.</p><def>map ::= (type, ((%object;), (%object;))*)</def><p>The <type> element is mandatory, although its value may beempty. For objects, unrecognized keys must be ignored.</p><p>Each <map> is added to the reference list. A <map> mightalso be represented as <null> or <ref>.</p><example title="Serialization of a Java Object">public class Car implements Serializable { String model = "Beetle"; String color = "aquamarine"; int mileage = 230431;}</example><results><map> <type>com.caucho.test.Car</type> <string>model<string> <string>Beetle</string> <string>color<string> <string>aquamarine</string> <string>mileage<string> <int>230431</int></map></results><example title="A sparse array">map = new HashMap();map.put(new Integer(1), "fee");map.put(new Integer(75), "fie");map.put(new Integer(932), "foe");</example><results><map> <type>java.util.HashMap</type> <int>1<int><string>fee</string> <int>75<int><string>fie</string> <int>932<int><string>foe</string></map></results><note>The <type> will depend on the specific protocol. EJB-basedprotocols will use Java classes.</note></s2><s2 title="ref" type="defun"><p>An integer referring to a previous <list> or <map>instance. As each <list> or <map> is read from theinput stream, it is assigned an integer. A later <ref> can then usethe previous object.</p><def>ref ::= #CDATA</def><p><ref> can refer to incompletely-read items. For example, acircular linked-list will refer to the first link before the entire listhas been read.</p><p>A possible implementation would add each <map> and <list> to anarray as its read. The <ref> will return the corresponding object from thearray. To support circular structures, the implementation would storethe <map> or <list> immediately, before filling in the object'scontents.</p><p>Each <list> or <array> is stored into an array as it isparsed. <ref> selects one of the stored objects. The firstobject is numbered '0'.</p><example title="circular list">list = new LinkedList();listhead = 1;list.tail = list;</example><results><map> <type>LinkedList</type> <string>head</string><int>1</int> <string>tail</string><ref>0</ref></map></results><note><ref> only to <list> and <map> elements. <string>and <base64>, in particular, can't share references.</note></s2><s2 title="remote" type="defun"><p>A reference to a remote object. The <type> elementspecifies the object type and the <string> element specifies the remoteobject's URL.</p><def>remote ::= (type, string)</def><p>Remote support is optional. Clients and servers don't needto support <remote> if the service doesn't need it.</p><results title="EJB Session Reference"><remote> <type>test.TestObj</type> <string>http://localhost/ejbhome;ejbid=69Xm8-zW</string></remote></results><note>Needed to support EJB in a reasonably portable way.</note></s2></s1><s1 title="burlap:call"><p>A Burlap call invokes a method on an object with an argumentlist. The object is uniquely named by its URL. The arguments arespecified by Burlap serialization.</p><def>burlap:call ::= (%header;), method, (%object;)*</def><results title="obj.add2(2,3)"><burlap:call> <method>add2</method> <int>2</int> <int>3</int></burlap:call><burlap:reply> <value> <int>5</int> </value></burlap:reply></results>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -