NAME

Kernel::GenericInterface::Transport::HTTP::SOAP – GenericInterface network transport interface for HTTP::SOAP

PUBLIC INTERFACE

has Operation

Attribute that holds the operation name.

has ContentType

Attribute that holds the content type.

ProviderProcessRequest()

Process an incoming web service request. This function has to read the request data from the web server process.

Based on the request the Operation to be used is determined.

No out-bound communication is done here, except from continue requests.

In case of an error, the resulting http error code and message are remembered for the response.

    my $Result = $TransportObject->ProviderProcessRequest();

    $Result = {
        Success      => 1,                  # 0 or 1
        ErrorMessage => '',                 # in case of error
        Operation    => 'DesiredOperation', # name of the operation to perform
        Data         => {                   # data payload of request
            ...
        },
    };

ProviderGenerateResponse()

Generates response for an incoming web service request.

In case of an error, error code and message are taken from environment (previously set on request processing).

The HTTP code is set accordingly – 200 for (syntactically) correct messages – 4xx for http errors – 500 for content syntax errors

    my $Result = $TransportObject->ProviderGenerateResponse(
        Success => 1
        Data    => { # data payload for response, optional
            ...
        },
    );

    $Result = {
        Success      => 1,   # 0 or 1
        ErrorMessage => '',  # in case of error
    };

RequesterPerformRequest()

Prepare data payload as XML structure, generate an outgoing web service request, receive the response and return its data.

    my $Result = $TransportObject->RequesterPerformRequest(
        Operation => 'remote_op', # name of remote operation to perform
        Data      => {            # data payload for request
            ...
        },
    );

    $Result = {
        Success      => 1,        # 0 or 1
        ErrorMessage => '',       # in case of error
        Data         => {
            ...
        },
    };

PRIVATE INTERFACE

_Error()

Take error parameters from request processing. Error message is written to debugger, written to environment for response. Error is generated to be passed to provider/requester.

    my $Result = $TransportObject->_Error(
        Summary   => 'Message',    # error message
        HTTPError => 500,          # http error code, optional
    );

    $Result = {
        Success      => 0,
        ErrorMessage => 'Message', # error message from given summary
    };

_Output()

Generate http response for provider and send it back to remote system. Environment variables are checked for potential error messages. Returns structure to be passed to provider.

    my $Result = $TransportObject->_Output(
        HTTPCode => 200,           # http code to be returned, optional
        Content  => 'response',    # message content, XML response on normal execution
    );

    $Result = {
        Success      => 0,
        ErrorMessage => 'Message', # error message from given summary
    };

_SOAPOutputRecursion()

Convert Perl data structure into a structure usable for SOAP::Lite.

Because some systems require data in a specific order, the sort order of hash ref entries (and only those) can be specified optionally. If entries exist that are not mentioned in sorting config, they will be added after the sorted entries in ascending alphanumerical order.

Example: $Data = { Key1 => 'Value', Key2 => { Key3 => 'Value', Key4 => [ 'Value', 'Value', { Key5 => 'Value', }, ], }, }; $Sort = [ # wrapper for level 1 { # first entry for level 1 Key2 => [ # wrapper for level 2 { # first entry for level 2 Key4 => [ undef, undef, [ # wrapper for level 3 { Key5 => undef, # first entry for level 3 }, ], # wrapper for level 3 ], }, # first entry for level 2 { # second entry for level 2 Key3 => undef, }, # second entry for level 2 ], # wrapper for level 2 } # first entry for level 1 { # second entry for level 1 Key1 => undef, } # second entry for level 1 ]; # wrapper for level 1

    my $Result = $TransportObject->_SOAPOutputRecursion(
        Data => {           # data payload
            ...
        },
        Sort => {           # sorting instructions, optional
            ...
        },
    );

    $Result = {
        Success      => 1,  # 0 or 1
        ErrorMessage => '', # in case of error
        Data         => {   # data payload in SOAP::Data format
            ...
        },
    };

_SOAPOutputHashRecursion()

This is a part of _SOAPOutputRecursion. It contains the functions to process a hash key/value pair.

    my $Result = $TransportObject->_SOAPOutputHashRecursion(
        Data => { # data payload
            ...
        },
        Sort => { # sort data payload
            ...
        },
    );

    $Result = {
        Success      => 1,  # 0 or 1
        ErrorMessage => '', # in case of error
        Data         => (   # data payload in SOAP::Data format
            ...
        ),
    };

_SOAPOutputProcessString()

This is a part of _SOAPOutputRecursion. It contains functions to quote invalid XML characters and encode the string

    my $Result = $TransportObject->_SOAPOutputProcessString(
        Data => 'a <string> & more',
    );

    $Result = 'a &lt;string> &amp; more';

_SOAPOutputTypesGet()

Determine and validate types of data and (optional) sort attributes.

The structure may contain multiple levels with scalars, array references and hash references. Empty array references and array references directly within array references are not permitted as they don't have a valid XML representation. Undefined data and empty hash references are treated as empty string.

The sorting structure has to be equal to the data structure with hash references replaced by an array reference and its elements wrapped in individual hash references. Values in the sorting structure are ignored but have to be specified (at least 'undef') for correct type detection.

    my $Result = $TransportObject->_SOAPOutputTypesGet(
        Data => {           # data payload
            ...
        },
        Sort => {           # sorting instructions, optional
            ...
        },
    );

    $Result = {
        Success      => 1,              # 0 or 1
        ErrorMessage => '',             # in case of error
        Data         => 'HASHREF',      # type of data content
        Sort         => 'ARRAYREF',     # type of sort content
    };