NAME

Froody::Method - object representing a method callable by Froody

SYNOPSIS

  # create
  use Froody::Method;
  my $method = Froody::Method->new()
                             ->full_name("wibble.fred.burt")
                             ->invoker($invoker);

  # run the method
  my $froody_response = $method->call( fred => "wilma", barney => "betty" );

  # inspect
  $invoker    = $method->invoker;
  $full_name  = $method->full_name;
  $name       = $method->name;
  $module     = $method->module;

DESCRIPTION

An accessor class for definition of method APIs. Once a method is declared here you can execute it by calling its call function.

Froody::API modules must return from their load method one of these objects per method that can be called by the Froody server. That said, it's not normal to have to write code that creates these, but instead use the Froody::API::XML to create the Froody::Module objects from definitions in an XML file.

Method objects must know what they're called and what invoker defines them (and likewise the invoker class must know what Perl code to run when they're handed this method object via invoke.)

METHODS

new()

Create a new reflection object

call($params_hashref)

Calls this method. This dispatches this method via the correct implementation (as defined by implementation below and returns a Froody::Response object.

match_to_regex( "foo.bar.*" )

Class method that returns a regular expression that will determine if a string matches the specification passed in

source

Provide diagnostic information about this method.

ACCESSORS

full_name

The full dot-path name of the method.

name

The method name. Read only (set as a side-effect of setting full_name.)

module

The perl-style package name of the method. Read only (set as a side-effect of setting full_name.)

service

The service name of of the method. Read only (set as a side-effect of setting full_name.)

object

The class responsible for the overall handling of a method. Read only (set as a side-effect of setting full_name.)

arguments

A hash reference with the names of each argument, with the following structure: { 'name' => { multiple => 1, optional => 1, doc => 'Argument documentation', type => 'text', #user defined type label. } }

If the argument encodes (somehow) multiple values, then multiple must be set. If it does not, the 'multiple' key may be omitted, or set to a false value. An argument is assumed to be required unless the 'optional' key is set to a true value.

structure

A hash reference containing the specification of how the data that will be returned by a call to this method will be aranged - essentially the blueprint for constructing the response.

You probably don't want to create these by hand; The Froody::API::XML module will create these given a suitable example. See that module documentaion for more info.

The structure is a simple hash with a 'xpath' style key pointing to a hash containing elts (elements) and attr (attributes) arrayrefs.

 { 'people' =>
       { attr => ['group'],
         elts => [qw/person/],
       },
   'people/person' =>
       { elts => [qw/name/],
         attr => [qw/nick number/],
         text => 0,
         multi => 1,
       },
 };

elts should contain a list of all elements under this node. Each one of these elements will require a further entry in the hash unless the element contains only text and cannot be repeated (for example, the title and description in the above data structure are like this.)

The hashrefs may also contain other flags. The text flag can be used to indicate if it is valid for this node to contain text or not. The multi flag is used to indicate if there can be repeate occurances of the elements.

This would mean that the above data structure would validate this XML structure:

 <people group="frameworks" />
   <person nick="clkao" number="243">
     <name>Chia-liang Kao</name>
   </person>
   <person nick="Trelane" number="234">
     <name>Mark Fowler</name>
   </person>
   <person nick="Nichloas" number="238">
     <name>Nicholas Clark</name>
   </person>
   <person nick="nnunley" number="243">
     <name>Norman Nunley</name>
   </person>
   <person nick="skugg" number="214">
     <name>Stig Brautaset</name>
   </person>
   <person nick="jerakeen" number="235">
     <name>Tom Insam</name>
   </person>
   Frameworks is a department of Fotango.  We work on lots of
   software, including writing tools like Froody.
 </people>

example_response

An example of the response we expect to see from the method. This should be a Froody::Response object.

errors

A hashref containing a mapping of numeric error code (as the key) to a message description (as the value.)

needslogin

A boolean field. 1 if the user must be 'logged in' in order to use the method.

description

A briefer documentation section for the method represented by the current instance.

invoker

The invoker instance that knows about how to run the Perl code needed to actually do whatever this method is meant to represent. This must be a subclass of Froody::Invoker.

BUGS

None known.

Please report any bugs you find via the CPAN RT system. http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Froody

AUTHOR

Copyright Fotango 2005. All rights reserved.

Please see the main Froody documentation for details of who has worked on this project.

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

SEE ALSO

Froody, Froody::Repository, Froody::Invoker