B.1 SOAP::Lite | Programming Web Services with Perl

The classes documented in this section are all available when an application loads the SOAP::Lite module via use or require . The order in which the classes are presented is based on general usage patterns; those which are directly used more often are presented first. Not all the classes within this file are present here; those which are meant only to be support elements are omitted.

B.1.1 SOAP::Lite

The first group of methods presented are the constructor and the accessor methods. All accessor methods share the trait of returning the current appropriate value when called with no arguments, while returning the object reference itself when called with a new value for the field in question. This allows the set-attribute calls to be chained together.

new( optional key/value pairs )

 $client = SOAP::Lite->new(proxy => $endpoint)

This is the constructor of the class. Many of the accessor methods defined here may be initialized at creation by providing their name as a key, followed by the desired value. The example provides the value for the proxy element of the client.

transport( optional transport object )

 $transp = $client->transport( );

Provides access to the transport object that the client has allocated to manage the communication layer operations. You can set this by passing a new object that derives from SOAP::Transport , but this is generally not needed or recommended. Several of the following methods are shortcuts to this object's accessors.

serializer( optional serializer object )

 $serial = $client->serializer( )

Provides access to the SOAP::Serialization object that the client uses to transform the elements and data of a request into an XML document for the sake of transport. As with transport , this may be set by providing a new object reference, but it is generally not needed.

proxy( endpoint, optional extra arguments )

 $client->proxy('http://soap.xml.info/ endPoint');

The proxy is the server or endpoint to which the client is going to connect. It shouldn't be confused with the uri method discussed later, which refers to a different element of the conversation. This method allows the setting of the endpoint, along with any extra information that the transport object may need when communicating the request. Indeed, this method is actually an alias to the proxy method of SOAP::Transport . It is the same as typing:

 $client->transport( )->proxy(...   arguments   );

When extra information is needed, it is also passed in the call to this method. Connecting to a server that uses browser cookies for authentication can be done by creating an instance of the HTTP::Cookies class (from the LWP package) and passing it as the value following a key of cookie_jar . The value for socket-time-outs may also be set this way. The full range of options vary by transport method. One common theme is that the endpoint string is always the first argument, with all additional arguments following it.

endpoint( optional new endpoint address )

 $client->endpoint('http://soap.xml.info/ newPoint')

It may be preferable to set a new endpoint without the additional work of examining the new address for protocol information and checking to ensure the support code is loaded and available. This method allows the caller to change the endpoint that the client is currently set to connect to, without reloading the relevant transport code. Note that the proxy method must have already been called before this method is used.

service( service URL )

 $client->service('http://svc.perl.org/Svc.wsdl');

SOAP::Lite offers some support for creating method stubs from service descriptions. At present, only WSDL support is in place. This method loads the specified WSDL schema and uses it as the basis for generating stubs.

outputxml( boolean )

 $client->outputxml('true');

Controls whether the returned information from a remote method call is the raw XML from the server. The default is to process the data from the server and present it to the caller as an object of the SOAP::SOM class. If the application prefers to use a different parser or do something else entirely with the results, this method may be used to inhibit the parsing of the returned information.

autotype( boolean )

 $client->autotype(0);

This method is a shortcut for:

 $client->serializer->autotype(   boolean   );

By default, the serializer tries to automatically deduce types for the data being sent in a message. Setting a false value with this method disables the behavior.

readable( boolean )

 $client->readable(1);

This method is a shortcut for:

 $client->serializer->readable(   boolean   );

When this is used to set a true value for this property, the generated XML sent to the endpoint has extra characters (spaces and new lines) added in to make the XML itself more readable to human eyes (presumably for debugging). The default is to not send any additional characters .

soapversion( optional value )

 $client->soapversion('1.2');

If no parameter is given, returns the current version of SOAP that is being used by the client object to encode requests . If a parameter is given, the method attempts to set that as the version of SOAP being used. The value should be either 1.1 or 1.2 .

envprefix( QName )

 $client->envprefix('env');

This method is a shortcut for:

 $client->serializer->envprefix(   QName   );

The namespace label used for the main SOAP namespace elements (such as Envelope , Body , and the attributes) defaults to SOAP-ENV . As has been discussed in earlier chapters, the label itself isn't important. But applications that wish to explicitly choose a different one (such as env to denote a SOAP 1.2 message) may do so with this method.

encprefix( QName )

 $client->encprefix('enc');

This method is a shortcut for:

 $client->serializer->encprefix(   QName   );

As with the envprefix method, this gets or sets the label used for the namespace of the encoding rules. The default value is SOAP-ENC , as is generally used in SOAP 1.1 messages, though the label itself has no actual meaning.

While it may seem to be an unnecessary operation to set a value that isn't relevant to the message, such as the namespace labels for the envelope and encoding URNs, the ability to set these labels explicitly can prove to be a great aid in distinguishing and debugging messages on the server side of operations.

encoding( encoding URN )

 $client->encoding($soap_12_encoding_URN);

This method is a shortcut for:

 $client->serializer->encoding(   args   );

Where the earlier method dealt with the label used for the attributes related to the SOAP encoding scheme, this method actually sets the URN to be specified as the encoding scheme for the message. The default is to specify the encoding for SOAP 1.1, so this is handy for applications that need to encode according to SOAP 1.2 rules.

typelookup

 $client->typelookup;

This method is a shortcut for:

 $client->serializer->typelookup;

Gives the application access to the type-lookup table from the serializer object. See the section on SOAP::Serializer .

uri( service specifier )

 $client->uri($service_uri);

This method is a shortcut for:

 $client->serializer->uri(   service   );

The URI associated with this accessor on a client object is the service-specifier for the request, often encoded for HTTP-based requests as the SOAPAction header. While the names may seem confusing, this method doesn't specify the endpoint itself. Often times, the value may look like a valid URL. Despite this, it doesn't have to point to an existing resource (and often doesn't). This method sets and retrieves this value from the object. Note that no transport code is triggered by this because it has no direct effect on the transport of the object.

multirefinplace( boolean )

 $client->multirefinplace(1);

This method is a shortcut for:

 $client->serializer->multirefinplace(   boolean   );

Controls how the serializer handles values that have multiple references to them. Recall from previous SOAP chapters that a value may be tagged with an identifier, then referred to in several places.

When this is the case for a value, the serializer defaults to putting the data element towards the top of the message, right after the opening tag of the method-specification. It is serialized as a standalone entity with an ID that is then referenced at the relevant places later on. If this method is used to set a true value, the behavior is different.

When the multirefinplace attribute is true , the data is serialized at the first place that references it, rather than as a separate element higher up in the body. This is more compact but may be harder to read or trace in a debugging environment.

self

 $ref = SOAP::Lite->self;

Returns an object reference to the default global object the SOAP::Lite package maintains. This is the object that processes many of the arguments when provided on the use line.

The following method isn't an accessor style of method but neither does it fit with the group that immediately follows it:

call( arguments )

 $client->call($method => @arguments);

As has been illustrated in previous chapters, the SOAP::Lite client objects can manage remote calls with auto-dispatching using some of Perl's more elaborate features. call is used when the application wants a greater degree of control over the details of the call itself. The method may be built up from a SOAP::Data object, so as to allow full control over the namespace associated with the tag, as well as other attributes like encoding. This is also important for calling methods that contain characters not allowable in Perl function names, such as A.B.C .

The next four methods used in the SOAP::Lite class are geared towards handling the types of events than can occur during the message lifecycle. Each of these sets up a callback for the event in question:

on_action( callback )

 $client->on_action(sub { qq("$_[0]") });

Triggered when the transport object sets up the SOAPAction header for an HTTP-based call. The default is to set the header to the string, uri # method , in which URI is the value set by the uri method described earlier, and method is the name of the method being called. When called, the routine referenced (or the closure, if specified as in the example) is given two arguments, uri and method , in that order.

on_fault( callback )

 $client->on_fault(sub { popup_dialog($_[1]) });

Triggered when a method call results in a fault response from the server. When it is called, the argument list is first the client object itself, followed by the object that encapsulates the fault. In the example, the fault object is passed (without the client object) to a hypothetical GUI function that presents an error dialog with the text of fault extracted from the object (which is covered shortly under the SOAP::SOM methods).

on_nonserialized( callback )

 $client->on_nonserialized(sub { die "$_[0]?!?" });

Occasionally, the serializer may be given data it can't turn into SOAP-savvy XML; for example, if a program bug results in a code reference or something similar being passed in as a parameter to method call. When that happens, this callback is activated, with one argument. That argument is the data item that could not be understood . It will be the only argument. If the routine returns, the return value is pasted into the message as the serialization. Generally, an error is in order, and this callback allows for control over signaling that error.

on_debug( callback )

 $client->on_debug(sub { print @_ });

This is kept for backwards -compatibility with earlier versions of the toolkit. Each method has a trace step built in, which is called at routine entry. This specifies a callback to be used when these trace statements are reached.

Because this is deprecated, it is recommended that applications use the +debug and +trace facilities described later under SOAP::Trace . Note also that debugging isn't handled on a per-object basis; if this method is used on a given object, it sets debugging behavior for all objects of the class.

B.1.2 SOAP::Data

The SOAP::Data class provides the means by which to explicitly manipulate and control all aspects of the way in which Perl data gets expressed as SOAP data entities. Most of the methods are accessors, which like those in SOAP::Lite are designed to return the current value if no new one is passed, while returning the object reference otherwise (allowing for chained method calls). Note that most accessors (except value ) accept a new value for the data object as a second argument.

new( optional key/value pairs )

 $obj = SOAP::Data->new(name => 'idx', value => 5);

This is the class constructor. Almost all of the attributes related to the class may be passed to the constructor as key/value pairs. This method isn't often used directly because SOAP::Data objects are generally created for temporary use. It is available for those situations that require it.

name( new name, optional value )

 $obj->name('index');

Gets or sets the current value of the name, as the object regards it. The name is what the serializer will use for the tag when generating the XML for this object. It is what will become the accessor for the data element. Optionally , the object's value may be updated if passed as a second argument.

type( new type, optional value )

 $obj->type('int');

Gets or sets the type associated with the current value in the object. This is useful for those cases where the SOAP::Data object is used to explicitly specify the type of data that would otherwise be interpreted as a different type completely (such as perceiving the string 123 as an integer, instead). Allows the setting of the object's value, if passed as a second argument to the method.

uri( new uri, optional value )

 $obj->uri('http://www.perl.com/SOAP');

Gets or sets the URI that will be used as the namespace for the resulting XML entity, if one is desired. This doesn't set the label for the namespace. If one isn't provided by means of the prefix method, one is generated automatically when needed. Also allows the setting of the object's value, if passed as a second argument to the method.

prefix( new prefix, optional value )

 $obj->prefix('perl');

Provides the prefix, or label, for use when associating the data object with a specific namespace. Also allows the setting of the object's value, if passed as a second argument to the method.

attr( hash reference of attributes, optional value )

 $obj->attr({ attr1 => 'value' });

Allows for the setting of arbitrary attributes on the data object. Keep in mind the requirement that any attributes not natively known to SOAP must be namespace-qualified. Also allows the setting of the object's value, if passed as a second argument to the method.

value( new value )

 $obj->value(10);

Fetches the current value encapsulated by the object, or explicitly sets it.

The last four methods are convenience shortcuts for the attributes that SOAP itself supports. Each also permits inclusion of a new value, as an optional second argument.

actor( new actor, optional value )

 $obj->actor($new_actor_name);

Gets or sets the value of the actor attribute; useful only when the object generates an entity for the message header.

mustUnderstand( boolean, optional value )

 $obj->mustUnderstand(0);

Manipulates the mustUnderstand attribute, which tells the SOAP processor whether it is required to understand the entity in question.

encodingStyle( new encoding URN, optional value )

 $obj->encodingStyle($soap_11_encoding);

This method is most likely to be used in places outside the header creation. Sets encodingStyle , which specifies an encoding that differs from the one that would otherwise be defaulted to.

root( boolean, optional value )

 $obj->root(1);

When the application must explicitly specify which data element is to be regarded as the root element for the sake of generating the object model, this method provides the access to the root attribute.

B.1.3 SOAP::SOM

Objects from the SOAP::SOM class aren't generally instantiated directly by an application. Rather, they are handed back by the deserialization of a message.

new( message )

 $som = SOAP::SOM->new($message_as_xml);

As said, the need to actually create an object of this class should be very rare. However, if the need arises, the syntax must be followed. The single argument to new must be a valid XML document the parser will understand as a SOAP response.

The following group of methods provide general data retrieval from the SOAP::SOM object. The model for this is an abbreviated form of XPath. Following this group are methods that are geared towards specific retrieval of commonly requested elements.

match( path )

 $som->match('/Envelope/Body/[1]');

This method sets the internal pointers within the data structure so that the retrieval methods that follow will have access to the desired data. In the example path, the match is being made against the method entity, which is the first child tag of the body in a SOAP response. The enumeration of container children starts at 1 in this syntax, not 0.

The returned value is dependent on the context of the call. If the call is made in a boolean context (such as if ($som->match($path)) ), the return value is a boolean indicating whether the requested path matched at all. Otherwise, an object reference is returned. The returned object is also a SOAP::SOM instance but is smaller, containing the subset of the document tree matched by the expression.

valueof ( node )

 $res = $som->valueof('[1]');

When the SOAP::SOM object has matched a path internally with the match method, this method allows retrieval of the data within any of the matched nodes. The data comes back as native Perl data, not a class instance (see dataof ). In a scalar context, this method returns just the first element from a matched node set. In an array context, all elements are returned. Assuming that the earlier call happens after the earlier call to match , it retrieves the result entity from the method response that is contained in $som , as this is the first child element in a method-response tag.

dataof( node )

 $resobj = $som->dataof('[1]');

Performs the same operation as the earlier valueof method, except that the data is left in its SOAP::Data form, rather than being deserialized. This allows full access to all the attributes that were serialized along with the data, such as namespace and encoding.

headerof( node )

 $resobj = $som->headerof('[1]');

Acts much like dataof , except that it returns an object of the SOAP::Header class (covered later in this chapter), rather than SOAP::Data . This is the preferred interface for manipulating the header entities in a message.

namespaceuriof( node )

 $ns = $som->namespaceof('[1]');

Retrieves the namespace URI that governs the requested node. Note that namespaces are inherited, so this method will return the relevant value, even if it derives from a parent or other ancestor node.

The following methods provide more direct access to the message envelope. All these methods return some form of a Perl value, most often a hash reference, when called. Context is also relevant: in a scalar context only the first matching node is returned, while in an array context, all matching nodes are. When called as a static method or as a regular function (such as SOAP::SOM::envelope ), any of the following methods returns the XPath string that is used with the match method to retrieve the data.

root

 $root = $som->root;

Returns the value of the root element as a hash reference. It behaves exactly as $som->valueof('/') does.

envelope

 $envelope = $som->envelope;

Retrieves the "Envelope" element of the message, returning it and its data as a hash reference. Keys in the hash will be Header and Body (plus any optional elements that may be present in a SOAP 1.1 envelope), whose values will be the serialized header and body, respectively.

header

 $header = $som->header;

Retrieves the header portion of the envelope as a hash reference. All data within it will have been deserialized. If the attributes of the header are desired, the static form of the method can be combined with match to fetch the header as a SOAP::Data object:

 $header = $som->match(SOAP::SOM::header)->dataof;

headers

 @hdrs = $som->headers;

Retrieves the node set of values with deserialized headers from within the Header container. This is different from the earlier header method in that it returns the whole header as a single structure, and this returns the child elements as an array. In other words, the following expressions yield the same data structure:

 $header = ($som->headers)[0]; $header = $som->valueof(SOAP::SOM::header.'/[1]');

body

 $body = $som->body;

Retrieves the message body as a hash reference. The entity tags act as keys, with their deserialized content providing the values.

fault

 if ($som->fault) { die $som->fault->faultstring }

Acts both as a boolean test whether a fault occurred, and as a way to retrieve the Fault entity itself from the message body as a hash reference. If the message contains a fault, the next four methods ( faultcode , faultstring , faultactor , and faultdetail ) may be used to retrieve the respective parts of the fault (which are also available on the hash reference as keys). If fault in a boolean context is true , the result , paramsin , paramsout , and method methods all return undef .

faultcode

 $code = $som->faultcode;

Returns the faultcode element of the fault if there is a fault; undef otherwise.

faultstring

 $string = $som->faultstring;

Returns the faultstring element of the fault if there is a fault; undef otherwise.

faultactor

 $actor = $som->faultactor;

Returns the faultactor element of the fault, if there is a fault and if the actor was specified within it. The faultactor element is optional in the serialization of a fault, so it may not always be present. This element is usually a string.

faultdetail

 $detail = $som->faultdetail;

Returns the content of the detail element of the fault, if there is a fault and if the detail element was provided. Note that the name of the element isn't the same as the method, due to the possibility for confusion had the method been called simply, detail . As with the faultactor element, this isn't always a required component of a fault, so it isn't guaranteed to be present. The specification for the detail portion of a fault calls for it to contain a series of element tags, so the application may expect a hash reference as a return value when detail information is available (and undef otherwise).

method

 $method = $som->method

Retrieves the "method" element of the message, as a hash reference. This includes all input parameters when called on a request message or all result/output parameters when called on a response message. If there is a fault present in the message, it returns undef .

result

 $value = $som->result;

Returns the value that is the result of a SOAP response. The value will be already deserialized into a native Perl datatype.

paramsin

 @list = $som->paramsin;

Retrieves the parameters being passed in on a SOAP request. If called in a scalar context, the first parameter is returned. When called in a list context, the full list of all parameters is returned. Each parameter is a hash reference, following the established structure for such return values.

paramsout

 @list = $som->paramsout;

Returns the output parameters from a SOAP response. These are the named parameters that are returned in addition to the explicit response entity itself. It shares the same scalar/list context behavior as the paramsin method.

paramsall

 @list = $som->paramsall;

Returns all parameters from a SOAP response, including the result entity itself, as one array.

B.1.4 SOAP::Fault

This class encapsulates SOAP faults prior to their serialization or after their deserialization. The methods available are a constructor and four accessors. Each accessor creates an object on demand, just as the other classes do, when called as a static method. Like other accessors in the SOAP::Lite package, they return the object itself when setting the attribute.

new( optional data )

 $fault = SOAP::Fault->new(faultcode => 'Server');

Explicitly creates a new SOAP::Fault object. Any of the four attributes represented next by accessor methods may be passed in the argument list with values immediately following their attribute name.

faultcode( optional value )

 $fault->faultcode('MethodUnknown');

Returns the current fault code or sets it if a value is given.

faultstring( optional value )

 $fault->faultstring("There is no $method here");

Returns or sets the fault string.

faultactor( optional value )

 $fault->faultcode($header->actor);

Returns or sets the fault-actor element. Note that the actor isn't always required in a SOAP fault.

faultdetail( optional value )

 $fault->faultcode(bless { proxy => $ip }, 'Err');

Returns or sets the fault's detail element. Like the actor , this isn't always a required element (refer back to the chapter on SOAP structure for discussion of these fault elements). Note that fault detail content in a message is represented as tag blocks. Thus, the values passed to this accessor when setting the value are either SOAP::Data objects, or more general blessed hash references.

In addition to these methods, the SOAP::Fault package also provides detail as an alias for faultdetail . The former is the actual name of the element with SOAP faults, but the latter name is less ambiguous when regarded with the rest of the SOAP::Lite package. Objects of this class also have a special stringification enabled. If an object is printed or otherwise stringified, the value produced is faultcode: faultstring , with the attribute values of the object.

B.1.5 SOAP::Transport

Objects of the SOAP::Transport class manage two roles: they manage both the parameters related to transport as set through the containing SOAP::Lite object, and they abstract the selection and loading of an appropriate transport module. This is done with an AUTOLOAD function within the class that intercepts all methods beyond the two defined next and reroutes them to the underlying transport implementation code.

new

 $trans = SOAP::Transport->new;

This is the constructor, which isn't usually called by an application directly. An application can use this to create a fresh new SOAP::Transport object, which may be installed using the SOAP::Lite->transport method defined earlier. No arguments are recognized.

proxy( optional URL string )

 $trans->proxy('http://www.blackperl.com/SOAP');

Gets or sets the proxy (endpoint). This method must be called before any other methods are called. The proper transport code is loaded based on the scheme specified by the URL itself ( http , jabber , etc.). Until this method is called the first time with a URL string, the underlying code has yet to be loaded, and the methods aren't available. When getting the current proxy (calling with no parameters), the returned value is a reference to the client object created from the protocol class that matched the endpoint, not the endpoint itself.

For the other methods that become available after proxy is called, see the later section on the SOAP transport modules.

B.1.6 SOAP::Serializer

The SOAP::Serializer class is the means by which the toolkit manages the expression of data as XML. The object that a SOAP::Lite instance uses by default is generally enough for the task, with no need for the application to create its own. The main purpose of this class is to provide a place for applications to extend the serializer by defining additional methods for handling new datatypes. The methods available through this class are:

new( optional key/value pairs )

 $serialize = SOAP::Serializer->new( );

This is the constructor method for the class. In addition to creating a basic object and initializing it with default values, the constructor can also take names and values for most of the accessor methods that the class supports.

envelope( method, data arguments )

 $serialize->envelope(fault => $fault_obj);

Provides the core purpose for the SOAP::Serializer class. It creates the full SOAP envelope based on the input passed in to it. The data arguments passed in the list of parameters to the method are divided into two sublists: any parameters that are SOAP::Header objects or derivatives of go into one list, while the remainder go into the other. The nonheader objects are used as the content for the message body, with the body itself being largely dependent on the value of the first argument in the list. This argument is expected to be a string and should be one of the following:

method: The envelope is being created to encapsulate a RPC-style method call.
response: The message being created is that of a response stemming from a RPC-style method call.
fault: For this specifier, the envelope being created is to transmit a fault.
freeform: This identifier is used as a general-case encoding style for messages that don't fit into any of the previous cases. The arguments are encoded into the envelope's Body tag without any sort of context sensitivity.

Any value other than these four results in an error.

envprefix( optional value )

 $serialize->envprefix('env');

Gets or sets the prefix that labels the SOAP envelope namespace. This defaults to SOAP-ENV .

encprefix( optional value )

 $serialize->envprefix('enc');

Gets or sets the prefix that labels the SOAP encoding namespace. Defaults to SOAP-ENC .

soapversion( optional value )

 $serial->soapversion('1.2');

If no parameter is given, returns the current version of SOAP that is being used as the basis for serializing messages. If a parameter is given, attempts to set that as the version of SOAP being used. The value should be either 1.1 or 1.2 . When the SOAP version is being set, the package selects new URNs for envelope and encoding spaces and also calls the xmlschema method to set the appropriate schema definition.

xmlschema( optional value )

 $serial->xmlschema($xml_schema_1999);

Gets or sets the URN for the schema being used to express the structure of the XML generated by the serializer. If setting the value, the input must be the full URN for the new schema and is checked against the list of known SOAP schemas.

B.1.7 SOAP::Header

Objects instantiated from the SOAP::Header class are functionally the same as SOAP::Data objects, and as such share all the methods from that class. The distinction may be cosmetic, but it is present so that applications may more easily distinguish header blocks from more generic data elements.

B.1.8 SOAP::Constants

A number of "constant" values are provided by means of this namespace. The values aren't constants in the strictest sense; the purpose of the values detailed here is to allow the application to change them if it desires to alter the specific behavior governed.

$DO_NOT_USE_XML_PARSER

The SOAP::Lite package attempts to locate and use the XML::Parser package, falling back on an internal, pure-Perl parser in its absence. This package is a fast parser, based on the Expat parser developed by James Clark. If the application sets this value to 1 , there will be no attempt to locate or use XML::Parser .

There are several reasons you might choose to do this. If the package will never be made available, there is no reason to perform the test. Setting this parameter is less time-consuming than the test for the package would be. Also, the XML::Parser code links against the Expat libraries for the C language. In some environments, this could cause a problem when mixed with other applications that may be linked against a different version of the same libraries. This was once the case with certain combinations of Apache, mod_perl and XML::Parser .

$DO_NOT_USE_CHARSET

Unless this parameter is set to 1 , outgoing Content-Type headers will include specification of the character set used in encoding the message itself. Not all endpoints (client or server) may be able to properly deal with that data on the content header, however. If dealing with an endpoint that expects to do a more literal examination of the header as whole (as opposed to fully parsing it), this parameter may prove useful.

$DO_NOT_CHECK_CONTENT_TYPE

The content-type itself for a SOAP message is rather clearly defined, and in most cases, an application would have no reason to disable the testing of that header. This having been said, the content-type for SOAP 1.2 is still only a recommended draft, and badly coded endpoints might send valid messages with invalid Content-Type headers. While the "right" thing to do would be to reject such messages, that isn't always an option. Setting this parameter to 1 allows the toolkit to skip the content-type test.

B.1.9 SOAP::Schema

This class provides an umbrella for the way in which SOAP::Lite manages service description schemas. Currently, the only support present is for the Web Services Description Language (WSDL) (see the next section). This is another of the classes not generally designed to be directly instantiated by an application, though it can be if so desired.

new( optional key/value pairs )

 $schema = SOAP::Schema->new(parse => $schema_uri);

This is the class constructor. With no arguments, it creates a blank object of the class. Any arguments that are passed are treated as key/value pairs in which the key represents one of the methods described here, and the value is what gets passed when the method itself gets invoked.

parse( service description URI )

 $schema->parse('http://schemas.w3.org/soap.wsdl');

Parses the internal representation of the service description prior to the generation of stub routines to provide method-like access to the remote services.

access( service description URI )

 $schema->access('http://soap.org/service.wsdl');

Loads the specified service description from the given URL, using the current value of the schema accessor if none is provided. The full content of the URL is returned on success, or an exception is thrown (via die ) on error.

load

 $schema->load;

Takes the internal representation of the service and generates code stubs for the remote methods, allowing them to be called as local object methods. Stubs are generated for all the functions declared in the WSDL description with this call because it's enough of a class framework to allow for basic object creation for use as handles.

schema

 $current_schema = $schema->schema;

Gets (or sets) the current schema representation to be used by this object. The value to be passed when setting this is just the URI of the schema. This gets passed to other methods such as access for loading the actual content.

services

 $hashref = $schema->services;

Gets or sets the services currently stored on the object. The services are kept as a hash reference, whose keys and values are the list of returned values from the WSDL parser. Keys represent the names of the services themselves (names have been normalized into Perl-compatible identifiers), with values that are also hash references to the internal representation of the service itself.

B.1.10 SOAP::Schema::WSDL

At present, the SOAP::Lite toolkit supports only loading of service descriptions in the WSDL syntax. This class manages the parsing and storing of these service specifications. As a general rule, this class should be even less likely to be used directly by an application because its presence should be completely abstracted by the previous class ( SOAP::Schema ). None of the methods are defined here; the class is only mentioned for sake of reference.

B.1.11 SOAP::Client

The SOAP::Client class exists purely as a superclass for client classes declared by the various transport modules detailed here. The methods it provides are all simple accessors; they return the current value when called with no arguments or set the attribute value and return the object reference when called with an argument. These attributes include:

code , message , status

Stores the response code, message, and status from the most-recent send attempt. For some protocols, such as FTP, the same value is used for all three because of the lack of finer-grained detail (the default is to ensure that all three attributes contain data, even if redundant). Other protocols (such as HTTP) have distinct values in each.

endpoint

Identifies the current endpoint to which messages are being sent. This should match the value of the transport method from the SOAP::Transport class, but setting this doesn't propagate to the transport object. It is better to use the transport object (or the shortcut via the SOAP::Lite object itself) when setting this.

is_success

The success or failure of the most-recent transmission is noted here as a boolean value.

options

The options attribute keeps a hash-table reference of additional options and their values. At present, only one option is used by any of the transport modules:

compress_threshold: The value of this option should be a numerical value. If set, and if the Compress::Zlib library is available, messages whose size in bytes exceeds this value will be compressed before sending. Both ends of the conversation must have it enabled.

Other options may be defined using this mechanism. Note that setting the options using this accessor requires a full hash reference be passed. To set just one or a few values, consider retrieving the current reference value and using it to set the key(s).

B.1.12 SOAP::Server

The SOAP::Server class provides the basic framework for the transport-specific server classes to build upon. Note that in none of the code examples provided with SOAP::Lite nor in any of the book examples, is this class used directly. Instead, it is designed to be a superclass within more specific implementation classes. The methods provided by SOAP::Server itself are:

new( optional key/value pairs )

 $server = SOAP::Server->new(%options);

Creates a new object of the class. Various default instance values are set up, and like many of the constructors in this module, most of the class methods described here may be passed in the construction call by giving the name followed by the parameter (or an array reference if there are multiple parameters).

action( optional new value )

 $action = $server->action

Retrieves or sets the value of the action attribute on the server object. This attribute is used when mapping the request to an appropriate namespace or routine. For example, the HTTP library sets the attribute to the value of the SOAPAction header when processing of the request begins, so that the find_target method described later may retrieve the value to match it against the server's configuration. Returns the object itself when setting the attribute.

myuri( optional new value )

 $server->myuri("http://localhost:9000/SOAP");

Gets or sets the myuri attribute. This specifies the specific URI that the server is answering requests to (which may be different from the value specified in action or in the SOAPAction header).

serializer( optional new value )

deserializer( optional new value )

 $serializer = $server->serializer; $server->deserializer($new_deser_obj);

As with the client objects, these methods provide direct access to the serialization and deserialization objects the server object uses to transform input and output from and to XML. There is generally little or no need to explicitly set these to new values.

options( optional new value )

 $server->options({compress_threshold => 10000});

Sets (or retrieves) the current server options as a hash-table reference. At present, only one option is used within the SOAP::Lite libraries themselves:

compress_threshold

The value of this option is expected to be a numerical value. If set, and if the Compress::Zlib library is available to use, messages whose size in bytes exceeds this value are compressed for transmission. Both ends of the conversation have to support this and have it enabled.

Other options may be defined and passed around using this mechanism. Note that setting the options using this accessor requires a full hash reference be passed. To set just one or a few values, retrieve the current reference value and use it to set the key(s).

dispatch_with( optional new value )

 $server->dispatch_with($new_table);

Represents one of two ways in which a SOAP::Server (or derived) object may specify mappings of incoming requests to server-side subroutines or namespaces. The value of the attribute is a hash-table reference. To set the attribute, you must pass a new hash reference. The hash table's keys are URI strings (literal URIs or the potential values of the SOAPAction header), and the corresponding values are one of a class name or an object reference. Requests that come in for a URI found in the table are routed to the specified class or through the specified object.

dispatch_to( optional list of new values )

 $server->dispatch_to($dir, 'Module',  'Mod::meth');

This is the more traditional way to specify modules and packages for routing requests. This is also an accessor, but it returns a list of values when called with no arguments (rather than a single one). Each item in the list of values passed to this method is expected to be one of four things:

Directory path: If the value is a directory path, all modules located in that path are available for remote use.
Package name: When the value is a package name (without including a specific method name), all routines within the package are available remotely.
Fully qualified method name: Alternately, when the value is a package-qualified name of a subroutine or method, that specific routine is made available. This allows the server to make selected methods available without opening the entire package.
Object reference: If the value is an object reference, the object itself routes the request.

The list of values held by the dispatch_to table are compared only after the URI mapping table from the dispatch_with attribute has been consulted. If the request's URI or SOAPAction header don't map to a specific configuration, the path specified by the action header (or in absence, the URI) is converted to a package name and compared against this set of values.

objects_by_reference( optional list of new values )

 $server->objects_by_reference(qw(My:: Class));

This also returns a list of values when retrieving the current attribute value, as opposed to a single value.

This method doesn't directly specify classes for request routing so much as it modifies the behavior of the routing for the specified classes. The classes that are given as arguments to this method are marked to be treated as producing persistent objects. The client is given an object representation that contains just a handle on a local object with a default persistence of 600 idle seconds. Each operation on the object resets the idle timer to zero. This facility is considered experimental in the current version of SOAP::Lite .

on_action( optional new value )

 $server->on_action(sub {   ...new code   });

Gets or sets the reference to a subroutine that is used for executing the on_action hook. Where the client code uses this hook to construct the action-request data (such as for a SOAPAction header), the server uses the on_action hook to do any last-minute tests on the request itself, before it gets routed to a final destination. When called, the hook routine is passed three arguments:

action: The action URI itself, retrieved from the action method described earlier.
method_uri: The URI of the XML namespace the method name is labeled with.
method_name: The name of the method being called by the request.

on_dispatch( optional new value )

 ($uri, $name) = $server->on_dispatch->($request);

Gets or sets the subroutine reference used for the on_dispatch hook. This hook is called at the start of the request-routing phase and is given a single argument when called:

request: An object of the SOAP::SOM class, containing the deserialized request from the client.

find_target

 ($class, $uri, $name) = $server->find_target($req)

Taking as its argument an object of the SOAP::SOM class that contains the deserialized request, this method returns a three-element list describing the method that is to be called. The elements are:

class: The class into which the method call should be made. This may come back as either a string or an object reference, if the dispatching is configured using an object instance.
uri: The URN associated with the request method. This is the value that was used when configuring the method routing on the server object.
name: The name of the method to call.

handle

 $server->handle($request_text);

Implements the main functionality of the serving process, in which the server takes an incoming request and dispatches it to the correct server-side subroutine. The parameter taken as input is either plain XML or MIME-encoded content (if MIME-encoding support is enabled).

make_fault

 return $server->makefault($code, $message);

Creates a SOAP::Fault object from the data passed in. The order of arguments is: code , message , detail , actor . The first two are required (because they must be present in all faults), but the last two may be omitted unless needed.

B.1.13 SOAP::Server::Parameters

This class provides two methods, but the primary purpose from the developer's point of view is to allow classes that a SOAP server exposes inherit from it. When a class inherits from the SOAP::Server::Parameters class, the list of parameters passed to a called method includes the deserialized request in the form of a SOAP::SOM object. This parameter is passed at the end of the arguments list, giving methods the option of ignoring it unless it is needed.

The class provides two subroutines (not methods), for retrieving parameters from the SOAP::SOM object. These are designed to be called without an object reference in the parameter list, but with an array reference instead (as the first parameter). The remainder of the arguments list is expected to be the list from the method-call itself, including the SOAP::SOM object at the end of the list. The routines may be useful to understand if an application wishes to subclass SOAP::Server::Parameters and inherit from the new class instead.

byNameOrOrder( order, parameter list, envelope )

 @args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @_);

Using the list of argument names passed in the initial argument as an array reference, this routine returns a list of the parameter values for the parameters matching those names, in that order. If none of the names given in the initial array-reference exist in the parameter list, the values are returned in the order in which they already appear within the list of parameters. In this case, the number of returned values may differ from the length of the requested-parameters list.

byName( order, parameter list, envelope )

 @args = SOAP::Server::Parameters::byName ([qw(a b c)], @_);

Acts in a similar manner to the previous, with the difference that it always returns as many values as requested, even if some (or all) don't exist. Parameters that don't exist in the parameter list are returned as undef values.

B.1.14 SOAP::Trace

As was detailed in Chapter 6, this class has no methods or objects. It is used only to manage and manipulate the run-time tracing of execution within the toolkit. In absence of methods, this section reviews the events that may be configured and the ways of configuring them.

Tracing is enabled by the SOAP::Lite import method. This is usually done at compile-time, though it may be done explicitly by calling import directly. The commands for setting up tracing start with the keyword +trace . Alternately, +debug may be used; the two are interchangeable. After the initial keyword, one or more of the signals detailed here may be specified, optionally with a callback to handle them. When specifying multiple signals to be handled by a single callback, it is sufficient to list all of them first, followed finally by the callback, as in:

 use SOAP::Lite +trace =>                method => fault => \&message_level,                trace => objects => \&lower_level;

In the fragment, the reference to message_level is installed as the callback for both method and fault signals, while lower_level is installed for trace and object events. If callbacks aren't explicitly provided, the default tracing action is to log a message to Perl's STDOUT file descriptor. Callbacks should expect a one or more arguments passed in, though the nature of the arguments varies based on the signal.

Any signal can be disabled by prefacing the name with a hyphen, such as -result . This is useful with the pseudo-signal "all," which is shorthand for the full list of signals. The following fragment disables only the two signals, while still enabling the rest:

 SOAP::Lite->import(+trace => all => -result => -parameters);

If the keyword +trace (or +debug ) is used without any signals specified, it enables all signals (as if all were implied ).

The signals and their meaning follow. Each also bears a note as to whether the signal is relevant to a server application, client application, or both.

transport Client only: Triggered in the transport layer just before a request is sent and immediately after a response is received. Each time the signal is sent, the sole argument to the callback is the relevant object. On requests, this is a HTTP::Request object; for responses, it's a HTTP::Response object.
dispatch Server only: Triggered with the full name of the method being dispatched, just before execution is passed to it. It is currently disabled in SOAP::Lite 0.55.
result Server only: Triggered after the method has been dispatched and is passed the results returned from the method as a list. The result values have not yet been serialized when this signal is sent.
parameters Server only: Triggered before a method call is actually dispatched, with the data that is intended for the call itself. The parameters for the method call are passed in as a list, after having been deserialized into Perl data.
headers Server only: This signal should be for triggering on the headers of an incoming message, but it isn't implemented as of SOAP::Lite 0.55.
objects Client or server: Highlights when an object is instantiated or destroyed . It is triggered in the new and DESTROY methods of the various SOAP::Lite classes.
method Client or server: Triggered with the list of arguments whenever the envelope method of SOAP::Serializer is invoked with an initial argument of method . The initial string itself isn't passed to the callback.
fault Client or server: As with the method signal earlier, except that this signal is triggered when SOAP::Serializer::envelope is called with an initial argument of fault .
freeform Client or server: Like the two previous, this signal is triggered when the method SOAP::Serializer::envelope is called with an initial parameter of freeform . This syntax is used when the method is creating SOAP::Data objects from free-form input data.
trace Client or server: Triggered at the entry-point of many of the more-significant functions. Not all the functions within the SOAP::Lite classes trigger this signal. Those that do are primarily the highly visible functions described in the interface descriptions for the various classes.
debug Client or server: Used in the various transport modules to track the contents of requests and responses (as ordinary strings, not as objects) at different points along the way.