XEP-0075: Jabber Object Access Protocol (JOAP)

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.

WARNING: This document has been automatically Deferred after 12 months of inactivity in its previous Experimental state. Implementation of the protocol described herein is not recommended for production systems. However, exploratory implementations are encouraged to resume the standards process.

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.

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:

Built-in authentication. 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.

Global namespace. Jabber allows namespacing
of addresses according to domain names. This allows objects to
be accessed globally, according to authorization rules.

An asynchronous messaging model. 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.

Cross-enterprise messaging. 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.

Message routing. 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.

Factoring network connections out of
scalability. 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.

Language independence. Jabber protocol
implementations exist for Java, C, and C++ as well as a number
of scripting languages such as Perl and Python.

Platform independence. The Jabber protocol
is implemented on most major modern platforms.

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.

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.

A scheme for defining the addresses of object servers,
classes, and instances (collectively known as
"objects").

A set of message stanzas in the jabber:iq:joap
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.

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.

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.

For example:

Employee@payroll.example.com - An employee class
at the payroll.example.com server.

Beside uniqueness and XMPP compliance, no further requirements are
made on class names. However, good design suggests mnemonic names.

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.

JOAP allows for no relative addressing of classes. Classes
are always referred to by their full address (node identifier
plus domain identifier).

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.

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:

Customer@videorental.example.net/JohnSmith - A
customer named "John Smith" (not necessarily the
same person as the above employee!).

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.

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.

As with other resource identifiers, instance identifiers are
case-sensitive.

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:

Date@calendar.example.net/2003-01-26 -- The date
January 26th, 2003.

City@canada.example.com/Montréal,QC -- The city
of Montréal, in the province of Québec.

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).

A method is a unit of behavior that makes up part of an
object. Methods in JOAP are compatible with XML-RPC [3], as
specified in Jabber-RPC (XEP-0009) [1]. In particular, methods have a name, a
return type, and 0 or more parameters, each of which has a
type.

The one exception to XML-RPC compatibility is that method
names for JOAP are restricted to the characters
[a-zA-z0-9_]. [4]

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.

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.

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.

For example, if Boxcar@trainset.example.com is a
subclass of Car@trainset.example.com, then
Boxcar@trainset.example.com/569 can be used as a
method parameter, or set as an attribute, where
Car@trainset.example.com is the defined type.

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.

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
Employee@payroll.example.com class could have an
attribute of type Job@hr.example.com.

This section defines the Jabber stanzas that make up the JOAP
protocol.

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.

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.

The <describe> verb requests the interface -- that is, methods,
attributes, and classes -- of a given object server or class. The IQ
type is "get".

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.

A flag indicating if the attribute is an attribute of the
class itself, or of individual instances.

A flag indicating if the attribute is writable.

A flag indicating if the attribute is required.

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).

The attribute definitions returned to a client should
include only attributes the user is authorized to access.

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.

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.

In addition, no provision is made to define which
superclass actually implements any methods or attributes
defined.

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. [6]

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. [8]

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.

The following are some common error codes may be generated
in response to an <add> verb.

404 (Not Found): The class for which an
instance is to be instantiated does not exists.

403 (Forbidden): The user is not
authorized to instantiate an instance of this class.

405 (Not Allowed): The client sent an
<add> verb to something that isn't a class.

406 (Not Acceptable): 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.

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.

The IQ is of type "set".

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.

The following error codes may be generated in response to a
<edit> verb.

404 (Not Found): The object to be
edited does not exists.

403 (Forbidden): The user is not
authorized to edit this object, or to change one of the
attributes specified in the <edit> request.

406 (Not Acceptable): 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.

How attribute values are specified for matching depends on
the type of the attribute.

For numeric types (<int>, <double>),
<boolean>, and <dateTime.iso8601>, values match
if they are exactly equal.

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".

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").

For instance addresses, a search value matches an
attribute value if they are exactly equal.

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.

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.

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.

Whether a class returns instances of subclasses that reside
on other object servers is implementation-dependent.
[10]

Classes cannot be searched on attributes that are defined
only in subclasses; for example, a search for the attribute
"contents" sent to the
Car@trainset.example.com class should result in a
406 (Not Acceptable) error.

Method calls in JOAP are simply XML-RPC calls, as defined in
XEP-0009. [11] 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.

Method names must be the exact method name as returned by
<describe>. No class or instance identifier prefix (with
"." or ":") is used.

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.

A more complex example would be an interface to a relational database
server, such as Oracle, PostgreSQL, or mySQL. The object server would
represent a single database within the database server. Each table in
the database would be represented by a class with no class attributes
or methods. Each row in the database would be an instance of its
table's class, with attributes but no methods.

With JOAP, application developers can create the last two
segments with a JOAP interface. User-interface clients can use
JOAP to access and manipulate the business objects in a
business object server. In turn, the business objects can use
JOAP to manipulate underlying database objects in the data
storage layer (perhaps implemented using a relational database
interface, as defined above).

Jabber protocols typically define a base set of functionality
for a component to provide. Implementers often want to provide
specialized, fine-grained control of the component that is not
part of the core functionality of a component. For example,
the implementer may wish to allow administrators to get
metrics on a component, enable or review logs, note error
situations, or configure the component remotely. [12]

A component can provide an additional JOAP interface, along
with its regular protocol-specific interface, to enable this
kind of control functionality. Implementers can in this way
provide implementation-specific functionality in an open
way.

For example, if conference.example.com is
a MUC component, control.conference.example.com might
be a JOAP component with access to the internal data
structures of the MUC component. A conference room addressed
in the MUC component as
ModelTrains@conference.example.com might be addressed
in the JOAP component as
Room@control.conference.example.com/ModelTrains.

There are a number of existing distributed object systems,
such as SOAP, CORBA, distributed OLE, Enterprise Java Beans,
etc.

It would be reasonable to create gateways for these object
systems or object servers implementing their protocols using
JOAP. JOAP could also be used to allow disparate object
systems to communicate through a common protocol.

Authorization for users to access and manipulate objects and
attributes in JOAP is fine-grained; object servers can return
error codes to indicate a lack of authorization for any given
attribute, object, or method.

No provision is made to define a user's authorization for an
object, attribute, or method. Implicit authorization is
outlined with the results of the <describe> verb.

For attributes, if a user is unauthorized to <read> the
attribute, the object server should not return a definition of
the attribute in the <describe> results.

If a user is unauthorized to <edit> an attribute, the
object server should note that the the attribute is not
writable in the <describe> results.

If a user is unauthorized to execute a method, the object
server should not return a definition of the attribute in
the <describe> results.

For classes that the user is not allowed to access at all,
the object server should not return a reference to that
class in the <describe> results for the object
server.

For instances that the user is not allowed to access at
all, the object server should not return references to that
instance in <search> results.

No provision is made in the JOAP protocol for providing
privacy and confidentiality in JOAP conversations. This is
left up to existing, more general Jabber protocols and
extensions.

Confidentiality from external, non-Jabber observers can be
obtained using transport-layer security (TLS) in all legs of
the Jabber path -- from client to server to (potentially)
another server to the object server component.

Due to the nature of the JOAP addressing scheme, however,
perfect confidentiality cannot be preserved. Even if the
contents of an IQ packet are encrypted, the address of the
object the packet is sent to -- e.g.,
Tips@whistleblower.example.org/NuclearRegulatoryInfractions
-- will reveal some information about the JOAP
conversation which could be harmful to the user.

The presence mechanism provided by Jabber is currently not
integrated into the JOAP protocol. It would be relatively
easy to incorporate an observation mechanism, based on
presence, that would enable JOAP clients to request state
updates on JOAP instances. It is currently an open question
as to whether this would be genuinely useful, or merely a
"gee-whiz" add-on that needlessly complicates
implementation of the JOAP protocol.

More sophisticated distributed object protocol mechanisms,
such as transactions, are not addressed in this
specification.

The JOAP addressing mechanism restricts the type of Jabber
entity that can act as an object server. A Jabber instant
messaging client, for example, is normally addressed with
username and resource, such as
'AJabberUser@example.com/Home'. This address has no place
to hang the class and instance identifiers to allow
JOAP interactions.

Additionally, the JOAP addressing mechanism inhibits
letting components that already use the node and resource
identifier parts of their addresses, such as multi-user
chat (MUC) services. This restriction can be worked around by
providing corresponding JOAP components for existing Jabber
components.

An additional type for object references may be called
for.

The addition of the widely used <nil> XML-RPC data
type may be called for.

Searching is fairly rudimentary; a full boolean logic (and,
or, not) may be necessary to provide rich searching.

There is no indication in class descriptions of the
inheritance hierarchy of the class, or which superclass's
implementation of a method the class may use. This is an
implementation decision, and it seems counterproductive to
force any given inheritance method on the implementer.

Some functionality will be expensive using JOAP. An example
might be finding all Cars in a Train and adding them to
another Train. In our example, this would require one IQ to
get the train's cars, and N many other IQs to update each
Car. A batching mechanism -- being able to send multiple
updates in one IQ message -- would make this somewhat less
chatty. However, this functionality may be better addressed by
a global Jabber batching mechanism, rather than
special-purpose batching just for JOAP.

A more appropriate term than <verb> may be necessary
to describe the different types of IQs that make up the JOAP
namespace.

The names of the verbs come from the so-called basic READ
data-manipulation functions: read, edit, add, delete. A more
SQL-oriented set of names might be SELECT, UPDATE, INSERT,
DELETE. A set of names from C-related object languages would
be get, set, new, destroy or delete.

No mechanism is provided to describe the range of an
attribute. For example, if an attribute can only be an integer
less than 10, or a string in the set {'open', 'closed'}, there
is no allowance for describing this in JOAP.

Currently, struct and array attributes and
parameters are described just with the "struct" and
"array" types, and no definition is given of their
parts' types, names, or semantics. It may be valuable to
expand JOAP type descriptions to also describe the members of
a struct or array.

Because JOAP requires some significant examples to define the
protocol, an example domain was developed to provide
consistency. Readers familiar with UML may find the following diagram
useful to illustrate some of the fine points of JOAP listed
above.

Appendix C: Legal Notices

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

2. 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.

4. 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.

5. 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.

6. Flattening the class
interface reduces the need for making multiple
"describe" verb calls just to find the interface
for one class.

7. 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.

8. This allows clients to cheaply retrieve
meta-information about an instance that may have exceptionally
large data, such as bin64-encoded file data.

9. This is to allow updates that alter the unique
key or attribute of an instance that determine its instance
identifier.

10. 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.

11. XEP-0009 leaves some open questions as to use
of widely-defined extensions to the XML-RPC standard, such as
the <nil> type.

12. Most
Jabber components currently define Web interfaces, or
command-line scripts, to perform this kind of
control.