burlap-draft-spec.xtp

RESIN 3.2 最新源码

<s2 title="Object Naming">

<p>The URL uniquely identifies the Burlap object.  This spec does
not mandate any particular URL naming convention.</p>

</s2>

<s2 title="EJB naming (non-normative)">

<p>As an example, the following format is used for EJB:</p>

<def>
http://hostname/ejb<var>/ejb-name</var>;ejbid=<var>object-id</var>
</def>

<p><var>http://hostname/ejb</var> identifies the EJB container.  In
Resin-EJB, this will refer to the EJB Servlet.  HTTP is used as an
example; Burlap does not require the use of HTTP.</p>

<p><var>/ejb-name</var>, the path info of the request, identifies the EJB home.
EJB containers can contain several entity and session beans, each with its
own EJB home.  The <var>ejb-name</var> corresponds to the ejb-name in the
deployment descriptor.

</p><p><var>object-id</var> identifies the specific object.  For entity beans, the
object-id encodes the primary key.  For session beans, the object-id encodes
a unique session identifier.  Home interfaces have no ";ejbid=..." portion.</p>

<example title="Example Entity Home Identifier">
http://localhost/ejb/houses
</example>

<example title="Example Session Bean Identifier">
http://localhost/ejb/session;ejbid=M9Zs1Zm
</example>

</s2>

<s2 title="Methods and Overloading">

<p>Method names must be unique.  Overloading is permitted by
encoding the argument types in the method names.  The types of
the actual arguments must not be used to select the methods.</p>

<p>Method names beginning with <var>_burlap_</var> are reserved.</p>

<p>Servers should accept calls with either the mangled method name
or the unmangled method name.  Clients should send the mangled method name.</p>

<note>See the Java binding for a possible overloading scheme.</note>

<example>add(int a, int b)</example>
<results>add_int_int</results>
<example>add(double a, double b)</example>
<results>add_double_double</results>
<example>add(shopping.Cart cart, shopping.Item item)</example>
<results>add_shopping.Cart_shopping.Item</results>

</s2>

<s2 title="Arguments">

<p>Arguments immediately follow the method in positional order.  Argument
values use Burlap's serialization.</p>

<results title="remote.add(2, 3)">
&lt;burlap:call&gt;
  &lt;method&gt;add&lt;method&gt;
  &lt;int&gt;2&lt;/int&gt;
  &lt;int&gt;3&lt;/int&gt;
&lt;/burlap:call&gt;
</results>

<p>All arguments share references, i.e. the reference list
starts with the first argument and continues for all other arguments.
This lets two arguments share values.</p>

<example title="remote.eq(bean, bean)">
bean = new Bean("foo", 13);

System.out.println(remote.eq(bean, bean));
</example>
<results>
&lt;burlap:call&gt;
  &lt;method&gt;eq&lt;method&gt;
  &lt;map&gt;
    &lt;type&gt;Bean&lt;/type&gt;
    &lt;string&gt;foo&lt;/string&gt;
    &lt;int&gt;13&lt;/int&gt;
  &lt;/map&gt;
  &lt;ref&gt;0&lt;/ref&gt;
&lt;/burlap:call&gt;
</results>

<p>The number and type of arguments are fixed by the remote method.
Variable length arguments are forbidden.  In other words, implementations
may take advantage of the expected type to improve performance.</p>

</s2>

<s2 title="Headers">

<p>Headers are key, value pairs introduced by a &lt;header&gt; tag.</p>

<p>The value of the header can be any serialized object.  The reference
array is reset for each header.  So a header can't point to an object
in another header.

</p><p>For example, a request might include a transaction context in a
header.  The client could require that the server understand the
transaction context or fail.</p>

<results title="Call with Distributed Transaction Context">
&lt;burlap:call&gt;
  &lt;header&gt;transaction&lt;header&gt;
  &lt;remote&gt;http://hostname/xa;ejbid=01b8e19a77&lt;/remote&gt;

  &lt;method&gt;debit&lt;method&gt;
  &lt;int&gt;12300&lt;/int&gt;
&lt;/burlap:call&gt;
</results>

</s2>

<s2 title="Versioning">

<p>Burlap requests and responses have no explicit version id.  This
is deliberate.  There are several different changes that get
lumped into a 'version', but each needs different handling.  In each
case, appropriate mechanisms already exist without adding a version.</p>

<ol>
<li>If the Burlap meta-protocol itself changes, the new protocol will
use a new top-level tag &lt;burlap-2:call&gt;.  In other words the
top element, burlap:call, signifies version 1.0.
</li><li>If clients can take advantage of a new server capabilities, it
should use &lt;header&gt; version.
</li></ol>

<results title="Requiring Version 2 of a Protocol">
&lt;burlap:call&gt;
  &lt;method&gt;debit&lt;method&gt;
  &lt;int&gt;12300&lt;/int&gt;
&lt;/burlap:call&gt;
</results>

</s2>

</s1>

<s1 title="burlap:reply">

<p>Burlap calls return either a &lt;fault&gt; or an object.</p>

<s2 title="Value">
  
<p>A successful reply returns a single &lt;value&gt; and possibly
some header information.  </p>
  
<results>
&lt;burlap:reply&gt;
  &lt;value&gt;
    &lt;int&gt;5&lt;/int&gt;
  &lt;/value&gt;
&lt;/burlap:reply&gt;
</results>

</s2>

<s2 title="Faults">
<p>Failed calls return a &lt;fault&gt;.

</p><p>Each fault has a number of informative fields, expressed like
&lt;map&gt; entries.  The defined fields are <var>code</var>, <var>message</var>,
and <var>detail</var>. <var>code</var> is one of a short list of strings
defined below.  <var>message</var> is a user-readable message.
<var>detail</var> is an object representing the exception.  In Java,
<var>detail</var> will be a serialized exception.</p>

<results title="Remote Call throws FileNotFoundException">
&lt;burlap:reply&gt;
  &lt;fault&gt;
    &lt;string&gt;code&lt;/string&gt;
    &lt;string&gt;ServiceException&lt;/string&gt;

    &lt;string&gt;message&lt;/string&gt;
    &lt;string&gt;File Not Found&lt;/string&gt;

    &lt;string&gt;detail&lt;/string&gt;
    &lt;map&gt;
      &lt;type&gt;java.io.FileNotFoundException&lt;/type&gt;
    &lt;/map&gt;

  &lt;/value&gt;
&lt;/burlap:reply&gt;
</results>

<deftable>
<tr><td>ProtocolException</td><td>The Burlap request has some sort of
syntactic error.
</td></tr><tr><td>NoSuchObjectException</td><td>The requested object does not exist.
</td></tr><tr><td>NoSuchMethodException</td><td>The requested method does not exist.
</td></tr><tr><td>ServiceException</td><td>The called method threw an exception.
</td></tr></deftable>

</s2>

</s1>

<s1 title="Metadata (non-normative)">

<p>Metadata is handled by special method calls, methods beginning
with <var>_burlap_</var>.</p>

<p><var>_burlap_getAttribute(String&#160;key)</var> returns a string.
The following attributes are predefined by this spec:</p>

<deftable>
<tr><th>attribute</th><th>meaning
</th></tr><tr><td>home-class</td><td>Java class for the home interface.
</td></tr><tr><td>remote-class</td><td>Java class for the object interface.
</td></tr><tr><td>primary-key-class</td><td>Java class for the primary key.
</td></tr></deftable>

</s1>

<s1 title="Micro Burlap">

<p>A "Micro Burlap" implementation may omit support for the "double" type.
</p>

</s1>

<s1 title="Formal Definitions">

<s2 title="SML grammar">
<def>
<var>tag-list</var> ::= (<var>S</var> <var>tag</var>)* <var>S</var>

<var>tag</var>      ::= &lt;<var>name</var>&gt; <var>tag-list</var> &lt;/<var>name</var>&gt;
         ::= &lt;<var>name</var>&gt; <var>cdata</var> &lt;/<var>name</var>&gt;

<var>S</var>        ::= (' ' | '\t' | '\r' | '\n')*

<var>cdata</var>    ::= ([^&lt;&amp;] | &amp;# [0-9]+ ; | &amp;lt; | &amp;gt; | &amp;amp;)*
<var>name</var>     ::= [a-zA-Z:_] [a-zA-Z0-9.-_:]*
</def>

</s2>

<s2 title="burlap:call">

<def>	
&lt;!DOCTYPE burlap:call&gt;

&lt;!ENTITY % object "null | boolean | int | double | string | xml |
                 base64 | date | ref | map | list | remote"&gt;
		      
&lt;!ENTITY % header "(header, (%object;))*"&gt;

&lt;!ELEMENT burlap:call - - ((%header;), method, (%object;)*)&gt;

&lt;!ELEMENT header - - #CDATA&gt;

&lt;!ELEMENT method - - #CDATA&gt;

&lt;!ELEMENT null - - EMPTY&gt;
&lt;!ELEMENT boolean - - #CDATA&gt;
&lt;!ELEMENT int - - #CDATA&gt;
&lt;!ELEMENT double - - #CDATA&gt;
&lt;!ELEMENT string - - #CDATA&gt;
&lt;!ELEMENT xml - - #CDATA&gt;
&lt;!ELEMENT base64 - - #CDATA&gt;
&lt;!ELEMENT date - - #CDATA&gt;

&lt;!ELEMENT ref - - #CDATA&gt;
&lt;!ELEMENT map - - (type, ((%object;), (%object;))*)&gt;
&lt;!ELEMENT list - - (type, length, (%object;)*)&gt;
&lt;!ELEMENT type - - #CDATA&gt;

&lt;!ELEMENT remote - - (type, string)&gt;
</def>

</s2>

<s2 title="burlap:reply">

<def>	
&lt;!DOCTYPE burlap:reply&gt;

&lt;!ENTITY % object "(null | boolean | int | double | string | xml |
                 base64 | date | ref | map | list | remote)"&gt;
		      
&lt;!ENTITY % header "(header, (%object;))*"&gt;

&lt;!ELEMENT burlap:reply - - ((%header;), (value | fault))&gt;

&lt;!ELEMENT header - - #CDATA&gt;

&lt;!ELEMENT value - - (%object;)&gt;
&lt;!ELEMENT fault - - (string, (%object;))*&gt;

&lt;!ELEMENT null - - EMPTY&gt;
&lt;!ELEMENT boolean - - #CDATA&gt;
&lt;!ELEMENT int - - #CDATA&gt;
&lt;!ELEMENT double - - #CDATA&gt;
&lt;!ELEMENT string - - #CDATA&gt;
&lt;!ELEMENT xml - - #CDATA&gt;
&lt;!ELEMENT base64 - - #CDATA&gt;
&lt;!ELEMENT date - - #CDATA&gt;

&lt;!ELEMENT ref - - #CDATA&gt;
&lt;!ELEMENT map - - (type, ((%object;), (%object;))*)&gt;
&lt;!ELEMENT list - - (type, length, (%object;)*)&gt;
&lt;!ELEMENT type - - #CDATA&gt;

&lt;!ELEMENT remote - - (type, string)&gt;
</def>

</s2>
</s1>

<s1 title="Copyright and Licensing">

<p>© Copyright 2000-2002 Caucho Technology, Inc. All Rights Reserved.

</p><p>Any party may implement this protocol for any purpose without royalty
or license fee, provided that the implementation conforms to this
specification.   Caucho Technology reserves the right to create a
test suite, freely available without royalty or license fee, to
validate implementation conformance.  The limited permissions granted
herein are perpetual and may not be revoked by Caucho Technology or
its successors or assigns.

</p><p>This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and these paragraphs are
included on all such copies and derivative works.

</p><p>This document and the information contained herein is provided on an
"AS IS" basis and CAUCHO TECHNOLOGY DISCLAIMS ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

</p></s1>

<s1 title="Changes">

<s2 title="Since draft v8">

<ul>
<li>Removed &lt;burlap:envelope&gt; and &lt;burlap:message&gt;.
</li></ul>

</s2>

<s2 title="Since draft v7">

<ul>
<li>Removed &lt;require&gt; header.
</li></ul>

</s2>

<s2 title="Since draft v6">

<ul>
<li>Added &lt;burlap:envelope&gt; and &lt;burlap:message&gt;
</li></ul>

</s2>

<s2 title="Since draft v5">

<ul>
<li>Added &lt;xml&gt;
</li><li>Clarified license.
</li><li>Allowed variable length arrays.
</li></ul>

</s2>

<s2 title="Since draft v4">

<ul>
<li>&lt;require&gt; must preceed &lt;header&gt; in headers.
</li><li>&lt;remote&gt; requires a &lt;type&gt; and &lt;string&gt; value.
</li></ul>

</s2>

<s2 title="Since draft v3">

<ul>
<li>Changed name of protocol from SML-RPC to "Burlap"
</li><li>Added and rewrote verbiage.
</li><li>base64 may have whitespace between triplets.
</li></ul>

</s2>

<s2 title="Since draft v2">

<ul>
<li>Added Standard XML entities ('&amp;lt;', '&amp;gt;', '&amp;amp;').
</li></ul>

</s2>

<s2 title="Since draft v1">

<ul>
<li>&lt;remote&gt; now takes a single string content, the url.
</li></ul>

</s2>
</s1>
  </body>
</document>