JOAP::Proxy::Class - Class for client-side proxy objects of JOAP classes
use JOAP::Proxy; use JOAP::Proxy::Class; # do Net::Jabber connection stuff here... $con = get_jabber_connection(); # You work this out # set the Jabber connection JOAP::Proxy->Connection($con); # get an object that represents a remote class $fooclass = JOAP::Proxy::Class->get('Foo@joap.example.net'); # update class attributes with server values $fooclass->refresh; # get an attribute value with the automagic accessor my $height = $fooclass->height; # set an attribute with the automagic accessor $fooclass->height($height + 1); # save class attributes to server $fooclass->save; # call a class method, with automagic method thingy $fooclass->reindex_all_frozzes('upwards'); # create a new instance my $foo = $fooclass->add(name => 'gar', drink => 'beaujolais'); # search for instances matching criteria my @matches = $fooclass->search(name => 'troyd');
This class is for proxies to JOAP classes. The proxy is a Perl object, not a class.
This class provides client-side access to the attributes, methods, and superclasses of a remote JOAP class. In general, it's preferable to use the JOAP::Proxy::Package::Class class instead.
This module is mainly useful if you don't know the address of the class at programming time; for quick one-off scripts where you don't feel like setting up a local Perl module for the class; and for scripts that work with the metadata of a class, like the joappxgen proxy code generator.
Most of the interface is inherited from various superclasses, but I document it here for convenience. For terminology, I try to use 'remote' for JOAP classes, instances, attributes and methods of the remote class or instance, and 'local' for methods of the local Perl package or instance, as well as instances of this class, etc., when I think the meaning is unclear.
One last thing: it's essential to set the Connection class attribute of the JOAP::Proxy class before using any of the methods in this package (except maybe Address). See JOAP::Proxy for more information.
Connection
Address
There's only one class method of any significance.
Returns a proxy version of the class at $class_address as an Perl object. The class attributes will be populated with its current values, and metadata will also be stored.
See JOAP::Addresses for more information on properly-formatted addresses.
These are methods on the Perl proxy object that represents the remote class.
These are methods you use to manipulate the data itself.
Reads the remote class attributes and caches them. If the metadata has not already been read, will also get that stuff, too.
In general, calling this method on the class before doing anything else is a good idea.
Saves the cached values of the class attributes to the remote server.
Adds a new JOAP instance and returns a proxy version as an instance of JOAP::Proxy::Instance. All required, writable attributes of the JOAP class must be present for it to work. You can include other instance attributes, also, but they must be writable.
Returns a list of addresses of all JOAP instances that match all the search specifications. The specifications are logically ANDed -- only instances that match all specification values will be returned. An example:
my @rectangles = Shape->search(sides => 4, angle => 90.0); foreach my $address (@rectangles) { my $rect = Shape->get($address); $rect->draw(); }
The semantics of the spec values is somewhat complicated -- see the JOAP specification for full details. In general, numeric and date types are matched exactly, while string types are matched if the spec value is a substring of the instance value.
Class attributes cannot be used as arguments to search().
search()
As a special case, search() with no arguments returns a list of all instances.
These methods return information about the structure of the class. It's generally a bad idea to use them as mutators (with arguments), unless you really really know what you're doing.
The address of the remote class this object is a proxy for.
Returns a reference to a hashtable mapping attribute names to attribute descriptors. See JOAP::Descriptors for more information on these data structures.
Returns a reference to a hashtable mapping method names to method descriptors. See JOAP::Descriptors for more information on these data structures.
The date and time that the class structure description was downloaded from the remote class. It's in ISO 8601 format; see JOAP::Types for details.
Note that this is also used internally as a flag to indicate that the class structure has been downloaded at all. If you set this attribute, without setting all the other instrospection attributes, bad things will most definitely occur.
A human-readable general description of the purpose and behavior of the class.
A reference to a list of addresses of remote classes that are superclasses of this class. This implies no local hierarchy of classes; it's only here to make typing decisions. It's currently not used in the internals of the proxy code.
As with other JOAP::Proxy classes, you can just go blithely around using accessors, mutators, and remote methods of the remote class really having to write any code for them.
For attributes, an eponymous ("same named") accessor will be autoloaded that will return the value of the attribute.
my $gar = $fooclass->gar;
If the attribute is writable, the same local method can be used as a mutator by passing a single value as the argument to the method.
$fooclass->gar('gar gar gar!');
Calling an accessor for an instance attribute on a class will cause a runtime error. So don't do that.
For remote methods, an eponymous local method is autoloaded that takes the same arguments and has the same return type as the remote method. This works for both class methods.
$fooclass->reindex_all_frozzes('upward');
A runtime error will be thrown if you call an instance method on a class object.
Note that if there are remote methods or attributes that have the same name as one of the above built-in methods, they won't work. Similarly, if a remote method and a remote attribute have the same name, the remote method will be used.
There are also some internal methods that may cause interference with remote methods and attributes.
None by default.
The class proxy object is not a Perl class.
The thread-safety attributes aren't specified for methods defined in this package nor for autoloaded methods.
There's currently no workaround for name clashes between attributes and methods and between local built-in methods and either of these.
There are probly lots more bugs lurking silently.
An easier, more Perlish, and more efficient mechanism for proxying remote classes can be found in JOAP::Proxy::Package::Class.
You should see JOAP::Proxy to figure out how to make your initial Jabber connection.
The add() method creates instances of the JOAP::Proxy::Instance class.
add()
JOAP::Types has more info on JOAP data types.
JOAP::Descriptors has more info on the structure of attribute and method descriptors. JOAP::Addresses has some clues about the structure of JOAP addresses.
There's more information in the JOAP documentation about how to contact the author of this package.
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.