JOAP::Addresses - Documentation-only package about JOAP addresses
[N/A]
JOAP defines a precise addressing scheme for object servers, classes, and instances. This document describes that addressing scheme in detail.
One of the cool things about JOAP is that object servers, classes, and instances are all directly addressable on the Jabber network. Clients send messages directly to the object that will handle the message; Jabber's routing schemes work to ensure that the proper object gets the message.
This document describes the form of Jabber addresses in general, and the form of JOAP addresses in particular.
Every node on the Jabber network has an address with the following format:
[[node identifier]@][domain identifier][/resource identifier]
The resource identifier part is optional. The node identifier part is also optional, if the resource identifier is not present. Each part is limited to 255 characters, and the node identifier and domain identifier are both case-independent.
Each object server has an address consisting of only a domain identifier. This is normally only used for Jabber servers or components. In general, object servers are implemented as Jabber components.
Some example object server addresses:
payroll.example.net jukebox.example.org accounting.western-region.example.com accounting.eastern-region.example.com object.server.in.a.much.divided.subdomain.example.com
Class addresses add a node identifier to the object server they're located on. The node identifier is the name of the class, preferably in some human-readable form. Examples:
Employee@payroll.example.net Song@jukebox.example.org Part@autoshop.example.com Part@theater.example.net
Note that class names are scoped by the object server name. In the last two examples, 'Part@autoshop.example.com' may be a class of automobile parts like mufflers or carburators, but 'Part@theater.example.net' might be a speaking part in a play. In general, you can't assume that just because two classes have the same node identifier, they have the same attributes and methods.
It is possible to explicitly describe a relationship between two classes on different object servers by making one class a subclass of the other.
In the JOAP Perl library, it's possible to map a Perl class name, like 'Instrument::Drum::Bongo', to a JOAP class name, like 'Bongo'.
If two classes, like 'Postage::Address' and 'Memory::Address', have similar names, you may want to use some kind of prefix to differentiate them. Tradition in Jabber uses intercaps to separate parts of a name:
PostageAddress@computer-assembly.example.com MemoryAddress@computer-assembly.example.com
Remember, though, that class names are case-insensitive, so multiple class names should be distinct regardless of case.
Instances JOAP are addressed by taking the name of the class the instance is a direct instance of, and adding a unique identifier as the resource part. For example:
Room@hotel.example.com/103 Element@periodic-table.example.net/103 Person@myserver.example.org/Prodromou,Evan
The instance identifier is normally a unique mnemonic identifier for the instance. It's opaque to clients; you shouldn't assume anything about the structure of the instance based on the instance identifier.
Note that, in JOAP land, the namespace of an instance identifier is the class name, and that the first two examples are addresses for two distinct instance objects (a hotel room and an element of the periodic table), even though they have the same instance identifier.
This is also true for classes that have an inheritance relationship. For example, even if 'Manager' is a subclass of 'Employee', these two instances are distinct:
Employee@payroll.example.net/Smith,HowardJ. Manager@payroll.example.net/Smith,HowardJ.
With one notable exception, there is no relative addressing in the JOAP Perl library. All addresses returned by library will be full addresses as described above. All methods in the library expect full addresses as parameters.
The notable exception is in the JOAP::Proxy::Package::Server class's ClassMap variable; see that class's documentation for details.
The addressing scheme is documented in more detail in the JOAP specification.
See JOAP for more information about JOAP and contact info for the author.
Evan Prodromou, <evan@prodromou.san-francisco.ca.us>
Copyright (c) 2003, Evan Prodromou <evan@prodromou.san-francisco.ca.us>.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
To install JOAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JOAP
CPAN shell
perl -MCPAN -e shell install JOAP
For more information on module installation, please visit the detailed CPAN module installation guide.