hessian-ws.ietf

RESIN 3.2 最新源码

      </section>
      
      <section title="Envelope">

        <figure anchor="envelope_grammar">
          <preamble>Envelope Grammar</preamble>
          <artwork>
envelope ::= E x02 x00 m b1 b0 &lt;method-string> env-chunk* z

env-chunk ::= int (string value)* binary int (string value)*
          </artwork>
        </figure>

        <t>
          A Hessian envelope wraps a Hessian message, adding headers and 
          footers and possibly compressing or encrypting the wrapped message.  
          The envelope type is identified by a method string, e.g.
          "com.caucho.hessian.io.Deflation" or
          "com.caucho.hessian.security.X509Encryption".
        </t>

        <t>
          Some envelopes may chunk the data, providing multiple header/footer
          chunks.  For example, a signature envelope might chunk a large
          streaming message to reduce the amount of buffering required to 
          validate the signatures.
        </t>

        <section title="Envelope examples">
          <figure anchor="identity_envelope_example">
            <preamble>Identity Envelope</preamble>
            <artwork>
E x02 x00
  m x00 x08 Identity   # "Identity" envelope does nothing to the body
  x90                  # no headers
  B x00 x0a            # binary wrapped body (12 bytes)
    p x02 x00          # wrapped message
    x05 hello          # "hello"
    z                  # end of wrapped message
  x90                  # no footers
  z                    # end of envelope
            </artwork>
          </figure>

          <figure anchor="chunked_identity_envelope_example">
            <preamble>Chunked Identity Envelope</preamble>
            <artwork>
E x02 x00
  m x00 x08 Identity   # "Identity" envelope does nothing to the body
  x90                  # no headers
  B x00 x0c            # binary header for wrapped body (10 bytes)
    p x02 x00          # wrapped message
    x07 hello,         # "hello, "
    z                  # end of wrapped message
  x90                  # no footers

  x90                  # no headers
  B x00 x08            # binary wrapped body (10 bytes)
    p x02 x00          # wrapped message
    x05 world          # world
    z
  x90                  # no footers
  z                    # end of envelope
            </artwork>
          </figure>

          <figure anchor="compression_envelope_example">
            <preamble>Compression Envelope</preamble>
            <artwork>
E x02 x00
  m x00 x09 Deflation  # "Deflation" envelope compresses the body
  x90                  # no headers
  B x00 x0a            # binary wrapped body (32 bytes)
    x78 x9c x4b...     # compressed message
  x90                  # no footers
  z                    # end of envelope
            </artwork>
          </figure>
        </section>
      </section>
      
      <section title="Message">
        <figure anchor="message_grammar">
          <preamble>Message Grammar</preamble>
          <artwork>
message ::= p x02 x00 object* z
          </artwork>
        </figure>

        <t>
          A Hessian message contains a sequence of Hessian serialized objects.  
          Messages can be used for multihop data transfer or simply for storing
          serialized data.
        </t>
      </section>

      <section title="Reply">
        <figure anchor="reply_grammar">
          <preamble>Reply Grammar</preamble>
          <artwork>
valid-reply ::= r x02 x00 header* value z
fault-reply ::= r x02 x00 header* fault z
          </artwork>
        </figure>

        <section title="Value">
  
          <t>
            A successful reply returns a single value and possibly some header 
            information.  
          </t>
  
          <figure anchor="integer_5_example">
            <preamble>Integer 5 Envelope</preamble>
            <artwork>
r x02 x00
  x95
  z
            </artwork>
          </figure>
        </section>

        <section title="Faults">

          <t>Failed calls return a fault.</t>

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

          <figure anchor="remote_call_throws_example">
            <preamble>Remote Call throws FileNotFoundException</preamble>
            <artwork>
r x02 x00
  f
  x04 code
  x10 ServiceException

  x07 message
  x0e File Not Found

  x06 detail
  M t x00 x1d java.io.FileNotFoundException
    z
  z
            </artwork>
          </figure>

          <list style="hanging">
            <t hangText="ProtocolException:">
              The Hessian request has some sort of syntactic error.
            </t>

            <t hangText="NoSuchObjectException:">
              The requested object does not exist.
            </t>

            <t hangText="NoSuchMethodException:">
              The requested method does not exist.
            </t>

            <t hangText="RequireHeaderException:">
              A required header was not understood by the server.
            </t>

            <t hangText="ServiceException:">
              The called method threw an exception.
            </t>
          </list>
        </section>
      </section>

      <section title="Versioning">
        <t>
          The call and response tags include a major and minor byte.  The
          current version is 2.0.
        </t>
      </section>

    </section>

    <section title="Service Location (URLs)">

      <t>
        Hessian services are identified by URLs.  Typically, these will be
        HTTP URLs, although protocols would be possible as well.
      </t>

      <section title="Object Naming (non-normative)">

        <t> 
          URLs are flexible enough to encode object instances as well as 
          simple static service locations.  The URL uniquely identifies the
          Hessian object.  Thus, Hessian can support object-oriented services, 
          e.g. naming services, entity beans, or session beans, specified by 
          the URL without requiring extra method parameters or headers.
        </t>

        <t>
          Object naming may use the query string convention that "?id=XXX"
          names the object "XXX" in the given service.  This convention is 
          recommented, but not required.
        </t>

        <t>
          For example, a stock quote service might have a factory interface 
          like http://foo.com/stock and object instances like 
          http://foo.com?id=PEET.  The factory interface would return valid
          object references through the factory methods.
        </t>

      </section>

      <section title="Object naming (non-normative) Example">
        <t>As an example, the following format is used for EJB:</t>

        <figure anchor="ejb_url_example">
          <artwork>
http://hostname/hessian<var>/ejb-name</var>?id=<var>object-id</var>
          </artwork>
        </figure>

        <t>
          http://hostname/hessian identifies the EJB container.  In Resin-EJB, 
          this will refer to the EJB Servlet.  "/hessian" is the servlet prefix 
          (url-pattern.)  HTTP is just used as an example; Hessian does not 
          require the use of HTTP.
        </t>

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

        <t>
          object-id 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.
        </t>

        <figure anchor="ejb_url_entity_example">
          <artwork>
# Example Entity Home Identifier
http://localhost/hessian/my-entity-bean

# Example Entity Bean Identifier
http://localhost/hessian/my-entity-bean?ejbid=slytherin

# Example Session Home Identifier
http://localhost/hessian/my-session-bean

# Example Session Bean Identifier
http://localhost/hessian/my-session-bean?ejbid=M9Zs1Zm
          </artwork>
        </figure>
      </section>
    </section>
  </middle>

  <back>
  </back>
 
</rfc>