Evangelo Prodromou > JOAP-0.01 > JOAP::Types

Download:
JOAP-0.01.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

JOAP::Types - Documentation-only package about data types in JOAP

SYNOPSIS ^

    [N/A]

ABSTRACT ^

This documentation-only package discusses the JOAP datatypes and gives precise definitions of each datatype and how they are used.

DESCRIPTION ^

JOAP has a fairly specific set of data types that are used throughout the system. Rather than documenting the types everywhere they're used, this package gives more detail on each type.

JOAP borrows its set of datatypes from XML-RPC, as XML-RPC is already used on the Jabber network for application development. Each datatype is defined by a name that is used in, for example, the metadata about attributes and methods.

Each type is identified by a string value; these are translated into element tag names in XML format.

The definition here is loose; see the full JOAP documenation for details. Although the types come from XML-RPC, the formats of each type are mapped to XML Schema datatypes, which are generally more permissive than XML-RPC.

Note also that input for accessors and method parameters are generally marshalled from Perl values to the 'correct' JOAP value format before going on the wire, and back to Perl values when they're taken off the wire. So programmers will generally not have to worry if their values are formatted correctly; the values will automagically go through the JOAP pipe correctly.

XML-RPC Types

The types inherited from XML-RPC include the following. Note that there is an eclectic inventory style here; this is XML-RPC's fault, not JOAP's, and there's not much we can do about it.

'string'

Any string value. No codeset conversion is done. There's no limit on the size of the string. Almost any Perl scalar value will work well in this data type.

'int'
'i4'

This is a 32-bit signed integer value in decimal format. The two type names are synonymous.

'double'

A signed 'double precision' floating-point number, in decimal notation ('-120.4') or scientific notation ('-1.204e2').

'boolean'

A boolean true/false value. The number '0' represents false, and '1' represents true.

'dateTime.iso8601'

A string representation for a date/time combination in the gregorian calendar. The format is very specific, as follows:

    YYYY-MM-DDTHH:MM:SS[.ffff]TZ

Here, YYYY is the four-digit year (actually, the year can be greater than four digits, or negative). MM is the 2-digit month of the year, from '01' to '12'. DD is the day of the month, ranging from '01' to '31'. The 'T' is a literal character 'T' (assumably to specify 'time'), and 'HH' is the hour, ranging from '00' to '23'. 'MM' is the minute part, from '00' to '59', and SS is the seconds, '00' to '59'.

The 'ffff' part is optional, and represents the fractional part of the second. Any number of digits can be included.

The TZ is the timezone; JOAP specifies that all datetime values will be in UTC, so this will always be the letter 'Z'.

This type comes from XML Schema; the XML-RPC date format is slightly different.

'base64'

This is a base64-encoded binary value (such as a binary file format). JOAP doesn't do any encoding for you, and support for this data type is spotty.

'array'

This is a series of other values. It maps well to Perl arrays or lists.

'struct'

A set of name-value pairs, where the values can be any kind of JOAP value.

Object Types

In addition to these types, JOAP defines an object-address datatype. If a type specification is a JOAP class address, like 'Person@joap-server.example.net', the address of any instance of that class can be used as a value, like 'Person@joap-server.example.net/Prodromou,Evan'.

Moreover, the addresses of instances of classes that define 'Person@joap-server.example.net' as one of their superclasses can also be used as values for the type. So 'Vulcan@joap-server.example.net/Spock' can be used if 'Vulcan@joap-server.example.net' defines 'Person@joap-server.example.net' as one of its superclasses.

Currently, the JOAP Perl package supports object types poorly.

EXPORT ^

None by default.

SEE ALSO ^

The JOAP specification lists the full definition of the datatypes with more detail.

The JOAP package has tools for marshalling Perl values to JOAP values and vice versa.

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

syntax highlighting: