File Coverage

blib/lib/XPC.pm

Criterion	Covered	Total	%
statement	1	3	33.3
branch			n/a
condition			n/a
subroutine	1	1	100.0
pod			n/a
total	2	4	50.0

#
# XPC.pm - XML Procedure Call Classes
#
# Designed to work in conjunction with the XML::Parser Style => 'Object'.
#
# Copyright (C) 2001 Gregor N. Purdy.
# All rights reserved.
#
# This is free software; you can redistribute it and/or modify it under
# the same terms as Perl itself.
#


package XPC;

#use XML::Writer;
use XML::Parser;

use vars qw($VERSION);

$VERSION = 0.2;


#
# new()
#

sub new
{
  my $class = shift;
  my $self;

  if (@_) {
    my $xml = shift;

    my $parser = new XML::Parser(Style => 'Objects');
    eval {
      $self = $parser->parse($xml);
    };

    if ($@) {
      print STDERR "XPC: XML =\n";
      print STDERR $xml;
      print STDERR "\n";
      die "XPC: Unable to parse XML into XPC instance!\n";
    }
  } else {
    $self = new XPC::xpc;
  }

  return $self;
}


#
# new_call()
#

sub new_call
{
  my $class = shift;
  my $self  = $class->new();
  $self->add_call(@_);
  return $self;
}


##############################################################################
#
# CHARACTER DATA:
#
##############################################################################


#
# XPC::Characters
#

package XPC::Characters;

sub data
{
  my $self = shift;

  return $self->{Text};
}

sub new
{
  my ($class, $data) = @_;

  return bless { Text => $data }, $class;
}


##############################################################################
#
# ROOT:
#
##############################################################################

package XPC::xpc;


#
# version()
#

sub version
{
  my $self = shift;
  return $self->{version} if defined $self->{version};
}


#
# new()
#

sub new
{
  my ($class, $version) = @_;
  my $self = bless { Kids => [ ] }, $class;
  $self->{version} = $version if defined $version;
  return $self;
}


#
# add_call()
#

sub add_call
{
  my ($self) = shift;

  $self->add_request(XPC::call->new(@_));
}


#
# add_response()
#

sub add_response
{
  my ($self, $response) = @_;

  die "XPC::xpc::add_response(): Cannod add undef response!\n" unless defined $response;

  push @{$self->{Kids}}, $response;
}


#
# add_request()
#

sub add_request
{
  my ($self, $request) = @_;

  push @{$self->{Kids}}, $request;
}


#
# as_string()
#

sub as_string
{
  my $self = shift;

#  print STDERR "XPC::xpc:as_string(): Generating string...\n";

  my $version = $self->version;
  my @kids    = @{$self->{Kids}};

  my $body;

  foreach my $kid (@kids) {
    next unless defined $kid; # TODO: How does this happen?
    $body .= $kid->as_string;
  }

  if (defined $version and $version ne '') {
    if (defined $body) {
      return "\n$body\n";
    } else {
      return "\n"; # TODO: Degenerate case
    }
  } else {
    if (defined $body) {
      return "\n$body\n";
    } else {
      return "\n"; # TODO: Degenerate case
    }
  }
}


#
# results()
#

sub results
{
  my ($self, $index) = @_;

  my @kids    = @{$self->{Kids}};
  my @results = grep { ref $_ eq 'XPC::result'; } @kids;
  return @results;
}


#
# result()
#

sub result
{
  my ($self, $index) = @_;
  return ($self->results)[$index];
}


#
# faults()
#

sub faults
{
  my ($self, $index) = @_;

  my @kids    = @{$self->{Kids}};
  my @faults = grep { ref $_ eq 'XPC::fault'; } @kids;
  return @faults;
}


#
# fault()
#

sub fault
{
  my ($self, $index) = @_;
  return ($self->faults)[$index];
}


##############################################################################
#
# QUERIES:
#
##############################################################################

package XPC::query;


#
# procedure()
#
# OPTIONAL
#

sub procedure
{
  my $self = shift;
  return $self->{procedure} if defined $self->{procedure};
}


#
# id()
#

sub id
{
  my $self = shift;
  return $self->{id} if defined $self->{id};
}


#
# new()
#

sub new
{
  my ($class, $procedure, $id) = @_;
  my $self = bless { Kids => [ ] }, $class;
  $self->{id} = $id if defined $id;
  $self->{procedure} = $procedure if defined $procedure;
  return $self;
}


##############################################################################
#
# CALLS:
#
##############################################################################

package XPC::call;


#
# procedure()
#
# MANDATORY
#

sub procedure
{
  shift->{procedure};
}


#
# id()
#
# OPTIONAL
#

sub id
{
  my $self = shift;
  return $self->{id} if defined $self->{id};
}


#
# new()
#

sub new
{
  my ($class, $procedure, $id) = @_;
  my $self = bless { procedure => $procedure, Kids => [ ] }, $class;
  $self->{id} = $id if defined $id;
  return $self;
}


#
# add_param()
#
# TODO
#


#
# as_string()
#

sub as_string
{
  my $self = shift;

  my $procedure = $self->procedure;

  my $body;

  foreach my $kid (@kids) {
    $body .= $kid->as_string;
  }

  if (defined $body) {
    return "  \n$body  \n";
  } else {
    return "  \n";
  }
}


##############################################################################
#
# CALL PARAMETERS:
#
##############################################################################

package XPC::param;


#
# name()
#
# OPTIONAL
#

sub name
{
  shift->{name};
}


#
# new()
#

sub new
{
  my ($class, $name) = @_;
  my $self = bless { Kids => [ ] }, $class;
  $self->{name} = $name if defined $name;
  return $self;
}


##############################################################################
#
# PROTOTYPES:
#
##############################################################################

package XPC::prototype;


#
# id()
#
# OPTIONAL
#

sub id
{
  shift->{id};
}


#
# procedure()
#
# REQUIRED
#

sub procedure
{
  shift->{procedure};
}


#
# comment()
#
# TODO:
#


##############################################################################
#
# PROTOTYPE PARAMETER DEFINITIONS:
#
##############################################################################

package XPC::param_def;


#
# name()
#
# OPTIONAL
#

sub name
{
  shift->{name};
}


#
# type()
#
# REQUIRED
#

sub type
{
  shift->{type};
}


#
# subtype()
#

sub subtype
{
  shift->{subtype};
}


##############################################################################
#
# PROTOTYPE RESULT DEFINITIONS:
#
# TODO
#
##############################################################################

package XPC::result_def;



##############################################################################
#
# RESULTS:
#
##############################################################################

package XPC::result;


#
# id()
#
# OPTIONAL
#

sub id
{
  shift->{id};
}


#
# name()
#
# OPTIONAL
#
# TODO: Get rid of this?
#

sub name
{
  shift->{name};
}


#
# new_scalar()
#

sub new_scalar
{
  my $class = shift;

  my $self = bless { Kids => [ ] }, $class;

  die sprintf("XPC::result::new_scalar(): Cannot create scalar result with %d arguments!\n", scalar @_) if (@_ != 1);

  push @{$self->{Kids}}, XPC::scalar->new(@_);

  return $self;
}


#
# as_string()
#

sub as_string
{
  my $self = shift;

  my $value;
  foreach my $kid (@{$self->{Kids}}) {
    next if ref $kid eq 'XPC::Characters';

    $value .= $kid->as_string;
  }

  if (defined $value) {
    return "  \n    $value\n  \n";
  } else {
    die "XPC::result::as_string(): Mystery! No Kids!\n";
  }
}


#
# value()
#
# TODO: Return structs and arrays, too.
#

sub value
{
  my $self = shift;

  my @kids = grep { ref $_ eq 'XPC::scalar' } @{$self->{Kids}};
  return '' unless @kids;
  return $kids[0]->value;
}



##############################################################################
#
# FAULTS:
#
##############################################################################

package XPC::fault;


#
# id()
#
# OPTIONAL
#

sub id
{
  shift->{id};
}


#
# code()
#
# MANDATORY
#

sub code
{
  shift->{code};
}


#
# message()
#

sub message
{
  my $self = shift;
  my $data = $self->{Kids}->[0]->data;

  $data =~ s/^\s*//;
  $data =~ s/\s*$//;

  return $data;
}


#
# new()
#

sub new
{
  my ($class, $code, $message, $id) = @_;

  $message =~ s/^\s*//;
  $message =~ s/\s*$//;

  my $self =  bless { code => $code,
    Kids => [ XPC::Characters->new($message) ]
  }, $class;

  $self->{id} = $id if defined $id;

  die "Hah!" unless $message eq $self->message;

  return $self;
}


#
# as_string()
#

sub as_string
{
  my $self    = shift;
  my $id      = $self->id;
  my $code    = $self->code;
  my $message = $self->message;

  if (defined $id) {
    return "  \n    $message\n    \n";
  } else {
    return "  \n    $message\n  \n";
  }
}


##############################################################################
#
# SCALAR VALUES:
#
##############################################################################

package XPC::scalar;


#
# type()
#

sub type
{
  shift->{type};
}


#
# new()
#

sub new
{
  my ($class, $value, $type) = @_;

  my $self = bless { Kids => [ ] }, $class;

  push @{$self->{Kids}}, XPC::Characters->new($value);

  $self->{type} = $type if defined $type;

  return $self;
}


#
# as_string()
#

sub as_string
{
  my $self = shift;
  my $type = $self->type;

  my $attrs = '';

  $attrs .= " type='$type'" if defined $type;

  return "" . $self->{Kids}[0]->data . "";
}


#
# value()
#

sub value
{
  my $self = shift;
  return $self->{Kids}[0]->data;
}


##############################################################################
#
# ARRAY VALUES:
#
# TODO
#
##############################################################################

package XPC::array;


##############################################################################
#
# STRUCTURE VALUES:
#
# TODO
#
##############################################################################

package XPC::struct;


##############################################################################
#
# STRUCTURE MEMBER VALUES:
#
# TODO
#
##############################################################################

package XPC::member;


#
# name()
#

sub name
{
  shift->{name};
}



##############################################################################
#
# XML VALUES:
#
# TODO: This presents a problem for this style of parsing, since we could have
# any elements whatsoever here.
#
##############################################################################

package XPC::xml;


##############################################################################
#
# COMMENTS:
#
# TODO
#
##############################################################################

package XPC::comment;



##############################################################################
##############################################################################

1;


=head1 NAME

XPC - XML Procedure Call


=head1 SYNOPSIS

  use XPC;

and then

  my $xpc = XPC->new(<




  END_XPC

or

  my $xpc = XPC->new();
  $xpc->add_call('localtime');

or

  my $xpc = XPC->new_call('localtime');

and then later

  print XML_FILE $xpc->as_string();


=head1 DESCRIPTION

This class represents an XPC request or response. It uses XML::Parser to
parse XML passed to its constructor.


=head1 MOTIVATION

A Commentary on the XML-RPC Specification and Definition of XPC Version 0.2


=head2 Introduction

The following commentary is based upon the specification from the UserLand web
site. The version referenced for this commentary has a notation on it that it
was "Updated 10/16/99 DW" (see L).

These comments are stylistic in nature, and it is well recognized by the
author that style in program and protocol design are very personal. This
commentary will, however, point out the rationale of the proposed changes to
the specification's design.


=head2 Procedure Call Structural Simplifications

The example in the "Request example" section looks like this:


    examples.getStateName


        41




We note by looking at the remainder of the specification that there are only
two top-level elements allowed in XML-RPC: C and C.
Since methods are I subject of RPC, and since all top-level elements
in the design are about methods, there is no need to have the redundant
qualifier "method" in the names of these elements. Thus, the example would
be modified to look like this:


    examples.getStateName


        41




Now, the content of the C element is constrained to be very simple
text (from the "Payload format" section, which says "... identifier characters,
upper and lower-case A-Z, the numeric characters, 0-9, underscore, dot, colon
and slash"). It is also mandatory. This is precisely the reason XML includes
the ability to add attributes to elements (it is technically redundant, but
very convenient). So, we really should turn this example into:




        41




Once the C element has been removed from the design, the C
element becomes superfluous, since its only purpose was to group the
parameters and separate them from the method name. Now, the C element
I the element that groups the parameters, leaving us with:



      41




=head2 Header Nomenclature

One final comment on terminology: RPC stands for Remote I Call, so
we should probably not use the term "method" when we mean "procedure" or
something else. Since the "procedures" can return values, which corresponds
in some languages to the term "function", we have a rivalry for the term to
use. "Procedure" matches the acronym nicely, but for some folks "Function"
would have a better connotation. Fans of Eiffel might even prefer "Feature",
or "Query" for calls returning a value and "Routine" or "Command" for those
not. Given the variety of possibilities, here we stay with the simple
policy of matching the acronym:



      41




=head2 Scalar Values

Typically, an interface definition determines the number, names and types of
parameters to a procedure call. It is incumbent upon the caller to conform
to that specification. Therefore, the declaration for any procedure to be
called as part of an interface I indicate the expected types of the
parameters, which means that the caller should not have to indicate the type
of value it is passing (and, the value I isn't passed in general, but
rather a I of the value is passed). XML-RPC should not
be blind to typing issues. These issues should not appear in the calling
standard, but rather in an interface definition standard (about which more
later). Removing the type information from the example results in:



      41



Since the  element really now just means "scalar" (see the specification
section "Scalar EvalueEs"), let's call it that:



      41



If for some reason not contemplated here type information is necessary for
scalars, then having a simple C attribute of the C element
would suffice, especially since the set of allowable values is fixed,
small, and consists of only short string values (C, C, C,
C, C, C, and C).

If we only ever expected simple, short scalar values, we could make one more
change, to:








but, it is presumed that it would be possible to have a very long scalar
string value, for which the former representation would be better.


=head2 Named Parameters

Some procedures may be implemented in a language that makes it very easy to
implement named parameters. Supporting this would be easy:



      41




=head2 Scalar Types

Whether types apply to calls and interfaces or just to interfaces, they are
an important part of the specification.

The specification defines C and C to be synonyms for a 'four-byte
signed integer'. Since the value will be represented in the call as text,
this description really isn't an appropriate specification, since it is
written in terms of a binary representation. We suggest here a single term
for this data type, C, and that it be defined in terms of a range
of acceptable values: -2,147,483,648 to +2,147,483,647 (just the range of
vales that can be stored in a two's complement 32-bit binary representation).

The C data type is distinct from the C data type, yet its
domain {C<0>, C<1>} is a subset of the C domain instead of the more
consistent {C, C}. If C is going to be treated as its own
type, it should have its own domain.

The specification defines C to be 'double-precision signed floating
point number'. Note that in the 1999-01-21 questions-and-answers section
near the end of the document, it is revealed that the full generality of
the data type commonly meant by such a description is not available. Niether
infinities, nor C (the Not-a-Number value) are permitted. Not even
exponential notation is allowed. Very simple strings matching the Perl
regular expression:

  /^([+-])(\d*)(\.)(\d*)$/

are the only ones permitted according to the answer given, although one
suspects that what was meant was something closer to this:

  /^([+-])?(\d*)((\.)(\d*))?$/

because the first expression requires the sign to be present, and permits
"C<+.>" and "C<-.>" as valid strings (although to what values they would map is
a mystery).

Note: The second expression makes the leading sign and trailing decimal point
and digits optional, but still isn't perfect, since it allows the empty string
as a value.

This type should be called C instead of C to get away
from the physical description. C is another potentially reasonable
name for this type.

Also, the FAQ answer says the range of allowable values is implementation-
dependant, but the specification refers to "double-precision
floating-point", which does have an expected set of behaviors for most people.

The specification mentions "ASCII" in the type definition for string, but
XML permits all of Unicode. Shouldn't one expect to be able to pass around
string values with all the characters thus permitted? Shouldn't servers and
clients be written to handle this broader character set, and convert as
necessary internally? Otherwise, we are taking a big step back from the
promise of XML and the web.

The C data type name is awkward. They didn't refer to the
IEEE 754 floating point standard in the name of the C type (which
would have been C if they had). Unless the specification
is going to allow multiple C variants, the qualifier is just an
annoyance. In addition, most people call this type C, even if their
computer languages sometimes just call it C (as in many SQL
implementations). So, here we propose that this type just be called C
and that the type description refer to the ISO 8601 standard.

Finally, the C type (added 1999-01-21) really should be C with
the encoding standard (Base-64) referenced in the type description.


=head2 Structures

Structures continue the same idiom used elsewhere in the specification: the
avoidance of element attributes. Here is the example used in the specification
(modified to acommodate the recommendations already made here):



      lowerBound
      18


      upperBound
      139



The C element here should be converted into an attribute of the C
element, leaving:



      18


      139




=head2 Arrays

The C element is defined with a superfluous C child element. This
element serves no function, so it should be removed. Here is the example from
the specification (again, modified based on previous recommendations):



      12
      Egypt
      false
      -31



Removing the unneeded C element leaves us with:


    12
    Egypt
    false
    -31


We have recommended getting rid of C and using C, but the
specification allows a C to contain a scalar value I a C
I an C. We can still do without the C element, though:


    12

      Egypt
      false
      -31




=head2 Responses

The example in the document is:







            faultCode
            4


            faultString
            Too many parameters.






This has much unnecessary nesting. It is I simpler to store the fault
code as an attribute of the C element and to have the fault description
be the body of the C element:




      Too many parameters.




=head2 Adding a Consistent Top-Level Element

It would be nice if one could always be sure that XML data involved in the
XML-RPC protocol had a particular root element.

Another benefit of doing this is that a given request I include
multiple calls, which for certain types of interactions could be of great
performance benefit. If you need to make many related calls, the network
latency would be a real drag on performance, but batching up the calls into
one big bundle amortizes the transport time, increasing performance. A top-
level element of C is used here to stand for "XML Procedure Call".


     ...
     ...
     ...


As soon as we decide to put multiple calls in a transmission, it begs the
issue of tieing responses to calls. We could use order for this, but we
could also provide an attribute to C and C called C that
is optionally provided by the caller, and if present, is copied into the
response element for that call.

HTTP POST REQUEST CONTENT:


     ...
     ...
     ...


HTTP RESPONSE CONTENT:


     ...
     ...
     ...


Another benefit of having a consistent top-level element is that we can use
it to specify the protocol version:


     ...


Finally, using a consistent top-level element permits the response to contain
a copy of the request if desired.

HTTP POST REQUEST CONTENT:


     ...
     ...
     ...


HTTP RESPONSE CONTENT:


     ...
     ...
     ...
     ...
     ...
     ...



=head2 Extended Types

Given that XML-RPC is an XML application, it is disconcerting to see its
design be so blind to XML issues such as Unicode values (discussed above) and
tree-structured data. Suppose a procedure was to accept XML as a parameter or
to return XML as its result. How would this be accomplished with XML-RPC? The
answer seems to be "stuff it in a string scalar". But, to be a proper string,
all the markup would have to be escaped:




        <bar>Here's some text in an element.</bar>




However, if we add to the C, C and C types a new
type C, then we can do the natural thing:




        Here's some text in an element.




We could even use XML Namespaces if needed to resolve element name collisions
if they arise (namespaces are commonly used for this reason in XSLT
transforms).

Technically speaking, allowing parameters and results to contain XML makes the
other XML-RPC types redundant, but providing shortcuts for these common cases
does make sense.


=head2 Interface Specifications

In order to provide true discoverability, there needs to be a way for a client
to ask the server what operations it supports, and to get back interface
information for the supported procedures.

Sending an empty C element should cause the server to return an array
of procedure names:

HTTP POST REQUEST CONTENT:





HTTP RESPONSE CONTENT:




        foo
        bar




Sending a C element with a procedure name filled in should return a
response containing a prototype:

HTTP POST REQUEST CONTENT:





HTTP RESPONSE CONTENT:




        The 'foo' procedure! Given an integer, returns an array with that
        many elements, with each element containing the integer number of
        its position within the array.






Requesting information on an unknown procedure results in a C return:

HTTP POST REQUEST CONTENT:





HTTP RESPONSE CONTENT:



      Unknown procedure name 'quux'!




=head2 Conclusion

The "Strategies/Goals" section of the specification lists these items
(paraphrased):


=over 4

=item *

Leverage the ability of CGI to pass many firewalls to build an RPC
mechanism that can cross many platforms and many network boundaries.

=item *

Cleanliness.

=item *

Extensibility.

=item *

Easy implementation.

=back


The first of these seems to be met without difficulty by leveraging the HTTP
protocol.

Cleanliness is of course a subjective measure, and this document has pointed
out many points on which we think cleanliness can be improved.

The original specification doesn't seem to address extensibility other than
to list it as a goal. This document's addition of the XML type provides much
extensibility.

Ease of implementation should not be radically decreased by the modified
version of XML-RPC proposed here, except in the handling of Unicode text.
This is likely the main reason ASCII was specified in the original protocol
definition.


=head1 ADDITIONAL INFORMATION

The following sections provide details behind the proposed XPC.

=head2 Document Type Definition for Proposed XPC

This appendix shows the complete simple DTD for XPC. It is no more complicated
than the XML-RPC DTD (see L
or L).
































    #IMPLIED >


















































=head2 XML Schema for Proposed XPC




=head2 An XML-RPC E---E XPC Gateway

The following XSLT transform will convert XML-RPC requests into XPC requests:




The following XSLT transform will convert XPC responses into XML-RPC responses
(where it is possible):




The following XSLT transform will convert XPC requests into XML-RPC requests
(where it is possible):




The following XSLT transform will convert XML-RPC responses into XPC responses:




=head1 AUTHOR

Gregor N. Purdy [e-mail]


=head1 COPYRIGHT

Copyright (C) 2001 Gregor N. Purdy. All rights reserved.

This is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.