# JOAP::Addresses.pm - Documentation-only package about JOAP addresses
#
# 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

# tag: documentation-only package about JOAP addresses

__END__

=head1 NAME

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

=head1 SYNOPSIS

  [N/A]

=head1 ABSTRACT

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

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

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

=head2 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

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

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

=head2 Relative Addressing

With one notable exception, there is B<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 L<JOAP::Proxy::Package::Server>
class's ClassMap variable; see that class's documentation for details.

=head2 EXPORT

[N/A]

=head1 SEE ALSO

The addressing scheme is documented in more detail in the JOAP
specification.

See L<JOAP> for more information about JOAP and contact info for the
author.

=head1 AUTHOR

Evan Prodromou, E<lt>evan@prodromou.san-francisco.ca.usE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2003, Evan Prodromou E<lt>evan@prodromou.san-francisco.ca.usE<gt>.

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

=cut
