Evangelo Prodromou > JOAP-0.01 > JOAP::Server

Download:
JOAP-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

JOAP::Server - Base Class for JOAP Object Servers

SYNOPSIS ^

    package MyServer;
    use JOAP::Server;
    use base qw(JOAP::Server);
    use MyPerson;

    MyServer->Description(<<'END_OF_DESCRIPTION');
    A simple server to illustrate the features of the server Perl
    package. Serves one class, Person.
    END_OF_DESCRIPTION

    MyServer->Attributes(
        {
            %{ JOAP::Server->Attributes() }, # inherit defaults
              'logLevel' => { type => 'i4',
                              desc => 'Level of verbosity for logging.' }
        } );

    MyServer->Methods (
        {
            'log' => {
                returnType => 'boolean',
                params => [
                    {
                        name => 'message',
                          type => 'string',
                          desc => 'message to write to log file.'
                    }
                ],
                desc => 'Log the given message to the log file. Return true for success.'
            }
        });

    MyServer->Classes (
        {
            Person => 'MyPerson'
        });

    sub log {

        my($self) = shift;
        my($message) = shift;

        push @{$self->{messages}}, $message
          if ($self->logLevel > 0);

        return 1;
    }

    1;

    package main;

    # create a server with Net::Jabber::Component arguments

    my $srv = new MyServer(debuglevel => 0,
                           logLevel => 4, # JOAP object argument
                           debugtime => 1);

    # execute the server

    $srv->execute(hostname => 'example.com',
                  port => 7010,
                  componentname => 'joap.example.com',
                  secret => 'JOAP is K00l',
                  connectiontype => 'accept');

ABSTRACT ^

JOAP::Server is a base class for creating JOAP object servers. It handles the necessary Jabber component tasks, such as connecting to a Jabber server. Secondly, it routes JOAP and RPC messages to the appropriate objects. Finally, it acts as a JOAP object itself, exposing attributes and methods.

DESCRIPTION ^

This is an abstract base class that can be used to quickly and easily define a JOAP server, ready to run on the Jabber network. You shouldn't instantiate or use this package directly; instead, create a sub-class of JOAP::Server and muck around with it, instead.

There are three distinct interfaces to this class:

Component

The class (and subclasses) act as Jabber components, connecting to a Jabber server and fielding JOAP and RPC requests.

Container

It routes JOAP and RPC requests to classes and instances it serves, and logs requests and responses.

JOAP Object

It exposes its own attributes and methods through JOAP.

This POD describes these interfaces in order.

Component Interface

The class handles a subset of the interface defined for Net::Jabber::Component objects. I just added the ones that seemed the most valuable, and was too lazy to add more.

Package->new(attr1 => $value1, attr2 => $value2, ...)

This is a class method that acts as a constructor. The name-value pairs passed as arguments will be used to initialize both the JOAP::Server::Object part of the server, and the Net::Jabber::Component part.

See Net::Jabber::Component for the name and format of its constructor parameters.

$obj->execute(%named_args)

Executes and runs the Jabber component. This does pretty much everything you need your server to do: it connects to the upstream Jabber server, authenticates, and runs a data pump, receiving messages and handling them or dispatching them to the right object, then returning the results back upstream. If the connection fails, it will try to reconnect.

You really shouldn't bother with any other component stuff.

The named arguments are the same as used for the Net::Jabber::Component Execute method. Since this is the preferred way to start a JOAP::Server, I list the main ones here:

componentname

The name of this component, in domain-name format.

hostname

The upstream Jabber server's hostname.

port

The port that the upstream Jabber server is listening on for our connection.

secret

The secret password we need to use to tell the upstream Jabber server that we are who we say we are.

connectiontype

The type of component connection. Usually this should just be 'accept', meaning that the server is listening on a port to accept our connection.

$obj->connect(%named_args)

Connect to a host server. See Net::Jabber::Component for the proper named arguments.

Also, use execute instead.

$obj->disconnect(%named_args)

Disconnect from a host server. See Net::Jabber::Component for the proper named arguments.

Also, use execute instead.

$obj->connected(%named_args)

Check if we're still connected to the host server. See Net::Jabber::Component for the proper named arguments.

Also, use execute instead.

Container Interface

OK, well, this isn't really so much an interface as a set of behaviors, now that I think about it. The JOAP::Server instance routes important events to the object an event was sent to, using the "Container Interface" in JOAP::Server::Object to pass in and out requests and results.

Note that there's no way for the objects themselves to find out much about the server. This is by design -- I wanted to keep JOAP classes ignorant of their containing server, and have them concentrate on their own behavior. It seems to work out fine, and when necessary the classes can figure out important stuff like their own address from the incoming IQ fields.

JOAP::Server uses a class accessor to determine what Perl classes are exposed as JOAP classes by this server.

Classes($classmap)

This class mutator takes as a parameter a reference to a hashtable which maps JOAP class names to Perl module names that implement that class. Note that only the class name, and not the full class address, is used.

Modules specified in the class map are not automatically use'd. You need to include use statements in your subclass module for each module you expose.

The classes in the class map must expose the same Container interface as JOAP::Server::Class.

Log Format

JOAP::Server object log JOAP and RPC events by default. The logging mechanism is pretty loosey-goosey right now, but the basic log format is this:

    $timestamp : "$from" - "$to" : $request (@args) -> (@results) ($status)

Here the parts of the log format look like this:

$timestamp

An ISO 8601 timestamp when the results of an event were returned. See JOAP::Types for the format of a timestamp.

$from

The remote user who sent the request.

$to

The local object (object server, class, or instance) that the request was sent to.

$request

The type of request; one of 'read', 'edit', 'add', 'delete', 'search', 'describe', or 'method'.

@args

Any arguments that the request contained. The format of the args is request-dependent.

@results

The results that the object returned. Again, this is request dependent, and one of these days I'll get around to defining it fully. B-)

$status

The status of the request. If there was an error, this is the numeric error code returned to the requester. If not, this is the string "OK".

JOAP Object Interface

This interface is how subclasses of JOAP::Server declare their methods, attributes, and human-readable description to the library (and thence to the world).

Note that the Classes method listed above is also exposed as part of the server object's interface.

Description($string)

Sets the human-readable description of the object server, which is returned in 'describe' verbs. Note that JOAP allows multiple descriptions for different human languages; this implementation does not, but that may change in the future.

Attributes($hashref)

This sets the publicly available attributes for the object server. $hashref is a reference to a hashtable mapping attribute names to attribute descriptors. See JOAP::Descriptors for the format of this data structure.

Besides the fields listed there, the attribute descriptor can also contain the following fields:

getter
setter
accessor

These work in the same way as with JOAP::Server::Object, which see.

Methods($hashref)

This sets the publicly available methods for the object server. $hashref is a reference to a hashtable mapping method names to method descriptors; see JOAP::Descriptors for the format of method descriptors.

As well as the fields described normally for method descriptors, the following fields are also used:

function

This is the name of, or reference to, a function that acts as this method. If the field is not provided, the function with the same name in this package will be used.

Note that the JOAP::Server class itself exposes a couple of attributes by default, just for kicks. You can expose these attributes in your subclass server by interpolating the JOAP::Server-Attributes> hash into your own hash, as shown above in the synopsis.

EXPORT

None by default.

BUGS ^

I think the delegation mechanism is probably flipped around the wrong way. Instead of being a JOAP::Server::Object and containing a Net::Jabber::Component, it should probably be a Net::Jabber::Component and contain a single JOAP::Server::Object. But, y'know, no biggie.

The server isn't terribly robust -- it doesn't trap errors very well, nor does it recover from error situations with any measure of grace.

It's all single-threaded, which loses.

The server doesn't automagically use Perl modules exposed as classes, nor does it have a default mechanism for mapping class names to Perl modules.

SEE ALSO ^

JOAP contains general information about JOAP, as well as contact information for the author of this package.

JOAP::Server::Object goes into more detail about the container interface for JOAP objects.

JOAP::Server::Class is good for defining classes exposed by a JOAP server.

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: