Evangelo Prodromou > JOAP-0.01 > JOAP

Download:
JOAP-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

JOAP - Perl extension for the Jabber Object Access Protocol (JOAP)

SYNOPSIS ^

    use Net::Jabber qw(Client);
    use JOAP;

    # have fun here. B-)

ABSTRACT ^

The Jabber Object Access Protocol (JOAP) allows object attributes and methods to be accessed over the Jabber network. This Perl package implements JOAP in Perl. It lets developers define their own JOAP servers and classes in Perl, and it also lets them use remote servers and classes in a transparent and Perlish way.

DESCRIPTION ^

This module is the entry-point for JOAP programming in Perl. Most of the interesting JOAP functionality is implemented in other packages. The SEE ALSO section below points out some important ones you should start with.

When loaded, this module sets up the Jabber libraries to be ready for JOAP. Most developers don't need to do much programming at the Jabber library level, since the JOAP libraries take care of most of this for you. But if you're interested, look at JOAP::NetJabber for more information.

This module also provides some important data marshalling services to other JOAP modules. You shouldn't need to worry about these in normal JOAP programming; they're documented here for reference by people working on this package. If you're not doing that, please jump to the "SEE ALSO" section to get started with JOAP.

Package Variables

The JOAP package has one package variable of any importance.

$JOAP::NS

This is a string representation of the JOAP XML namespace. When and if JOAP becomes a Jabber standard, this will be 'jabber:iq:joap'. Until then, this is set to a temporary namespace, as recommended by the JOAP specification. This lets us interoperate with other implementations that are experimenting with JOAP, without causing problems in the future if (when) the specification changes.

The other JOAP libraries use this variable pretty consistently.

Mucking around with this variable is done at your peril, and the peril of other software that talks JOAP to yours. Don't do it.

Class Methods

The JOAP package provides some data marshalling services that make it a little easier to convert Perl data to JOAP data and vice versa.

JOAP->encode($type, $pval)

Encode the Perl value $pval to a JOAP value of type $type. See JOAP::Types for a discussion of the JOAP type system. Returns a JOAP value element that can be used with JOAP-copy_value> below.

JOAP->decode($jval)

Decode the JOAP value $jval, and returns its Perl value. Since JOAP values contain type information, you don't need to pass in a type.

JOAP->copy_value($from, $to)

Copy JOAP value $from to JOAP value $to. This is kind of a hack, but I had a hard time making the Net::Jabber libraries take a JOAP value as an argument.

JOAP->value_type($jval)

Returns a string containing the name of the type of JOAP value $value. See JOAP::Types.

JOAP->coerce($type, $pval)

Gets a Perl value, Perl-equivalent to $pval, that will encode cleanly into a JOAP value of type $type. By "Perl-equivalent", I mean all the tricky stuff that happens when you evaluate a Perl value in different contexts.

For example,

     JOAP->coerce('boolean', '0 but true')

...will return '1', since that's the JOAP equivalent of the Perl boolean value of '0 but true'. On the other hand,

     JOAP->coerce('int', '54 horses')

...will return '54', since that's the JOAP equivalent of the integer value of '54 horses'.

     JOAP->coerce('dateTime.iso8601', time)

...will return the current time as an ISO 8601-formatted string.

The whole point here is to let Perl hackers do all the crazy, wigged-out and intuitive tricks they want with their custom JOAP code, and have it go out in clean and acceptable fashion onto the wire. It's probably a quixotic dream, but it works for a lot of stuff.

JOAP->int_to_datetime($int)

Converts (Perl) integer $int to an ISO 8601-formatted datetime string, where $int is considered in seconds-past-the-epoch, as is returned by "time" in perlfunc.

JOAP->array_to_datetime($arrayref)

Converts a reference to time array in "gmtime" in perlfunc format to a formatted ISO 8601 datetime string.

JOAP->datetime_to_array($datetime)

Converts a formatted ISO 8601 datetime string to a time array in "gmtime" in perlfunc format. Note that it returns an array, not a reference to an array.

EXPORT

None by default.

BUGS and CAVEATS ^

An important caveat is that JOAP is still an immature protocol, and this is an early, experimental implementation. You can do some interesting hacking with this package, but you should track the future development of the package, since it will probably go through a number of revisions in the near future.

The marshalling code is usable but still pretty shaky with compound types like arrays and structs, and doesn't handle object types well at all.

Badly-formatted datetimes (e.g., '19930207T120000Z') will be evaluated as integers, with some disturbing results. Be careful with datetimes.

SEE ALSO ^

If you're interested in creating a JOAP server, you should probably start off looking at JOAP::Server and JOAP::Server::Class.

If you're interested in creating a JOAP client, you will probably want to take a look at the documentation for JOAP::Proxy::Package::Server and JOAP::Proxy::Package::Class.

A discussion of the JOAP type system is in JOAP::Types.

Information on using 'raw' JOAP Jabber stanzas can be found in JOAP::NetJabber.

There's a Web page for this project on JabberStudio, which you can find here:

        http://joap-perl.jabberstudio.org/

You can file bug reports with the cool bug reporting facility here:

        http://www.jabberstudio.org/projects/joap-perl/bugs/

...and make feature requests here:

        http://www.jabberstudio.org/projects/joap-perl/features/

There's a mailing list which you can sign up for here:

        http://www.jabberstudio.org/cgi-bin/mailman/listinfo/joap-perl-dev/

Messages should be sent to joap-perl-dev@jabberstudio.org.

There's a Jabber conference for the project here:

        joap-perl@conference.jabberstudio.org

I can personally be contacted at evan@prodromou.san-francisco.ca.us by email, and at EvanProdromou@jabber.org by Jabber.

More information on Jabber itself can be found here:

        http://www.jabber.org/

The definition of the Jabber Object Access Protocol is here:

        http://www.jabber.org/jeps/jep-0075.html

This implementation conforms to version 0.3 of the protocol.

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: