view release on metacpan or  search on metacpan

JOAP/Types.pod  view on Meta::CPAN

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

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

=over

=item '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.

=item 'int'

=item 'i4'

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

=item 'double'

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

=item 'boolean'

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

=item '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.

=item '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.

=item 'array'

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

=item 'struct'

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

=back

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

=head1 EXPORT

None by default.

=head1 SEE ALSO