z/TPF and WebSphere Application Server in a Service Oriented Architecture

30 z/TPF and WebSphere Application Server in a Service Oriented Architecture

3.1 SOAP handler

When a SOAP message arrives on the z/TPF system, it triggers a specified path to get

executed, which can be seen in the diagram in Figure 3-1 on page 30.

Figure 3-1 Inbound flow of a SOAP message in z/TPF

The input message has to be handed to the SOAP handler by the communications protocol

software. The SOAP handler receives three pieces of input:

򐂰 An input message structure:

A soapMsg structure

1

containing the SOAP input message

򐂰 An output message structure:

A soapMsg structure

1

in which the application has to build its SOAP output message

򐂰 Communications binding information:

A commsBinding structure

1

that contains information about the communications protocol

and the application routing information

The SOAP handler performs the following tasks:

1. Invokes the SOAP handler user exit:

The z/TPF SOAP handler user exit is shared object CSO2. It allows you to specify

translation of a SOAP message, log messages, or any other user specific processing your

system requires to process the input SOAP message. The SOAP handler handles the

following predefined return codes from the z/TPF SOAP handler user exit:

– TPF_CONTINUE_DO_NOT_TRANSLATE

Translation was completed by the user exit, so processing continues.

1

The detailed contents of these structures are discussed in Chapter 3.5, “SOAP structures” on page 44.

SOAP Handler

SOAP Handler

User Exit

User Exit

Input Message

Input Message

Translator

Translator

B2B XML

B2B XML

Scanner

Scanner

SOAP Syntax

SOAP Syntax

Checker

Checker

SOAP Application

SOAP Application

Handler

Handler

SOAP

SOAP

Handler

Handler

1

2

3

4

5

Chapter 3. z/TPF SOAP processing 31

– TPF_CONTINUE_DO_TRANSLATE

Translation was not completed by the user exit, so the SOAP handler attempts to

translate the SOAP message.

– TPF_TRANS_FAILED_RECEIVER:

The SOAP handler user exit determined that an error occurred that was caused by the

receiver, which is the z/TPF system. The SOAP fault builder

2

is called and a fault

message is built and returned to the client.

– TPF_TRANS_FAILED_SENDER

The SOAP handler user exit determined that an error occurred that was created by the

sender. The SOAP fault builder

2

is called and a fault message is built and returned to

the sending client.

The SOAP handler also handles the ErrorReplyNeeded return code, which indicates that

the SOAP application encountered an error but did not create the fault message. The

SOAP handler calls the SOAP fault builder

2

to create the fault message.

When the SOAP handler receives any other return codes from another component, it

simply returns to the communications binding.

By default the SOAP handler user exit is empty and returns the value

TPF_CONTINUE_DO_TRANSLATE. Example 3-1 shows the way the SOAP handler user

exit is shipped with z/TPF.

2. Translates the input message if necessary:

Depending on the return code from the SOAP handler user exit, the input message is

translated to the host encoding of the z/TPF system.

3. Invokes the B2B XML scanner:

For more about the B2B XML scanner, see Chapter 5, “XML on z/TPF” on page 79.

4. Checks the SOAP syntax:

The SOAP handler performs the following syntax checks:

– The document must not contain a Document Type Definition (DTD) or any processing

instructions.

– The document must not have a standalone=no value in the docSwitches field of the

infoNodes structure.

– The document must contain a SOAP envelope.

– The SOAP envelope must be namespace-qualified.

– If the document contains a header element, it must follow immediately after the

envelope element.

– If the document contains a header element, it must be namespace-qualified.

– The document must contain a body element.

– The body element must follow the header element if one is present or follow

immediately after the envelope element.

For SOAP version 1.1, if the document contains a mustUnderstand element, the value

must be 0 or 1.

For SOAP version 1.2, the following additional checks are performed:

– The document must not contain an attribute of encodingStyle in the envelope element.

– If the document contains a mustUnderstand element, the value must be true or false.

2

See Chapter 3.3, “SOAP fault builder” on page 33.