You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

1820 lines
80 KiB

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd'
[ <!ENTITY % ents SYSTEM "xep.ent"> %ents;
<!ENTITY xmlrpc "XML-RPC<note><link url='http://www.xmlrpc.org/spec'>The XML-RPC Specification</link></note>">
]
>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jabber Object Access Protocol (JOAP)</title>
<abstract>The Jabber Object Access Protocol, or JOAP, defines a
mechanism for creating Jabber-accessible object servers, and
manipulating objects provided by those servers. It is intended
for development of business applications with Jabber.</abstract>
&LEGALNOTICE;
<number>0075</number>
<status>Deferred</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>N/A</shortname>
<author>
<firstname>Evan</firstname>
<surname>Prodromou</surname>
<email>evan@prodromou.san-francisco.ca.us</email>
<jid>EvanProdromou@jabber.org</jid>
</author>
<revision>
<version>0.3</version>
<date>2003-05-22</date>
<initials>esp</initials>
<remark>For consistency, renamed hyphenated elements
'new-address' and 'return-type' to 'newAddress' and 'returnType'
respectively. Added 'desc' element for human-readable
descriptions to object servers and classes. Changed the
'writeable' [sic] attribute to the more correct
'writable'. Added experimental namespace recommendation in
XMPP Registrar section.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-03-05</date>
<initials>esp</initials>
<remark>Added a schema and DTD, a number of new examples, and
ensured that all examples validate against the DTD and
schema.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-01-28</date>
<initials>esp</initials>
<remark>Initial version (unpublished).</remark>
</revision>
</header>
<section1 topic='Introduction'>
<p>This document defines the Jabber Object Access Protocol (JOAP)
as an extension to the Jabber protocol. It outlines the
addressing scheme and IQ stanzas that comprise the protocol as
well as the data types that the protocol models. Example
applications are discussed, as well as security
considerations.</p>
<p>Jabber has a number of attractive features that give it an
advantage over existing frameworks for building multi-tier
applications, such as the Simple Object Access Protocol (SOAP)
or Java 2, Enterprise Edition (J2EE). Among these are:</p>
<ul>
<li><strong>Built-in authentication.</strong> All clients in the
Jabber network must be authenticated with their server before
sending messages to other Jabber entities. Inter-server
communication requires additional authentication, in the form
of dialback connections or other trust mechanisms. This
ensures that, when a message is delivered to a JOAP object
server, there is little doubt as to the authenticity of its
originator.</li>
<li><strong>Global namespace.</strong> Jabber allows namespacing
of addresses according to domain names. This allows objects to
be accessed globally, according to authorization rules.</li>
<li><strong>An asynchronous messaging model.</strong> Jabber is
built on a store-and-forward mechanism that allows a single
client to send messages to multiple servers concurrently. Of
course, synchronous messaging can be simulated on the client
side.</li>
<li><strong>Cross-enterprise messaging.</strong> Jabber is
designed to allow cross-enterprise messaging. Using Jabber for
multitier applications makes development of cross-enterprise
systems as easy as intra-enterprise development.</li>
<li><strong>Message routing.</strong> The architecture of Jabber
is based on clients that connect to a local server, and then
can send messages through that server to other clients,
servers, or components. Topographically, this contrasts well
with the one-to-one connections required with, for example,
HTTP.</li>
<li><strong>Factoring network connections out of
scalability.</strong> Because messages in Jabber are routed,
components need to maintain only one connection -- to their
upstream Jabber server. This removes the number of network
connections from the scalability equation for object
servers.</li>
<li><strong>Language independence.</strong> Jabber protocol
implementations exist for Java, C, and C++ as well as a number
of scripting languages such as Perl and Python.</li>
<li><strong>Platform independence.</strong> The Jabber protocol
is implemented on most major modern platforms.</li>
</ul>
<p>For existing Jabber development efforts, there are significant
advantages to building applications within a JOAP
framework. It should go without saying that, for developers creating
business applications on top of Jabber, a uniform object access
protocol provides significant advantage for cross-product
integration.</p>
<p>In addition, implementers of special-purpose components, such as
multi-user chat servers or whiteboarding components, can use an
object-server interface to allow fine-grained control of the
implementations, especially where such control is not specified
by the applicable Jabber protocol.</p>
</section1>
<section1 topic='Requirements'>
<p>JOAP has the following design goals:</p>
<ul>
<li>Create a protocol for client programs to access object
server components.</li>
<li>Create a model for addressing object servers, classes, and
instances.</li>
<li>Define a language for manipulating data.</li>
<li>Define a language for describing data structures.</li>
<li>Maintain compatibility with &xep0009;.</li>
<li>Make classes and instances directly addressable.</li>
<li>Allow human- and programming-language independence.</li>
<li>Allow easy dynamic mapping of JOAP classes to local classes
in Perl, Python, and other dynamic languages.</li>
</ul>
<p>The following are non-goals:</p>
<ul>
<li>Enable object-oriented access to all parts of the Jabber
network (e.g., clients, other components).</li>
<li>Define a language for creating or altering classes on an
object server.</li>
<li>Define a language for describing or defining the
authorization of given users for given objects.</li>
<li>Define a programming interface between object servers and
classes in those servers (like Enterprise Java Beans).</li>
</ul>
</section1>
<section1 topic='Overview'>
<p>The JOAP interface is made up of three key parts:</p>
<ul>
<li>A scheme for defining the addresses of object servers,
classes, and instances (collectively known as
"objects").</li>
<li>A set of message stanzas in the <tt>jabber:iq:joap</tt>
namespace for manipulating data in object servers, classes,
and instances. The stanzas allow client programs to analyze
the structure of objects, to read object attributes, to edit
object attributes, to add new instances, to delete instances,
and to search classes.</li>
<li>An application of XEP-0009 for calling methods on
objects.</li>
</ul>
</section1>
<section1 topic='Entities in the JOAP Universe'>
<p>This section describes the various entities in the JOAP
universe. Some entities are directly addressable with Jabber IDs
(JIDs), as described below. Others are not considered outside of
their enclosing entities.</p>
<section2 topic='Object Server Component'>
<p>An object server component is a Jabber component that
provides object services. It is addressed like any other
Jabber component, i.e., with a DNS hostname or
pseudo-hostname. Some examples would be:</p>
<ul>
<li><tt>payroll.example.com</tt> - A payroll application
server.</li>
<li><tt>jukebox.example.com</tt> - An MP3 jukebox server.</li>
</ul>
<p>An object server has zero or more attributes, methods, and
classes.</p>
</section2>
<section2 topic='Class'>
<p>A class is a category of object instances. It defines the
structure and interface of these instances. Each class is
addressed using the class name as the node identifier, and the
object server as the domain identifier. Class names must
conform to the node identifier restrictions defined for
XMPP. Class names must also be unique, regardless of case,
within an object server.</p>
<p>For example:</p>
<ul>
<li><tt>Employee@payroll.example.com</tt> - An employee class
at the payroll.example.com server.</li>
<li><tt>Song@jukebox.example.net</tt> - A song class on the
jukebox server.</li>
<li><tt>Board@circuit-design.example.com</tt> - A class for
circuit boards.</li>
<li><tt>Board@surf-shop.example.net</tt> - A class for
surfboards -- distinct from above class!</li>
</ul>
<p>Beside uniqueness and XMPP compliance, no further requirements are
made on class names. However, good design suggests mnemonic names.</p>
<p>Classes define the attributes and methods of their instances. In
addition, they can have attributes and methods of their own. Finally,
classes can have superclasses, which indicate an inheritance structure
as well as implementation of a defined interface.</p>
<p>JOAP allows for no relative addressing of classes. Classes
are always referred to by their full address (node identifier
plus domain identifier).</p>
</section2>
<section2 topic='Instance'>
<p>An instance is a collection of data with identity, state, and
behavior. Each instance is a member of a class, which defines the
attributes (data) and methods (behavior) of the instance
itself.</p>
<p>An instance is addressed using the node plus server that identifies
its class, as well as a unique string that occupies the resource
identifier section of the Jabber ID. The resource is only unique over
the space of the corresponding class. Some example instance addresses:</p>
<ul>
<li><tt>Room@hotel.example.com/103</tt> - Room 103 in the
Example Hotel.</li>
<li><tt>Element@periodic-table.example.net/103</tt> - Element
103 (rutherfordium) in the periodic table.</li>
<li><tt>Employee@payroll.example.com/JohnSmith</tt> - An
employee named "John Smith".</li>
<li><tt>Customer@videorental.example.net/JohnSmith</tt> - A
customer named "John Smith" (not necessarily the
same person as the above employee!).</li>
</ul>
<p>Besides uniqueness within a class, and compliance with the
rules for resource identifiers in the XMPP standard, there are
no further requirements on instance identifiers in JOAP. In
particular, the instance identifier is opaque -- that is, no
further information about the state of the object can or
should be discerned from the identifier. What visible part of
the instance, if any, makes up the unique resource identifier
is implementation dependent.</p>
<p>That said, it is recommended that the instance identifier be
persistent through the life of the instance. In addition, using
mnemonic identifiers can greatly enhance the usability of JOAP
objects.</p>
<p>As with other resource identifiers, instance identifiers are
case-sensitive.</p>
<p>The instance identifier roughly corresponds to a primary key in a
relational database, and for object servers that provide access to
relational databases, it is recommended to use the primary key of a
table as the instance identifier. For tables with a compound key, a
comma (',') dash ('-'), or other non-alphanumeric character can be
used to separate parts of the key for better readability. For
example:</p>
<ul>
<li><tt>Date@calendar.example.net/2003-01-26</tt> -- The date
January 26th, 2003.</li>
<li><tt>City@canada.example.com/Montréal,QC</tt> -- The city
of Montréal, in the province of Québec.</li>
</ul>
<p>JOAP allows for no relative addressing of
instances. Instances are always referred to using their full
address (node identifier plus domain identifier plus resource
identifier).</p>
</section2>
<section2 topic='Attribute'>
<p>An attribute is a unit of state that makes up part of an object
server, instance, or class. Each attribute has a name and a
type.</p>
<p>Attribute names must be strings of characters containing only
the characters [a-zA-Z0-9_]. The first character must be an
underscore or alphabetic character. <note>This requirement is
intended to allow easy mapping of attributes in JOAP to
attributes of objects in client programming languages. The
restriction is the lowest common denominator for variable
names in most modern programming languages.</note></p>
<p>Attributes cannot be addressed individually. Attributes are
manipulated by sending JOAP messages to the object that owns
them.</p>
</section2>
<section2 topic='Method'>
<p>A method is a unit of behavior that makes up part of an
object. Methods in JOAP are compatible with &xmlrpc;, as
specified in &xep0009;. In particular, methods have a name, a
return type, and 0 or more parameters, each of which has a
type.</p>
<p>The one exception to XML-RPC compatibility is that method
names for JOAP are restricted to the characters
[a-zA-z0-9_]. <note>This is to avoid conceptual mismatch in
programming languages where the other three characters allowed
by XML-RPC, namely ".", ":", and
"/", are used to separate class or instance names
from methods.</note></p>
<p>Methods cannot be directly addressed using JOAP. Methods are
described and executed by sending messages to the object
server, class, or instance that owns them.</p>
</section2>
</section1>
<section1 topic='JOAP Data Types'>
<p>The range of JOAP data types is borrowed directly from
XML-RPC.</p>
<section2 topic='Scalar Types'>
<p>The scalar types include the following:</p>
<ul>
<li><strong>int</strong> or <strong>i4</strong>: a 32-bit
signed integer</li>
<li><strong>boolean</strong>: a one-digit integer representing
"true" (1) or "false" (0)</li>
<li><strong>string</strong>: a string of characters</li>
<li><strong>double</strong>: double-precision signed
floating-point number</li>
<li><strong>datetime.iso8601</strong>: a date value, in ISO
8601 format</li>
<li><strong>base64</strong>: binary data, base64-encoded for
transmission</li>
</ul>
</section2>
<section2 topic='Instance Addresses'>
<p>Instance addresses are a special type of string used for
referring to instance objects. They can be passed as
parameters to methods, or set as attribute values.</p>
<p>If a value can contain an object instance, its type is the
address of a class. The address of any object instance that is
an instance of that class, or any of its subclasses, can be
used in that value.</p>
<p>For example, if <tt>Boxcar@trainset.example.com</tt> is a
subclass of <tt>Car@trainset.example.com</tt>, then
<tt>Boxcar@trainset.example.com/569</tt> can be used as a
method parameter, or set as an attribute, where
<tt>Car@trainset.example.com</tt> is the defined type.</p>
<p>Because addresses are used for instance values, all methods
involving instances are implicitly pass-by-reference. If a
pass-by-value functionality is needed, a struct (see below)
should be used instead.</p>
<p>Note that attribute and method param types can use classes
and instances from other object servers (that is, with
different domain identifiers). For instance, an
<tt>Employee@payroll.example.com</tt> class could have an
attribute of type <tt>Job@hr.example.com</tt>.</p>
</section2>
<section2 topic='Compound Types'>
<p>There are two compound types defined in XML-RPC.</p>
<section3 topic='Arrays'>
<p>An <em>array</em> is an ordered list of values. An array
can contain values of any type, including other compound
types.</p>
<p>In JOAP, as with XML-RPC, it is not possible to address,
set, or delete elements of an array. To set values in an
array, the entire new array must be specified.</p>
</section3>
<section3 topic='Structs'>
<p>A <em>struct</em> is a set of name-value pairs organized into
a logical grouping. A struct can contain values of any type,
including other compound types.</p>
<p>In JOAP, as with XML-RPC, it is not possible to address,
set, or delete elements of a struct. To set values in an
struct, the entire new struct must be specified.</p>
<p>Structs are useful mainly for groupings of data that do not
have independent identity or behavior. Where an object
needs identity or behavior, an instance should be used
instead of a struct.</p>
</section3>
</section2>
<section2 topic='Specifying Types'>
<p>Types are specified by a string name of the type. This can be
one of the XML-RPC types described above, or a class
address.<note>Implementers can determine if a specified type
is valid by checking it against a list of the XML-RPC
types. If it does not match, it should be checked to see if
matches the syntax for a class address (node identifier
plus domain identifier). Otherwise, it is not a valid
type.</note></p>
</section2>
</section1>
<section1 topic='JOAP Stanzas'>
<p>This section defines the Jabber stanzas that make up the JOAP
protocol.</p>
<p>Each stanza is an information query (IQ). Except for method
calls, the stanzas are all in the 'jabber:iq:joap' namespace. Each
of the following sections describes a stanza in that namespace,
herein called a "verb". The verbs allow basic access
to object servers, classes, and instances.</p>
<p>Not all verbs can be sent to all JOAP entities. The appropriate JOAP
entity a verb should be addressed to is noted under the description of
the verb.</p>
<section2 topic='&lt;describe&gt;'>
<p>The &lt;describe&gt; verb requests the interface -- that is, methods,
attributes, and classes -- of a given object server or class. The IQ
type is "get".</p>
<p>The &lt;describe&gt; verb is useful for creating wrapper
classes in JOAP clients, either at runtime or at compile
time. It can also be used for object browsers, or for client
programs to ascertain that the interface they assume for an
object is still valid.</p>
<section3 topic='Targets'>
<p>&lt;describe&gt; verbs can be sent to object servers, classes, and
instances. Each will return different data.</p>
<ul>
<li>Object servers return zero or more descriptive texts,
zero or more attribute definitions, zero or more method
definitions, zero or more class names, and a
timestamp.</li>
<li>Classes return zero or more descriptive texts, zero or
more attribute definitions, zero or more method
definitions, and a timestamp.</li>
<li>Instances return the exact results of sending the
&lt;describe&gt; method to their class. This is for convenience
only; it is preferable to send &lt;describe&gt; to the class
directly.</li>
</ul>
</section3>
<section3 topic='Descriptive Texts'>
<p>Each object description can contain one or more strings of
descriptive text. This is to indicate the
purpose and usage of the object in human-readable form.</p>
<p>Multiple descriptions are allowed in the hope that they
will be used to describe the attribute in multiple
languages (differentiated using the xml:lang
attribute).</p>
</section3>
<section3 topic='Attribute Definitions'>
<p>Attribute definitions have the following parts:</p>
<ul>
<li>A name, which is a legal attribute name as described
above.</li>
<li>A type, which is a legal JOAP type as described
above.</li>
<li>A flag indicating if the attribute is an attribute of the
class itself, or of individual instances.</li>
<li>A flag indicating if the attribute is writable.</li>
<li>A flag indicating if the attribute is required.</li>
<li>One or more strings of descriptive text, to indicate the
purpose and usage of this attribute. Multiple
descriptions are allowed in the hope that they will be
used to describe the attribute in multiple languages
(differentiated using the 'xml:lang' attribute).</li>
</ul>
<p>The attribute definitions returned to a client should
include only attributes the user is authorized to access.</p>
</section3>
<section3 topic='Method Definitions'>
<p>Method definitions have the following parts:</p>
<ul>
<li>A name, which is a legal method name as described
above.</li>
<li>A return type, which is a legal JOAP type as described
above.</li>
<li>A flag indicating if the method is a method of the class
itself, or of individual instances.</li>
<li>Zero or more parameters, each of which has a name, a
type, and one or more strings of descriptive text.</li>
<li>One or more strings of descriptive text, indicating the
use and behavior of this method.</li>
</ul>
<p>The method definitions returned to a client should
include only methods the user is authorized to access.</p>
</section3>
<section3 topic='Class References'>
<p>Classes, in superclass definitions and object server
interfaces, are always referred to by their full
address.</p>
</section3>
<section3 topic='Timestamps'>
<p>The timestamp is a date-time value in ISO 8601 format,
UTC. The timestamp indicates the last time an interface was
changed, if that information is available.</p>
</section3>
<section3 topic='Superclasses'>
<p>The main point of describing the superclasses a class has
is to allow clients to make typing distinctions: that is, to
determine if a class presents a given interface, or may be
provided as a parameter or attribute in another JOAP
call.</p>
<p>The list of superclasses given in a class description is
flat, not hierarchical. No provision is made to
indicate which of a class's superclasses are superclasses of
each other, nor is there any implied precedence order in the
order of the classes in the returned description.</p>
<p>In addition, no provision is made to define which
superclass actually implements any methods or attributes
defined.</p>
</section3>
<section3 topic='Flattening'>
<p>When a class receives a &lt;describe&gt; verb, it must
return all its superclasses, including multiple
ancestors. It must as well return all the attributes and
methods that it responds to, including those defined in
its superclasses. This is called a "flattened"
description of the class. <note>Flattening the class
interface reduces the need for making multiple
"describe" verb calls just to find the interface
for one class.</note></p>
</section3>
<section3 topic='Examples'>
<p>The following examples illustrate the use of the &lt;describe&gt;
verb. <note>All extended examples in this document refer
to a particular object domain, based on a fictional model
train set. A UML description of the object domain is
available in Appendix D.</note></p>
<p>To describe a server, the JOAP client sends this
stanza.</p>
<example caption='Describing An Object Server'><![CDATA[
<iq type='get'
id='joap_describe_1'
from='Client@example.com'
to='trainset.example.com'>
<describe xmlns='jabber:iq:joap' />
</iq>]]></example>
<p>The object server returns this response:</p>
<example caption='Description of an Object Server'><![CDATA[
<iq type='result'
id='joap_describe_1'
from='trainset.example.com'
to='Client@example.com'>
<describe xmlns='jabber:iq:joap'>
<desc xml:lang='en-US'>
This server provides classes for managing a virtual
remote train set.
</desc>
<attributeDescription writable='true'>
<name>logLevel</name>
<type>i4</type>
<desc xml:lang='en-US'>Verbosity level for access logging.</desc>
</attributeDescription>
<methodDescription>
<name>startLogging</name>
<returnType>boolean</returnType>
<desc xml:lang='en-US'>Start logging activity on this
server. Returns true for success and false for an
error.</desc>
</methodDescription>
<methodDescription>
<name>stopLogging</name>
<returnType>boolean</returnType>
<desc xml:lang='en-US'>Stop logging activity on this
server. Returns true for success and false for an
error.</desc>
</methodDescription>
<class>Train@trainset.example.com</class>
<class>Car@trainset.example.com</class>
<class>Caboose@trainset.example.com</class>
<class>Engine@trainset.example.com</class>
<class>Boxcar@trainset.example.com</class>
<class>PassengerCar@trainset.example.com</class>
<class>Building@trainset.example.com</class>
<class>TrackSegment@trainset.example.com</class>
<class>Switch@trainset.example.com</class>
<class>Station@trainset.example.com</class>
<timestamp>2003-01-07T20:08:13Z</timestamp>
</describe>
</iq>]]></example>
<p>To describe the <tt>Car@trainset.example.com</tt> class,
the JOAP client sends this stanza to the class for
boxcars.</p>
<example caption='Describing a Class'><![CDATA[
<iq type='get'
id='joap_describe_2'
from='Client@example.com'
to='Boxcar@trainset.example.com' >
<describe xmlns='jabber:iq:joap' />
</iq>]]></example>
<p>The class returns this stanza to the JOAP client.</p>
<example caption='Description of a Class'><![CDATA[
<iq type='result'
id='joap_describe_2'
from='Boxcar@trainset.example.com'
to='Client@example.com'>
<describe xmlns='jabber:iq:joap'>
<desc xml:lang='en-US'>
A Car in the trainset that can be used to ship cargo.
</desc>
<attributeDescription writable='false' required='true'>
<name>trackingNumber</name>
<type>i4</type>
<desc xml:lang='en-US'>Tracking number for this car.</desc>
</attributeDescription>
<attributeDescription writable='true' required='true'>
<name>contents</name>
<type>string</type>
<desc xml:lang='en-US'>Contents of the boxcar.</desc>
</attributeDescription>
<methodDescription allocation='class'>
<name>nextTrackingNumber</name>
<returnType>i4</returnType>
<desc xml:lang='en-US'>The next available tracking number.</desc>
</methodDescription>
<superclass>Car@trainset.example.com</superclass>
<timestamp>2003-01-07T20:08:13Z</timestamp>
</describe>
</iq>]]></example>
<p>To describe an instance, the JOAP client sends this stanza
to a particular track segment.</p>
<example caption='Describing an Instance'><![CDATA[
<iq type='get'
id='joap_describe_3'
from='Client@example.com'
to='TrackSegment@trainset.example.com/134' >
<describe xmlns='jabber:iq:joap' />
</iq>
]]>
</example>
<p>The instance returns this stanza to the JOAP client.</p>
<example caption='Description of an Instance'><![CDATA[
<iq type='result'
from='TrackSegment@trainset.example.com/134'
to='Client@example.com'
id='joap_describe_3'>
<describe xmlns='jabber:iq:joap'>
<desc xml:lang='en-US'>
A length of track in the trainset which can be
connected to a previous and next length of track.
</desc>
<attributeDescription>
<name>previous</name>
<type>TrackSegment@trainset.example.com</type>
<desc>Previous segment of track.</desc>
</attributeDescription>
<attributeDescription>
<name>next</name>
<type>TrackSegment@trainset.example.com</type>
<desc>Next segment of track.</desc>
</attributeDescription>
<timestamp>2003-01-07T20:08:13Z</timestamp>
</describe>
</iq>]]>
</example>
</section3>
</section2>
<section2 topic='&lt;read&gt;'>
<p>The &lt;read&gt; verb allows clients to retrieve the values
of attributes of an object server, class, or instance. The
client can specify which attributes to return; if no
attributes are specified, then all attributes are
returned. <note>This allows clients to cheaply retrieve
meta-information about an instance that may have exceptionally
large data, such as bin64-encoded file data.</note></p>
<p>The &lt;read&gt; verb uses the "get" IQ type.</p>
<section3 topic='Timestamps'>
<p>A timestamp, in ISO 8601 format, UTC, can be added to the
results of a &lt;read&gt;. The timestamp indicates the last
time any of an object's attribute values have changed (not
just the requested ones). The timestamp can be used, for
example, to implement object caching on the client side.</p>
</section3>
<section3 topic='Error Codes'>
<p>The following are some common error codes may be generated
in response to a &lt;read&gt; verb.</p>
<ul>
<li><strong>404 (Not Found)</strong>: The object addressed
does not exists.</li>
<li><strong>403 (Forbidden)</strong>: The user is not
authorized to read attributes of this object, or not
authorized to read the specified attributes of this
object.</li>
<li><strong>406 (Not Acceptable)</strong>: The client sent
an &lt;read&gt; verb specifying attributes that are not
defined for the class.</li>
</ul>
</section3>
<section3 topic='Examples'>
<p>This section gives some examples of using the &lt;read&gt;
verb.</p>
<p>A client would send the following stanza to an instance to
read its attributes:</p>
<example caption='Reading the Attributes of an
Instance'><![CDATA[
<iq type='get'
id='joap_read_1'
from='Client@example.com'
to='Station@trainset.example.com/Paddington'>
<read xmlns='jabber:iq:joap' />
</iq>
]]>
</example>
<p>In return, the instance would send this stanza to the
client:</p>
<example caption='Attributes of an Instance'><![CDATA[
<iq type='result'
id='joap_read_1'
from='Station@trainset.example.com/Paddington'
to='Client@example.com'>
<read xmlns='jabber:iq:joap'>
<attribute>
<name>name</name>
<value>Paddington Station</value>
</attribute>
<attribute>
<name>size</name>
<value>
<struct>
<member>
<name>length</name>
<value><i4>4</i4></value>
</member>
<member>
<name>width</name>
<value><i4>3</i4></value>
</member>
</struct>
</value>
</attribute>
<attribute>
<name>previous</name>
<value>TrackSegment@trainset.example.com/334</value>
</attribute>
<attribute>
<name>next</name>
<value>TrackSegment@trainset.example.com/271</value>
</attribute>
</read>
</iq>]]>
</example>
<p>To read only specified attributes of an instance, the
client would send this stanza:</p>
<example caption='Reading Limited Attributes'><![CDATA[
<iq type='get'
id='joap_read_2'
from='Client@example.com'
to='Train@trainset.example.com/38'>
<read xmlns='jabber:iq:joap'>
<name>location</name>
<name>cars</name>
</read>
</iq>
]]>
</example>
<p>In return, the instance would send this stanza to the
client:</p>
<example caption='Limited Attributes'><![CDATA[
<iq type='result'
id='joap_read_2'
from='Train@trainset.example.com/38'
to='Client@example.com'>
<read xmlns='jabber:iq:joap'>
<attribute>
<name>location</name>
<value>Station@trainset.example.com/Paddington</value>
</attribute>
<attribute>
<name>cars</name>
<value>
<array>
<data>
<value>Engine@trainset.example.com/14</value>
<value>PassengerCar@trainset.example.com/112</value>
<value>PassengerCar@trainset.example.com/309</value>
<value>BoxCar@trainset.example.com/212</value>
<value>Caboose@trainset.example.com/9</value>
</data>
</array>
</value>
</attribute>
</read>
</iq>]]></example>
</section3>
</section2>
<section2 topic='&lt;add&gt;'>
<p>The &lt;add&gt; verb is used to create a new instance of a
JOAP class. The verb is sent to the JOAP class, which returns
the address of the newly-created instance.</p>
<p>Within each &lt;add&gt; verb the client must include
attribute values for each required, writable attribute of the
class.</p>
<p>The IQ is of type "set".</p>
<section3 topic='Error Codes'>
<p>The following are some common error codes may be generated
in response to an &lt;add&gt; verb.</p>
<ul>
<li><strong>404 (Not Found)</strong>: The class for which an
instance is to be instantiated does not exists.</li>
<li><strong>403 (Forbidden)</strong>: The user is not
authorized to instantiate an instance of this class.</li>
<li><strong>405 (Not Allowed)</strong>: The client sent an
&lt;add&gt; verb to something that isn't a class.</li>
<li><strong>406 (Not Acceptable)</strong>: The client sent an
&lt;add&gt; verb containing attributes that are not
writable, or without all required, writable attributes,
or with attributes that are not defined for the class, or
with attribute values that are of the wrong type.</li>
</ul>
</section3>
<section3 topic='Examples'>
<p>To create a new PassengerCar, the client would send the
following stanza to the PassengerCar class:</p>
<example caption='Adding a New Instance'><![CDATA[
<iq type='set'
id='joap_add_1'
to='PassengerCar@trainset.example.com'
from='Client@example.com'>
<add xmlns='jabber:iq:joap'>
<attribute>
<name>passengers</name>
<value><i4>38</i4></value>
</attribute>
</add>
</iq>]]></example>
<p>The class would return the following response:</p>
<example caption='A New Instance'><![CDATA[
<iq type='result'
id='joap_add_1'
from='PassengerCar@trainset.example.com'
to='Client@example.com'>
<add xmlns='jabber:iq:joap'>
<newAddress>PassengerCar@trainset.example.com/866</newAddress>
</add>
</iq>
]]></example>
<p>Note that the class created a new instance identifier, 866,
for the new instance. Further communications from the client
would use the full instance address returned.</p>
</section3>
</section2>
<section2 topic='&lt;edit&gt;'>
<p>The &lt;edit&gt; verb is used to update the attributes of an
object. The name and new value of each attribute that is to be
updated is listed in the &lt;edit&gt; verb.</p>
<p>The IQ is of type "set".</p>
<p>Leaving a given attribute out of an &lt;edit&gt; verb does
not indicate that the attribute should be set to an undefined
or default value. The new values of attributes that are left
out is implementation-dependent; in general, though, they
should remain unchanged, if possible.</p>
<section3 topic='Content in &lt;edit&gt; Results'>
<p>If the results of an &lt;edit&gt; verb have content, it
will contain the new address of the instance that was
updated. The new address should be used henceforth by the
client. <note>This is to allow updates that alter the unique
key or attribute of an instance that determine its instance
identifier.</note></p>
</section3>
<section3 topic='Error Codes'>
<p>The following error codes may be generated in response to a
&lt;edit&gt; verb.</p>
<ul>
<li><strong>404 (Not Found)</strong>: The object to be
edited does not exists.</li>
<li><strong>403 (Forbidden)</strong>: The user is not
authorized to edit this object, or to change one of the
attributes specified in the &lt;edit&gt; request.</li>
<li><strong>406 (Not Acceptable)</strong>: The client sent
an &lt;edit&gt; verb containing attributes that are not
defined for the class, or with attribute values that are
of the wrong type, or with attribute values that are
outside the range for the attribute.</li>
</ul>
</section3>
<section3 topic='Examples'>
<p>To change the number of passengers in a PassengerCar, the
client would send the following stanza to the instance:</p>
<example caption='Editing an Instance'><![CDATA[
<iq type='set'
id='joap_edit_1'
from='Client@example.com'
to='PassengerCar@trainset.example.com/199'>
<edit xmlns='jabber:iq:joap'>
<attribute>
<name>passengers</name>
<value><i4>31</i4></value>
</attribute>
</edit>
</iq>
]]></example>
<p>The client would return the following stanza:</p>
<example caption='Results of Editing an Instance'><![CDATA[
<iq type='result'
id='joap_edit_1'
to='Client@example.com'
from='PassengerCar@trainset.example.com/199'>
<edit xmlns='jabber:iq:joap' />
</iq>
]]></example>
<p>If a client wanted to change the name of a Building, it
would send the following stanza to the instance:</p>
<example caption='Editing an Instance'><![CDATA[
<iq type='set'
id='joap_edit_2'
from='Client@example.com'
to='Building@trainset.example.com/JonesFamilyHome'>
<edit xmlns='jabber:iq:joap'>
<attribute>
<name>name</name>
<value>Smith Family Home</value>
</attribute>
</edit>
</iq>
]]></example>
<p>The results would be as follows:</p>
<example caption='Results of Editing an Instance'><![CDATA[
<iq type='result'
id='joap_edit_2'
to='Client@example.com'
from='Building@trainset.example.com/JonesFamilyHome'>
<edit xmlns='jabber:iq:joap'>
<newAddress>Building@trainset.example.com/SmithFamilyHome</newAddress>
</edit>
</iq>
]]></example>
<p>Note that the instance indentifier, and thus the instance
address, of the instance has changed. The <tt>from</tt> part
of the IQ, however, contains the old address.</p>
</section3>
</section2>
<section2 topic='&lt;delete&gt;'>
<p>The &lt;delete&gt; verb is used to delete an instance. The IQ
is of type "set". The &lt;delete&gt; stanza has no
sub-elements.</p>
<p>Only instances can be deleted. Classes and object servers
cannot be deleted. After an instance is deleted, it is no
longer addressable.</p>
<p>A given user may not be able to delete a particular
instance.</p>
<section3 topic='Error Codes'>
<p>The following error codes may be generated in response to a
&lt;delete&gt; verb.</p>
<ul>
<li><strong>404 (Not Found)</strong>: The instance to be
deleted does not exists.</li>
<li><strong>403 (Forbidden)</strong>: The user is not
authorized to delete this instance.</li>
<li><strong>405 (Not Allowed)</strong>: The client sent a
&lt;delete&gt; verb to an object server or class.</li>
</ul>
</section3>
<section3 topic='Examples'>
<p>To delete an instance, a client would send the following
stanza:</p>
<example caption='Deleting an Instance'><![CDATA[
<iq type='set'
id='joap_delete_1'
from='Client@example.com'
to='Building@trainset.example.com/Courthouse'>
<delete xmlns='jabber:iq:joap' />
</iq>]]></example>
<p>The instance would return this stanza:</p>
<example caption='A Deleted Instance'><![CDATA[
<iq type='result'
id='joap_delete_1'
to='Client@example.com'
from='Building@trainset.example.com/Courthouse'>
<delete xmlns='jabber:iq:joap' />
</iq>]]></example>
<p>If the user is not authorized to delete the instance, it
would return this error:</p>
<example caption='Error on Unauthorized Deletion'><![CDATA[
<iq type='error'
id='joap_delete_1'
to='Client@example.com'
from='Building@trainset.example.com/Courthouse'>
<delete xmlns='jabber:iq:joap' />
<error code='403'>
You are not authorized to delete this instance.
</error>
</iq>]]></example>
</section3>
</section2>
<section2 topic='&lt;search&gt;'>
<p>The &lt;search&gt; verb allows rudimentary searching and
listing of instances in a class. The IQ is of type
"get".</p>
<p>The client sends a &lt;search&gt; verb to the class,
specifying the attributes that are search criteria and values
to search for. The class returns a list of the addresses of
matching instances.</p>
<p>Multiple attributes are logically AND'd; that
is, resulting instances must match <em>all</em> of the
attribute values.</p>
<section3 topic='Value Matching'>
<p>How attribute values are specified for matching depends on
the type of the attribute.</p>
<ul>
<li>For numeric types (&lt;int&gt;, &lt;double&gt;),
&lt;boolean&gt;, and &lt;dateTime.iso8601&gt;, values match
if they are exactly equal.</li>
<li>For &lt;string&gt; types, a search value matches an
attribute value if it is a case-dependent substring of
that value. For example, "hat" will match
"hat", "that", and "real-time
chat server".</li>
<li>For the &lt;base64&gt; type, a search value matches
an attribute value if the base64-decoded value of the
search value is an 8-bit clean substring of the
base64-decoded attribute value. For example,
"aGF0Cg==" ("hat") will match
"cmVhbC10aW1lIGNoYXQK" ("real-time
chat").</li>
<li>For instance addresses, a search value matches an
attribute value if they are exactly equal.</li>
<li>For &lt;struct&gt; types, a search value matches an
attribute value if each of its named members matches the
corresponding named members in the attribute value, and
has the same type.</li>
<li>For &lt;array&gt; types, a search value matches an
attribute value if each of its members matches the
corresponding members in the attribute value, in order,
and has the same type.</li>
</ul>
</section3>
<section3 topic='Instances of Subclasses'>
<p>Classes should return all instances of the class that are
on the same object server (that is, which have the same
domain identifier in their address) and that match the search
criteria. This includes instances of subclasses of the
class.</p>
<p>Whether a class returns instances of subclasses that reside
on other object servers is implementation-dependent.
<note>This caveat is to allow different types of subclassing
policies. Classes that define a well-known, standard
interface -- for example, a class defined by a standards
organization -- would probably not be "aware" of
all instances of that class. However, it is conceivable to
have a multi-tier business application where the object
servers did know about other servers, their classes, and
their instances.</note></p>
<p>Classes cannot be searched on attributes that are defined
only in subclasses; for example, a search for the attribute
"contents" sent to the
<tt>Car@trainset.example.com</tt> class should result in a
<tt>406 (Not Acceptable)</tt> error.</p>
</section3>
<section3 topic='Empty &lt;search&gt;'>
<p>The semantics of an empty &lt;search&gt; verb is to request
<em>all</em> instances of a class. This provides a listing
or browsing functionality.</p>
</section3>
<section3 topic='Error Codes'>
<p>The following error codes may be generated in response to a
&lt;search&gt; verb.</p>
<ul>
<li><strong>404 (Not Found)</strong>: The class to be
searched does not exists.</li>
<li><strong>403 (Forbidden)</strong>: The user is not
authorized to search this class.</li>
<li><strong>405 (Not Allowed)</strong>: The client sent a
&lt;search&gt; verb to an object server or instance.</li>
<li><strong>406 (Not Acceptable)</strong>: The client sent
an &lt;search&gt; verb containing attributes that are not
defined for the class, or with attribute values that are
of the wrong type.</li>
</ul>
</section3>
<section3 topic='Examples'>
<p>To search for Boxcar instances carrying coal, the client
would send the following stanza to the Boxcar class:</p>
<example caption='Searching for Instances'><![CDATA[
<iq type='get'
id='joap_search_1'
from='Client@example.com'
to='Boxcar@trainset.example.com'>
<search xmlns='jabber:iq:joap'>
<attribute>
<name>contents</name>
<value><string>coal</string></value>
</attribute>
</search>
</iq>]]></example>
<p>The Boxcar class would return a list of all matching
instances:</p>
<example caption='Search Results'><![CDATA[
<iq type='result'
id='joap_search_1'
from='Boxcar@trainset.example.com'
to='Client@example.com'>
<search xmlns='jabber:iq:joap'>
<item>Boxcar@trainset.example.com/195</item>
<item>Boxcar@trainset.example.com/35</item>
<item>Boxcar@trainset.example.com/681</item>
</search>
</iq>]]></example>
<p>To get a list of all Building instances, the client would
send an empty &lt;search&gt; verb, as follows:</p>
<example caption='Listing All Instances of a Class'><![CDATA[
<iq type='get'
id='joap_search_2'
from='Client@example.com'
to='Building@trainset.example.com'>
<search xmlns='jabber:iq:joap' />
</iq>]]></example>
<p>The Building class would return the following stanza:</p>
<example caption='List Results'><![CDATA[
<iq type='result'
id='joap_search_2'
from='Building@trainset.example.com'
to='Client@example.com'>
<search xmlns='jabber:iq:joap'>
<item>Building@trainset.example.com/Courthouse</item>
<item>Station@trainset.example.com/Paddington</item>
<item>Station@trainset.example.com/GareDeLyon</item>
<item>Building@trainset.example.com/SmithFamilyHome</item>
</search>
</iq>]]></example>
<p>Note that the class returns instances of subclasses, as
well as direct instances of the class.</p>
</section3>
</section2>
<section2 topic='Method Calls'>
<p>Method calls in JOAP are simply XML-RPC calls, as defined in
XEP-0009.<note>XEP-0009 leaves some open questions as to use
of widely-defined extensions to the XML-RPC standard, such as
the &lt;nil&gt; type.</note> To call a method
on an object, the client simply sends an XML-RPC message to that
object. Method calls must match the parameters as defined in
the method definition returned by the &lt;describe&gt;
verb.</p>
<p>Method names must be the exact method name as returned by
&lt;describe&gt;. No class or instance identifier prefix (with
"." or ":") is used.</p>
<p>Note, also, that the addressee of the method call, that is,
the object that defines the method, is not specified as a
parameter of the method, as it is in some programming
languages. The addressee of the method is implicit in the
address to which the method was sent.</p>
<section3 topic='Examples'>
<p>To start the event log on the train set server, the client
would send the following stanza:</p>
<example caption='Method Call on an Object Server'><![CDATA[
<iq type='set'
id='joap_xmlrpc_1'
from='Client@example.com'
to='trainset.example.com'>
<query xmlns='jabber:iq:rpc'>
<methodCall>
<methodName>startLogging</methodName>
</methodCall>
</query>
</iq>]]></example>
<p>The object server would respond with the following results:</p>
<example