view release on metacpan or  search on metacpan

lib/SOAP/SOM.pod  view on Meta::CPAN

# ======================================================================

=pod

=head1 NAME

SOAP::SOM - provides access to the values contained in SOAP Response

=head1 DESCRIPTION

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. In other words, developers will almost never do this:

    $som = SOAP::SOM->new;

SOAP::SOM objects are returned by a SOAP::Lite call in a client context. For example:

    my $client = SOAP::Lite
        ->readable(1)
        ->uri($NS)
        ->proxy($HOST)
    $som = $client->someMethod();

=head1 METHODS

=over

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

=back

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.

=over

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

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

=item dataof(node)

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

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

=item headerof(node)

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

Acts much like dataof, except that it returns an object of the L<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.

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

=back

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 retu...

=over

=item root

    $root = $som->root;

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

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

=item 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::Dat...

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

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

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

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

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

=item faultcode

    $code = $som->faultcode;

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