The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
JOAP-0.01
River stage zero No dependents
/ JOAP::Server::Object

NAME

JOAP::Server::Object - Base Class for Things Servable By JOAP Servers

SYNOPSIS

    [N/A]

ABSTRACT

This verbosely-named OO package -- sorry about that -- is the base class for object servers, classes, and instances inside a JOAP server. It is probably not such a hunky-dory idea to inherit from this class itself -- use JOAP::Server::Class or JOAP::Server instead. However, it does lay out the framework for how those classes works -- thus, this POD.

DESCRIPTION

When it comes down to it, JOAP is about defining objects and making their attributes and methods available across the Jabber network. This class does the meat of that.

(Unfortunate note: this is a Perl class for defining JOAP objects. It uses Perl attributes to make JOAP attributes, and Perl methods to make JOAP methods. The terminology is confusing, so I'll try and use the prefixes 'Perl' and 'JOAP' where possible.)

There are three interfaces for this module.

Container

This interface consists of a constructor and a set of 8 "handler" methods, which are appropriate for folks who want to create JOAP servers that can serve Perl classes (JOAP::Server is one piece of software that uses this interface).

Simple Subclass

This interface is a set of rules for defining data and methods in a Perl module that is a subclass of JOAP::Server::Object, so that it can be seen by the world as a JOAP class.

This interface is documented in JOAP::Server and JOAP::Server::Class for object servers and classes, respectively. It's repeated here for completeness.

Complex Subclass

This interface is a whole bunch of itty-bitty methods that subclasses can overload if they want to subvert the 'standard' way of defining a JOAP server class in Perl. It'd be appropriate for, say, creating gateways to other object systems, or having more robust and scalable systems written in Perl than the one implemented here.

The complex subclass interface is still in flux and remains undocumented for now.

Simple Subclass Interface

This interface is how subclasses declare their methods, attributes, and human-readable description to the library. JOAP::Server::Object uses this information to validate incoming requests, and to format outgoing responses. By using this interface, subclasses cut down on the amount of JOAP-level hoohaw they have to deal with, and can concentrate on application-specific logic that deals with marshalled Perl values.

Application code SHOULD NOT subclass from JOAP::Server::Object directly. Use JOAP::Server for object servers, and JOAP::Server::Class for classes and their instances.

Description($string)

Sets the human-readable description of the object, 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. $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

This is the name of, or a reference to, a method that returns the value of the attribute. If no getter is defined, the method in this package with the same name as the attribute is used. If no such method is defined, an autoloaded method is defined at runtime (see "Autoloaded Accessors" below for details).

setter

This is the name of, or a reference to, a method that sets the value of the attribute. If no setter is defined, the method in this package with the same name as the attribute is used. If no such method is defined, an autoloaded method is defined at runtime (see "Autoloaded Accessors" below for details).

accessor

This is the name of, or a reference to, a method that acts as both 'getter' and 'setter'.

Methods($hashref)

This sets the publicly available methods for the class. $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.

Container Interface

The container interface is made up of one constructor, new, and eight "event" methods, to be called for events (presumably, when IQs representing the events come in over a Jabber network, although it's perfectly acceptable to use them for testing, too (or whatever)).

Package->new(attrib1 => 'value 1', attrib2 => 'value 2', ...)

This creates a new object that's ready to receive events. The attributes should be writable attributes declared in the package's Attributes class variable.

$obj->on_iq($iq)

Main dispatcher for Jabber IQ stanzas. The default implementation checks the query tag and namespace and calls the more appropriate specific event handler.

It returns a Jabber IQ stanza as a reply.

In general, containers should probably just call this, and let objects do their own dispatching.

$obj->on_describe($iq)

This method takes an IQ that should be a JOAP 'describe' verb, and returns a 'describe' verb containing the object's description.

The default behavior is to return a description with all attributes and methods, as well as a timestamp. Subclasses like ::Server and ::Class add superclass or class information, as necessary.

It returns a Jabber IQ stanza as describe reply.

$obj->on_read($iq)

This method responds to a 'read' verb with the requested attributes. The default implementation validates that requested attribute names are appropriate, and then uses configured or autoloaded accessors to determine the values of the attributes and returns them. If no attribute names are passed in, it returns a default set of attributes for the object.

It returns a Jabber IQ stanza as describe reply.

$obj->on_edit($iq)

Responds to an 'edit' verb. The default implementation checks that the incoming attribute names and values are acceptable, and uses configured or autoloaded mutators to set the values of the attributes.

As with other event handlers, this method returns a result IQ.

$obj->on_add($iq)

Responds to an 'add' verb. The default implementation returns an error IQ, as only JOAP class objects respond to 'add'. The JOAP::Server::Class package overloads this to create and store a new instance.

As with other event handlers, this method returns a result IQ.

$obj->on_search($iq)

Responds to a 'search' verb. The default implementation returns an error IQ, as only JOAP class objects respond to 'search'. The JOAP::Server::Class package overloads this to search for instances matching the search criteria specified in the IQ.

This method returns a result IQ.

$obj->on_delete($iq)

Responds to a 'delete' verb. The default implementation returns an error IQ, as only JOAP class objects respond to 'search'. The JOAP::Server::Class package overloads this to delete an instance.

This method returns a result IQ.

$obj->on_method($iq)

Responds to a 'jabber:iq:rpc' RPC method. The default implementation checks that the method is declared in the Methods class variable, and that the parameters of the IQ match the number and types of the declared parameters. It then calls the declared or eponymous function for the method, and returns the results.

If the function throws an Error, the value and text of the error are returned as an XML-RPC faultCode and faultString respectively.

This method returns a 'jabber:iq:rpc' result IQ.

Autoloaded Accessors

If a getter or setter or accessor is not defined for an attribute named in the Attributes map, the JOAP server libraries try to use a function by the same name as a Perl method to retrieve or set the attribute. If no Perl method by the same name is defined, the library creates a method to act as an accessor. This happens when the attribute is first used.

The default autoloaded accessor for instance attributes will store the attribute value as a field in the instance. For class attributes, the value will be stored as a symbol in the class package.

You can use this for attributes that are calculated from the values of other attributes, or to create side-effects from getting or setting an attribute.

It's generally better practice to use accessors for attributes in your custom code, rather than using the instance fields or class variables directly.

EXPORT

None by default.

BUGS

The default methods go poking around in subclasses to find classes, attributes, methods, and so forth. This is probably the Wrong Thing and will have Perl OO fanatics crawling all over me.

There's not a lot of validation of the input to the Simple Subclass interface. This lets simple typos cause unexpected and difficult-to-trace errors at run time rather than load time.

Using huge hashes-of-hashes and lists-of-hashes and stuff to do the metadata is kind of clunky. I might try and figger out Perl-level attributes (like 'lock' and 'method') to do these declarations instead.

The complex subclass interface is untested, undocumented, and probably insufficient.

The metadata stuff doesn't really handle Perl-level inheritance well. You have to explicitly declare all attributes and methods, even if you have a Perl superclass that already declares most or some of them. This is probly the Wrong Thing, also.

SEE ALSO

Unless you really really have to, and you really really know what you're doing, you probably shouldn't use this class directly. Most people will need to use JOAP::Server::Class, and folks creating new JOAP servers would want to use JOAP::Server.

Look at Error to see how to throw an error from custom code.

Net::Jabber::IQ contains more information on handling IQ stanzas.

JOAP contains more general information, as well as contact information 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