|
|
|
|
<?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='<describe>'>
|
|
|
|
|
<p>The <describe> 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 <describe> 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><describe> 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
|
|
|
|
|
<describe> method to their class. This is for convenience
|
|
|
|
|
only; it is preferable to send <describe> 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 <describe> 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 <describe>
|
|
|
|
|
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='<read>'>
|
|
|
|
|
<p>The <read> 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 <read> 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 <read>. 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 <read> 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 <read> 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 <read>
|
|
|
|
|
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='<add>'>
|
|
|
|
|
<p>The <add> 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 <add> 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 <add> 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
|
|
|
|
|
<add> verb to something that isn't a class.</li>
|
|
|
|
|
<li><strong>406 (Not Acceptable)</strong>: The client sent an
|
|
|
|
|
<add> 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='<edit>'>
|
|
|
|
|
<p>The <edit> 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 <edit> verb.</p>
|
|
|
|
|
<p>The IQ is of type "set".</p>
|
|
|
|
|
<p>Leaving a given attribute out of an <edit> 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 <edit> Results'>
|
|
|
|
|
<p>If the results of an <edit> 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
|
|
|
|
|
<edit> 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 <edit> request.</li>
|
|
|
|
|
<li><strong>406 (Not Acceptable)</strong>: The client sent
|
|
|
|
|
an <edit> 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='<delete>'>
|
|
|
|
|
<p>The <delete> verb is used to delete an instance. The IQ
|
|
|
|
|
is of type "set". The <delete> 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
|
|
|
|
|
<delete> 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
|
|
|
|
|
<delete> 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='<search>'>
|
|
|
|
|
<p>The <search> verb allows rudimentary searching and
|
|
|
|
|
listing of instances in a class. The IQ is of type
|
|
|
|
|
"get".</p>
|
|
|
|
|
<p>The client sends a <search> 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 (<int>, <double>),
|
|
|
|
|
<boolean>, and <dateTime.iso8601>, values match
|
|
|
|
|
if they are exactly equal.</li>
|
|
|
|
|
<li>For <string> 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 <base64> 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 <struct> 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 <array> 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 <search>'>
|
|
|
|
|
<p>The semantics of an empty <search> 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
|
|
|
|
|
<search> 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
|
|
|
|
|
<search> verb to an object server or instance.</li>
|
|
|
|
|
<li><strong>406 (Not Acceptable)</strong>: The client sent
|
|
|
|
|
an <search> 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 <search> 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 <nil> 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 <describe>
|
|
|
|
|
verb.</p>
|
|
|
|
|
<p>Method names must be the exact method name as returned by
|
|
|
|
|
<describe>. 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>
|
|
|
