Author image Evangelo Prodromou

NAME

JOAP::NetJabber - Documentation-only package about using Net::Jabber JOAP objects

SYNOPSIS

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

   my $iq = new Net::Jabber::IQ;
   my $read = $iq->NewQuery($JOAP::NS, 'read');

   $read->SetName('gar');

ABSTRACT

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.

DESCRIPTION

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.

Building JOAP IQs

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

Autoload Methods

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.

read requests

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  array    GetName()         SetName()         DefinedName()
  master   GetRead()         SetRead()

read responses

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.

edit requests

See "attributes" for more info on contents of attributes.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  children GetAttribute()    AddAttribute()    DefinedAttribute()
  master   GetEdit()         SetEdit()

edit responses

  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.

add requests

See "attributes" for more info on contents of attributes.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  children GetAttribute()    AddAttribute()    DefinedAttribute()
  master   GetAdd()          SetAdd()

add responses

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  string   GetNewAddress()   SetNewAddress()   DefinedNewAddress()
  master   GetAdd()          SetAdd()

delete requests

Delete requests don't have much in them.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  master   GetDelete()       SetDelete()

delete responses

Delete responses don't have much in them, either.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  master   GetDelete()       SetDelete()

search requests

See "attributes" for more info on contents of attributes.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  children GetAttribute()    AddAttribute()    DefinedAttribute()
  master   GetSearch()       SetSearch()

search responses

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  array    GetItem()         SetItem()         DefinedItem()
  master   GetSearch()       SetSearch()

describe requests

Describe requests are pretty empty.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  master   GetDescribe()     SetDescribe()

describe responses

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.

attributes

  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.

attribute descriptions

  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()

method descriptions

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()

params

This is just a nested container; See "param" for further info on the param object.

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  array    GetParams()                         SetParams()
  object                     AddParam()

param

  Type     Get               Set               Defined
  =======  ================  ================  ==================
  string   GetName()         SetName()         DefinedName()
  string   GetType()         SetType()         DefinedType()
  array    GetDesc()         SetDesc()         DefinedDesc()
  master   GetParam()        SetParam()

EXPORT

[N/A]

SEE ALSO

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.

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