INTERNET-DRAFT A. Megacz
draft-megacz-xmc-01.txt The XWT Foundation
Category: Informational 01 Sep 2002
Expires: February 2003
XML Method Call (XMC)
** DRAFT **
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on October 22, 2002.
Copyright Notice
Copyright (C) The Internet Society 2002. All Rights Reserved.
Abstract
This memo describes the XML Method Call (XMC) protocol.
XMC a simple presentation layer protocol for network transactions
with method call semantics and payloads consisting of small object
trees. XMC specifies the request and response protocol, an XML
representation for the object trees, and a tree-encoding for
graphs.
XMC is forward and backward compatible with XML-RPC [1]. XMC
clients can make calls to XML-RPC servers, and XML-RPC clients can
make calls to XMC servers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC 2119.
Table of Contents
1. Introduction
2. Implementation Requirements
3. Relationship to XML-RPC
4. XMC values
4.1 Simple Types
4.1.1 boolean
4.1.2 int
4.1.3 string
4.1.4 unicode
4.1.5 double
4.1.6 dateTime.iso8601
4.1.7 base64
4.2 Aggregate Types
4.2.1 array
4.2.2 struct
5. XMC Requests
6. XMC Responses
6.1 Successful Response
6.2 Fault Response
7. Graph Encoding
8. Session Layer Bindings
8.1 HTTP
8.2 HTTPS
8.3 SMTP
8.4 Jabber
1. Introduction
XMC is a presentation layer protocol for network transactions with
method call semantics.
Each transaction consists of a single request sent in its entirity
by the client, followed by a single response sent in its entirity
by the server. Both the request and the response consist of object
trees built from a small set of primitive types. The object trees
are encoded in XML, providing an easily human-readable wire format
which aids debugging. A standardized mapping from graphs to trees
is provided for applications which need to encode multi-reference
data.
XMC assumes that the request and response are each small enough to
be held entirely in main memory before being passed up to the
application layer.
2. Relationship to XML-RPC
XMC is forward and backward compatible with Dave Winer's XML-RPC
[1] protocol. Because UserLand Software, Inc. holds trademark
rights on the name "XML-RPC", XMC is not XML-RPC, although it is
fully compatible with it.
XMC is stricter than XML-RPC in two areas:
- The order of a <member>'s child elements is mandated.
- XMC's behavior is undefined when recieving characters other
than 0x09, 0x0A, 0x0D, and 0x20-0x7F in a <string> or <name>
element, in order to ensure that all XMC requests and replies
are valid XML.
Unlike XML-RPC, XMC is defined independently of any particular
session layer protocol. Bindings for HTTP, SMTP, and Jabber are
included in this document; other bindings may be defined in future
RFCs.
The SMTP Binding described in section 8.2 is derived from and
compatible with the "XML-RPC via SMTP" specification [2] published
by Eric Soroos.
The Jabber Binding described in section 8.3 is derived from and
compatible with JEP-0009 [3] published by DJ Adams.
3. Implementation Requirements
XMC implementations SHOULD use an XML parser compliant with the XML
1.0 specification [5]. XMC implementations MUST NOT assume that
their peers are using a compliant parser.
The behavior of an XMC implementation is undefined when recieving
the following:
- Characters in a CDATA section other than 0x09 (tab), 0x0A
(LF), 0x0D (CR), and 0x20-0xFF (inclusive). Octets in the
range 0x80-0xFF may only occur in the CDATA section of
<unicode/> elements.
- Character and entity references other than "<" and "&".
- <![CDATA[ ... ]]> sections.
- XML attributes, comments, and namespaces.
- XML processing directives other than those explicitly required
by this document.
Any transmission of these constructs is outside this specification
and may be used only by private agreement between endpoints.
4. XMC Values
An XMC value is a single node in an object tree. Each value
belongs to a type, which can be either simple or aggregate.
An XMC value is encoded in XML as a <value> element with a single
child element, except in the case of string values. The tag name
and content of that child element is determined by the value's
type.
4.1 Simple Types
XMC values are of one of six simple types: boolean, int, string,
double, dateTime.iso8601, and base64.
4.1.1 boolean
A boolean is either true or false. The true value is encoded
as "1" and the false value is encoded as "0". Whitespace is
not permitted.
Example:
<value><boolean>1</boolean></value>
4.1.2 int
An int is a signed integer between 1 - 2^31 and 2^31. It is
encoded as an optional '+' or '-' character followed by one
or more digits in the range 0-9. Leading zeroes are not
permitted. Whitespace is not permitted. The type name "i4" can
be used interchangeably with "int".
Example:
<value><i4>+3313</i4></value>
4.1.3 string
A string is encoded as a sequence of CDATA characters subject
to the restrictions in section 3.
Example:
<value><string>fooBaz</string></value>
As a special exception for compatability with XML-RPC, XMC
implementations which recieve a <value> element with
character content should assume that the character content
represents a value of type string. XMC implementations MUST
NOT send values encoded this way.
Example:
<value>fooBaz</value>
4.1.4 unicode
A unicode value is a sequence of unicode characters least one
of which is 0x0080 or greater. The characters must be
encoded into octets using UTF-8. Character sequences which
do not contain any non-ASCII characters should be sent as a
string value.
Not all implementations support unicode strings. An XMC
server which does not support unicode strings MUST return a
fault if it recieves a unicode value. An XMC client which
does not support unicode strings MUST NOT propagate any part
of the request to the application layer if it recieves a
unicode value.
4.1.5 double
A double is a real number. It is encoded as an optional '+'
or '-' character followed by zero or more digits in the range
0-9, followed by a mandatory period '.', followed by zero or
more digits in the range 0-9. Leading zeroes are not
permitted. Whitespace is not permitted.
There is no mechanism for representing NaN, positive
infinity, or negative infinity as a double. There is no bound
on the precision of double values; implementations recieving
a double may truncate or round the double if they cannot
represent it at the level of precision provided.
Example:
<value><double>+.123</double></value>
4.1.6 dateTime.iso8601
A dateTime.iso8601 is an instant in time. It is encoded with
the following format
YYYYMMDDTHH:mm:SS
where YYYY is the four digit year, MM is the two digit month,
DD is the two digit day of the month, T is the literal
character 'T', HH is the two digit time (0-23), : is the
literal character ':', mm is the two digit minute (00-59), SS
is the two digit second (00-59).
Implementations MUST assume that the timezone is UTC unless
server-specific documentation explicitly states otherwise.
Whitespace is not permitted.
The identifier "dateTime.iso8601" is used for compatability
with XML-RPC; the format used is not actually found in ISO
8601 [4].
Example:
<value>
<dateTime.iso8601>19711103T16:20:00</dateTime.iso8601>
</value>
4.1.7 base64
A base64 is a sequence of octets. It is encoded using Base64,
as defined in Section 6.8 of RFC 2045 [6].
Although RFC 2045 limits lines to no more than 76 characters,
XMC implementations MUST correctly decode lines of any length
for compatability with XML-RPC. XMC implementations SHOULD NOT
send lines longer than 76 characters.
Example:
<value><base64>
d293LCB5b3UgbXVzdCByZWFsbHkgYmUgYm9yZWQK
</base64></value>
4.2 Aggregate Types
4.2.1 array
An array is a sequence of values whose order is
significant. An array is encoded as an <array> element with
exactly one child element, <data>. The <data> element
contains zero or more encoded XMC values.
Example:
<array>
<data>
<value><boolean>0</boolean></value>
<value><i4>43</i4></value>
<value><string>Festering Concrete</string></value>
</data>
</array>
4.2.2 struct
A struct is a set of key-value pairs. The order of the pairs
is not significant, and implementations may reorder the
pairs. A struct is encoded as a <struct> element with zero
or more <member> child elements.
Each <member> element has exactly two child elements. The
first child element is <name>, whose CDATA content is the
key, subject to the restrictions in section 3. The second
child element is an encoded XMC value, which constitutes the
value of the pair.
Example: Atomic mass of various elements
<struct>
<member>
<name>Hydrogen</name>
<value><double>1.008</double></value>
</member>
<member>
<name>Helium</name>
<value><double>4.003</double></value>
</member>
</struct>
5. XMC Requests
An XMC Request is a well-formed XML document.
Example:
<?xml version="1.0"?>
<methodCall>
<methodName>airline.priceAirlineTicket</methodName>
<params>
<param>
<value><string>SFO</string></value>
<value><string>PIT</string></value>
<value><i4>1729</i4></value>
<value><boolean>1</boolean></value>
</param>
</params>
</methodCall>
An XMC Request begins with an XML processing directive indicating
only the XML version being used. This directive is followed by a
single <methodCall> element. The <methodCall> element has exactly
two child elements: a single <methodName> element and a single
<params> element. To ensure compatability, the <params> element is
mandatory in XMC, even if the method takes no parameters.
The <methodName> element's content is the name of the method to be
invoked on the server. The string may only contain the following
ASCII characters: A-Z, a-z, 0-9, underscore, period, colon, and
forward slash. All method names beginning with the seven-character
sequence "system." are reserved for use as well-known methods with
the same semantics on every server; all other method names are
server-specific.
The <params> element contains zero or more <param> elements, each of
which represents a single argument to the method being
invoked. Each <param> element has exactly one child element, which
must be an encoded XMC value.
6. XMC Responses
Just like an XMC request, an XMC response begins with an XML
processing directive indicating the XML version in use.
The processing directive is followed by a <methodResponse>
element. The <methodResponse> element must have exactly one
child element, which is a <params> element if the call was
successful, or a <fault> element if the call faulted.
6.1 Successful Response
An XMC Successful Response is sent if the requested method
executed successfully.
Example:
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><double>22.01</double></value>
</param>
</params>
</methodResponse>
The <params> element must have exactly one child element,
<param>. The <param> element must contain a single XMC value,
which represents the result of the method call.
6.2 Fault Response
An XMC Fault Response is sent if the server was unable to decode
the XMC Request, the method requested could not be invoked, or
the method invoked wishes to signal an error condition.
Example:
<?xml version="1.0"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>102</int></value>
</member>
<member>
<name>faultString</name>
<value><string>No such airport.</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>
The <fault> element contains an encoded XMC value, which must be
a struct. The struct must have two members, named "faultCode"
and "faultString".
The "faultCode" member's value must be an int. The value
should represent a machine-readable description of the error
encountered. The meaning of this int is server-specific.
The "faultString" member's value must be a string. The value
should be a description of the error, suitable for presentation
to a human.
7. Graph Encoding
Some applications, particluarly XMC-to-SOAP and SOAP-to-XMC
gateways, will need to encode data structures containing null
references or more than one reference to a given value. XMC Graph
Encoding provides a simple mapping from graphs to trees so that
these data structures can be sent via XMC.
Graph Encoding is implemented as a layer above XMC so that clients
using older toolkits and clients which cannot natively represent
multi-reference data can manipulate and transfer the data in its
tree-encoded form.
Example: a struct with one member (my_array) which is a two-element
array. The first element in the array is the string
"/startswithaslash". The second element of the array is a
reference to the first element in the array.
<value><struct>
<member>
<name>my_array</name>
<value><array><data>
<value><string>//startswithaslash</string></value>
<value><string>/my_array/0</string></value>
</data></array></value>
</member>
</struct></value>
To encode a graph as an XMC value tree:
- Prepend an additional slash (0x2F) to the beginning of all
string values that begin with a slash.
- Encode null references as an XMC string representing the
six-character sequence "/null/".
- Encode one of the references to each value as the value
itself, and all others as an XMC string containing the path to
the value.
The path to the root value is encoded as a single slash. The path
to any other value is the concatenation of steps along the path to
that value from the root of the tree.
- A step from an array to one of its elements is encoded as
a slash followed by a decimal integer indicating the index
in the array to follow. The index of the first element is
zero.
- A step from a struct to one of its members is encoded as a
slash followed by the contents of the <name/> element of
the member, with each ocurrence of the slash character
replaced with the four-character sequence "_//_".
8. Session Layer Bindings
8.1 HTTP
The XMC HTTP binding is compatible with XML-RPC.
To make an XMC call over HTTP, the client should send an HTTP
POST request to the server. The URI used is server-specific,
although it is typical for XML-RPC servers to use "/RPC2" and
XMC servers to use "/XMC". Servers MAY assign semantic meaning
to the URI.
The request MUST have the following headers, although it may
have others:
User-Agent:
Host:
Content-Length:
Content-Type: text/xml
The payload of the HTTP POST request is the XMC request.
The HTTP reply should return code 200 for successes and faults
unless an error occurred at or below the session layer. An HTTP
authentication [8] failure is considered a session layer error,
and MUST result in a return code of 401.
The response must include the following headers, although it may
include others as well:
Content-Length:
Content-Type: text/xml
The payload of the HTTP response is the XMC response.
8.2 HTTPS
The HTTPS binding is identical to the HTTP binding, except that
HTTPS [9] is used as the session layer.
8.3 SMTP
Both the request and response are sent as RFC 2822 messages,
each of which MUST have, at a minimum, the following headers:
To:
Subject:
From:
Date:
Message-Id:
Mime-Version: 1.0
Content-Type: text/xml
The request and response SHOULD also include the X-Mailer
header.
The values of the To: and Subject: headers in the request
message are specified by the server and may be used to route or
filter calls. The body of the message sent by the client is the
XMC request.
The value of the To: header in the response message must match the
value of the From: header in the request message. If the client
included an X-XMC-Response-Subject header, its value is used as
the value of the Subject header of the response message; otherwise
the response Subject is the same as the request subject, prepended
with the four characters "Re: ". The body of the message sent by
the server is the XMC response.
All other headers in the request and response may have any value
consistent with RFC 2822.
8.4 Jabber
An XMC request is sent over Jabber [7] as an <iq/> element of
type "set". The "iq" element must have exactly one child
element, <query/>, whose namespace is "jabber:iq:rpc". The
<query/> element must have exactly one child element, which is
the <methodCall/> element of the XMC request.
Example:
<iq type='set' to='responder@company-a.com/jrpc-server' id='1'>
<query xmlns='jabber:iq:rpc'>
<methodCall>
...
</methodCall>
</query>
</iq>
An XMC response is sent as an <iq/> element of type "result".
The "iq" element must have exactly one child element, <query/>,
whose namespace is "jabber:iq:rpc". The <query/> element must
have exactly one child element, which is the <methodResponse>
element of the XMC response.
Example:
<iq type='result' to='requester@company-b.com/jrpc-client'
from='responder@company-a.com/jrpc-server' id='1'>
<query xmlns='jabber:iq:rpc'>
<methodResponse>
...
</methodResponse>
</query>
</iq>
Session layer errors are indicated in the normal way for <iq/>
elements -- by an <iq/> element of type "error".
Informative References
[1] Winer, Dave, "XML-RPC Specification",
http://www.xmlrpc.org/spec , June 1999.
[2] Soroos, Eric, "XML-RPC via SMTP",
http://www.wiredfool.com/discuss/msgReader$117 , April 2000.
[3] Adams, DJ. "JEP-0009: Transporting XML-RPC over Jabber",
JEP-0009, September 2001.
[4] International Standard ISO 8601
Normative References
[5] Bray, Paoli, Sperberg-McQueen, and Maler, "Extensible Markup
Language (XML) 1.0 (Second Edition)", W3C Recommendation, 6
October 2000.
[6] Freed, Borenstein, "Multipurpose Internet Mail Extensions
(MIME) Part One: Format of Internet Message Bodies", RFC
2045, November 1996.
[7] Miller, "Jabber",
http://hades.jabber.org/ietf/draft-miller-jabber-00.html,
Work in Progress
[8] Franks, Hallam-Baker, Hostetler, Lawrence, Leach, Stewart, and
Luotonen, "HTTP Authentication: Basic and Digest Access
Authentication", RFC 2167, June 1999.
[9] E. Rescorla, "HTTP Over TLS", RFC 2818, May 2000.
Author's Address
Adam Megacz
The XWT Foundation
EMail: adam@xwt.org
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
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 this
paragraph are included on all such copies and derivative
works. However, this document itself may not be modified in any
way, such as by removing the copyright notice or references to the
Internet Society or other Internet organizations, except as needed
for the purpose of developing Internet standards in which case the
procedures for copyrights defined in the Internet Standards process
must be followed, or as required to translate it into languages
other than English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on
an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE 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.
Acknowledgements
Dave Winer designed XML-RPC, which XMC is based upon.
P. Oscar Boykin contributed the wording for the first three
paragraphs of section 4.1.6.
Wording for section 3 was taken from Jay Carlson's lcdXML-RPC
recommendation.
Funding for the RFC Editor function is currently provided by the
Internet Society.