Evangelo Prodromou > JOAP-0.01 > JOAP::Addresses

Download:
JOAP-0.01.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

JOAP::Addresses - Documentation-only package about JOAP addresses

SYNOPSIS ^

  [N/A]

ABSTRACT ^

JOAP defines a precise addressing scheme for object servers, classes, and instances. This document describes that addressing scheme in detail.

DESCRIPTION ^

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.

Jabber Addresses

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.

Object Server Addresses

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

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.

Instance Addresses

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.

Relative Addressing

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.

EXPORT

[N/A]

SEE ALSO ^

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.

AUTHOR ^

Evan Prodromou, <evan@prodromou.san-francisco.ca.us>

COPYRIGHT AND LICENSE ^

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

syntax highlighting: