JOAP::NetJabber - Documentation-only package about using Net::Jabber JOAP objects
use Net::Jabber qw(Client); use JOAP; my $iq = new Net::Jabber::IQ; my $read = $iq->NewQuery($JOAP::NS, 'read'); $read->SetName('gar');
The JOAP Perl package leverages off the excellent Jabber Perl library Net::Jabber. This documentation-only package describes how JOAP uses Net::Jabber, and how to do low-level JOAP stuff with Net::Jabber. It's probably only of interest to people hacking on this library itself or people extending -- nay, overextending -- this library.
First off, nothing in this document is crucial to anyone using the JOAP Perl libraries. Don't get confused or querulous about what's in here. It requires some deep knowledge of the Net::Jabber libraries and the Jabber protocol itself, as well as of the JOAP protocol.
Users of the JOAP library only have to use Net::Jabber for one thing: to set up the connection for JOAP proxies. See JOAP::Proxy for more information.
The JOAP library uses -- or, really, abuses -- the Net::Jabber library. Net::Jabber allows external libraries to map autoloaded methods to a particular XML namespace. We use that to add methods to Jabber-level objects in the JOAP namespace, so we don't go insane trying to fiddle with all the details.
Each JOAP object is a Net::Jabber::Query. The base queries -- JOAP verbs, children of an Net::Jabber::IQ -- are all in the $JOAP::NS namespace. This may change, so I'm not writing it out all over the place here. The stuff that is children of the base queries -- attributes, timestamps, etc. -- are in munged-up internal sub-parts of the $JOAP::NS. See Net::Jabber::Namespaces for why this is needed.
$JOAP::NS
JOAP IQs have queries with tagnames like 'read', 'edit', 'add', etc. Most namespaces use the tagname 'query', though, so it's a little difficult to get around the Net::Jabber default. The mechanism I've found to work is this:
# create an IQ my $iq = new Net::Jabber::IQ; # add a new query in the JOAP namespace with the given query tagname my $read = $iq->NewQuery($JOAP::NS, 'read');
Also note that IQ's Reply() method leaves in all the children of a query, which you probably don't want to do. JOAP::Server::Object defines a reply() method that works better.
Reply()
reply()
The methods created are too numerous to go into here. Instead, I borrow a page from the Net::Jabber handbook and merely give tables of functions that can be used to manipulate JOAP objects. See Net::Jabber::Query for an explanation of the format of these tables.
Note also that at this level there's no automagic coercion of datatypes; parameters to these methods should be in exactly the right format to go on the wire.
Type Get Set Defined ======= ================ ================ ================== array GetName() SetName() DefinedName() master GetRead() SetRead()
See "attributes" for more info on contents of attributes.
Type Get Set Defined ======= ================ ================ ================== children GetAttribute() AddAttribute() DefinedAttribute() string GetTimestamp() SetTimestamp() DefinedTimestamp() master GetRead() SetRead()
Timestamps must be date/time values in ISO 8601 format; see <JOAP::Types> for details.
Type Get Set Defined ======= ================ ================ ================== children GetAttribute() AddAttribute() DefinedAttribute() master GetEdit() SetEdit()
Type Get Set Defined ======= ================ ================ ================== string GetNewAddress() SetNewAddress() DefinedNewAddress() master GetEdit() SetEdit()
The new address must be a valid JOAP address; see <JOAP::Addresses> for details.
Type Get Set Defined ======= ================ ================ ================== children GetAttribute() AddAttribute() DefinedAttribute() master GetAdd() SetAdd()
Type Get Set Defined ======= ================ ================ ================== string GetNewAddress() SetNewAddress() DefinedNewAddress() master GetAdd() SetAdd()
Delete requests don't have much in them.
Type Get Set Defined ======= ================ ================ ================== master GetDelete() SetDelete()
Delete responses don't have much in them, either.
Type Get Set Defined ======= ================ ================ ================== children GetAttribute() AddAttribute() DefinedAttribute() master GetSearch() SetSearch()
Type Get Set Defined ======= ================ ================ ================== array GetItem() SetItem() DefinedItem() master GetSearch() SetSearch()
Describe requests are pretty empty.
Type Get Set Defined ======= ================ ================ ================== master GetDescribe() SetDescribe()
See "attribute descriptions" for more info about the content of attribute descriptions.
See "method descriptions" for more info about the content of method descriptions.
Type Get Set Defined ======= ================ ================ ================== array GetDesc() SetDesc() DefinedDesc() array GetClass() SetClass() DefinedClass() array GetSuperclass() SetSuperclass() DefinedSuperclass() children GetAttributeDescription() AddAttributeDescription() DefinedAttributeDescription() children GetMethodDescription() AddMethodDescription() DefinedMethodDescription() string GetTimestamp() SetTimestamp() DefinedTimestamp() master GetDescribe() SetDescribe()
Both classes and superclasses must be valid JOAP class addresses; see JOAP::Addresses for details.
Type Get Set Defined ======= ================ ================ ================== string GetName() SetName() DefinedName() string GetValue() SetValue() DefinedValue() master GetAttribute() SetAttribute()
The value of an attribute is identical to a jabber:iq:rpc value object; see Net::Jabber::Query for details on the interface.
Type Get Set Defined ======= ================ ================ ================== string GetName() SetName() DefinedName() string GetType() SetType() DefinedType() array GetDesc() SetDesc() DefinedDesc() string GetRequired() SetRequired() DefinedRequired() string GetWritable() SetWritable() DefinedWritable() string GetAllocation() SetAllocation() DefinedAllocation() master GetAttributeDescription() SetAttributeDescription()
See "params" for further info on the params object.
Type Get Set Defined ======= ================ ================ ================== string GetName() SetName() DefinedName() string GetReturnType() SetReturnType() DefinedReturnType() array GetDesc() SetDesc() DefinedDesc() string GetAllocation() SetAllocation() DefinedAllocation() master GetMethodDescription() SetMethodDescription()
This is just a nested container; See "param" for further info on the param object.
Type Get Set Defined ======= ================ ================ ================== array GetParams() SetParams() object AddParam()
Type Get Set Defined ======= ================ ================ ================== string GetName() SetName() DefinedName() string GetType() SetType() DefinedType() array GetDesc() SetDesc() DefinedDesc() master GetParam() SetParam()
[N/A]
The JOAP documentation has general information about the library as well as bug-reporting and other contact addresses.
Net::Jabber and friends describe how to do Jabber programming. Net::Jabber::Namespaces describes the mechanism JOAP uses to insinuate itself into the Net::Jabber world.
Net::Jabber::Query defines how to build XML-RPC queries.
Evan Prodromou, <evan@prodromou.san-francisco.ca.us>
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
To install JOAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JOAP
CPAN shell
perl -MCPAN -e shell install JOAP
For more information on module installation, please visit the detailed CPAN module installation guide.