NAME

PSA::Request - Encapsulate a generic PSA request.

SYNOPSIS

  my $acceptor = PSA::Acceptor::SomeType->new();

  my $request = $acceptor->accept();

  # fetch request meta-data; this might be headers in a SOAP
  # request, or CGI parameters.
  print $request->param("foo");

  # The request contains a unique, cryptographically strong
  # identifier.  Return it.
  print $request->sid();

  # The request has an associated URL.  With a CGI request,
  # this would be the request URL.  With a SOAP request, it
  # would be the soapmethod/soapaction
  print $request->uri();   # or ->url(), take yer pick

  # if the request was proxied in a way that we could detect,
  # the details will be here.
  print $request->proxy();  # like caller(); pass a number
                            # to go back N levels

  # Get the actual content... this method will possibly be
  # indexed in some manner, if the request supports
  # multi-part requests.
  print $request->body();

DESCRIPTION

PSA::Request is an abstract base class, that defines an interface for code to access information about incoming requests.

As such, the methods in this module that define how to return information about the request are stubs that throw exceptions, and therefore must be defined in sub-classes to be called.

Most users are more interested in the sub-classes of this module, such as PSA::Request::CGI, PSA::Request::XML and PSA::Request::SOAP. Go see the most relevant manual page for those modules if you want to use a PSA::Request object.

People who are writing new types of requests for their application server will want to implement the interface described in this manual page.

DATA MEMBERS

Certain aspects of input requests don't vary an awful lot between request types. These are defined as data members of the base class. As such, they have accessors as provided by Class::Tangram (see Class::Tangram).

sid

A unique identifier for this request.

Subclasses should explictly fill this variable when they are constructed, if appropriate. After the session is attached, the value might be changed, if the SID in the request was invalid.

uri

This Identifes the Resource that this request is requesting in a Universal manner. It is the most specific part of the resource; eg, once a message has been decoded from an envelope PSA::Request object to a more specific PSA::Request object, this might change.

METHODS

CONSTRUCTOR

Class->new()

The standard new() constructor should function as per the Class::Tangram standard [ ie, (attribute => $value, [...]) ].

Class->fetch()

In programming environments where the request is poked into strange places in the process environment or other such mallarky, this method should immediately fetch it all out, and not return until the request has been fully encapsulated.

METHODS

Not all of these methods apply to all types of request.

$request->param("name" [, "name" [...])

Fetch a named parameter (or list of named parameters) to the request. These are typically from the standard source of metadata for the given request type, such as CGI form parameters, extra HTTP headers, etc.

$request->proxy([ $level ])

This method should return either:

• An appropriate string that identifies a gateway URL, such as the POST url for a SOAP gateway.

• The "parent" PSA::Request object. Which should stringify to a URL, if only for easy debugging purposes.

$request->body([ $index ])

When called in scalar context with no arguments, this method must return the first or primary body of the message, before any kind of decoding has been applied.

When called in list context with no arguments, this method should return all parts, in order.

When called with a numeric index, this method should return the body part corresponding to that index in a multi-part message, or undef.

When called with a string index, this method should return the body part with that label in a multi-part message, or undef.

This method must return plain strings, which are complete serialisations of the relevant body parts.