JOAP::Descriptors - Documentation-only package about JOAP descriptors
package MyPerson; use JOAP::Server::Class; use base qw(JOAP::Server::Class); # other stuff here MyPerson->Attributes ( { given_name => { type => 'string', required => 1, desc => 'Given name of the person.' }, age => { type => 'i4', writable => 0, desc => 'Age in years (rounded down) of person at current time', }, species => { type => 'string', writable => 0, allocation => 'class', desc => 'species of people' }, population => { type => 'i4', writable => 1, allocation => 'class', desc => 'total population of people' } }); MyPerson->Methods ( { walk => { returnType => 'boolean', params => [ { name => 'steps', type => 'i4', desc => 'how many steps forward to walk, fault if less than zero' } ], desc => 'Walk forward \'steps\' steps'}, get_family => { allocation => 'class', returnType => 'array', params => [ { name => 'family_name', type => 'string', desc => 'family name to look for' } ], desc => 'Returns people in a given family'} });
This documentation-only package describes the format and use of the descriptor data structures used to define JOAP attributes and methods.
The JOAP server and proxy classes all use data structures called descriptors to describe attributes and methods. This document defines the data structures, so I don't have to define them over and over and over again.
Each attribute descriptor is a reference to a hashtable containing the following fields.
A string value containing the name of the datatype for the attribute. See JOAP::Types for details about the allowed values in this field.
Leaving out this field is a bad idea.
1 if this is a required attribute, and 0 if it's not required. If unspecified, defaults to 0.
1 if this attribute can be written to, and 0 if not. Default is 1.
'class' if this is a class attribute, and 'instance' if this is an instance attribute. For object servers, this is kind of a moot point, so it should probably be unspecified.
Default is 'instance'.
A human-readable description of the purpose and usage of the attribute. Although JOAP allows multiple descriptions for an attribute (for i18n reasons), this library doesn't. This is a bug that should be fixed in future versions.
Note that the name of the attribute is not in the descriptor. As shown in the synopsis, names are provided as the key in the attribute descriptor hashtables.
Attribute names can only contain characters in the range [a-zA-Z0-9_], and the first character must be an understore or an alphabetic character.
Each method descriptor is a reference to a hashtable containing the following fields.
A string value containing the datatype of the return value of this method. See JOAP::Types for more information on the range of datatypes afforded by JOAP.
By default, the returnType is 'array'.
'class' if this is a class method, and 'instance' if this is an instance method. The default is 'instance'.
For object servers, the allocation of a method is a moot point, and it's best to leave it unspecified.
A reference to an array of parameter descriptors. See "Parameter Descriptors" below for more information on the format of these descriptors.
The parameter descriptors must be ordered in the array in the order that the parameters are required by the method. There is no provision for optional parameters or parameter lists. Each and every parameter in the list must be present, in order, for a method call.
A human-readable description of the purpose and usage of the method. JOAP allows multiple values for this field; this library does not. This will probably be corrected in future versions.
Note that each parameter also has its own description.
As with attribute descriptors, method descriptors don't contain the name of the method. This is defined at a higher level, in the map of names to descriptors, as above in the SYNOPSIS.
Method names can only contain characters in the range [a-zA-Z0-9_], and the first character must be an understore or an alphabetic character.
For methods, there's further descriptors for each parameter of the method. These descriptors are also references to hashtables with the following fields:
A string containing the name of the parameter. Parameter names can only contain characters in the range [a-zA-Z0-9_], and the first character must be an underscore or an alphabetic character.
A string with the JOAP datatype for this parameter. See JOAP::Types for more information about the range of values for JOAP datatypes.
A human-readable description of the purpose and use of the parameter. Again, JOAP allows multiple values here, but this library only allows a single string. This will probably be fixed in the future.
N/A
The fields in descriptors are generally not validated, causing bad typo errors.
See JOAP for more information about JOAP and contact info for the author.
See JOAP::Types for more information about JOAP datatypes.
Attribute and method descriptors are used all over the place in JOAP; see JOAP::Server::Object, JOAP::Proxy, and JOAP::Proxy::Package for examples.
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.