JOAP::Proxy::Class - Class for client-side proxy objects of JOAP classes
use JOAP::Proxy; use JOAP::Proxy::Instance; # 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 $foo = JOAP::Proxy::Instance->get('Foo@joap.example.net/gar'); # refresh instance with attribute values from server $foo->refresh; # read an instance attribute using the Magic Accessor my $name = $foo->name; # set an instance attribute (did I mention the magic accessors?) $foo->name('Murgatroyd'); # save to the server $foo->save; # call an instance method $foo->scratch_where_it_itches(1, 2, 3); # delete an instance $foo->delete;
This class is for proxies to JOAP instance.
This class provides client-side access to the attributes, methods, and superclasses of a remote JOAP instance. In general, it's preferable to use the JOAP::Proxy::Package::Class package to make real Perl packages for remote classes, and have instances be instances of their class's class. But if you want to be difficult, use this package instead.
This module is mainly useful if you don't have information about the instance's class at programming time, and for quick one-off scripts where you don't feel like setting up a local Perl module for the class.
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 instance at $inst_address as an Perl object. The instance's 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 instance.
These are methods you use to manipulate the data itself.
Reads the remote instance attributes and caches them. If the metadata has not already been read, will also get that stuff, too.
Saves the cached values of the instance attributes to the remote server.
Delete the remote instance. The local proxy will still have all its attributes, so you can query them, but it will no longer be "linked" to the remote instance. Calling remote methods, or any of the data manipulation methods, will most likely result in an error.
These methods return information about the structure of the instance. 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 instance 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 instance 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 instance 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 the JOAP instance is an instance of.
A reference to a list of addresses of remote classes that are superclasses of this instance's JOAP 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 = $foo->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.
$foo->gar('gar gar gar!');
Calling an accessor for a class attribute on a JOAP::Proxy::Instance 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.
$fooclass->reindex_all_frozzes('upward');
A runtime error will be thrown if you call a class method on a JOAP::Proxy::Instance 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.
There's a lot of wasteful overhead in storing the metadata in each instance; smart programmers will use JOAP::Proxy::Package::Class for regular use.
You can't get at class data or methods.
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 instances can be found in JOAP::Proxy::Package::Class.
You should see JOAP::Proxy to figure out how to make your initial Jabber connection.
You can get a proxy to the instance's class using JOAP::Proxy::Class.
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.