SOAP

SOAP Headers

In Portus, the SOAP Headers are used for versioning, the support of conversational SOAP processing, support of transactions, and specific settings on the datasource you are accessing. By default all elements are "empty". To get the default behaviour, all header elements should be left blank, or removed altogether. Example:

<soap:Envelope xmlns:rapdv="http://www.risaris.com/namespaces/xmiddle" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <rapdv:AdabasEmployeeHeader>
      <Version/>
      <ConversationState/>
      <ConversationId/>
      <TransactionState/>
      <TransactionId/>
    </rapdv:AdabasEmployeeHeader>
  </soap:Header>
  <soap:Body>
  ...
  </soap:Body>
</soap:Envelope>

Conversational Processing

Every time a SOAP request is made to Portus, this request must be associated with a specific context. By default, a new context is created and destroyed for every SOAP Request.

The user may also use the SOAP Headers to re-use and re-connect to a specific context.

When a user starts, re-uses, and ultimately finishes with their context, the process is known as a "conversation". In the SOAP Header, the "ConversationState" and "ConversationId" are used for conversational processing, see below for more information.

The Version Element

The 'Version' element is currently unused. It will be brought into use in future versions of Portus.

The ConversationState Element

The 'ConversationState' element is used to control conversation processing. It should be one of the following:

State	Description
New	A new conversation is being started. In this case, the ConversationID ( see below) value must by NULL or an error will occur.
Old	An existing conversation is active with which the current SOAP message should be associated. When the SOAP request is processed, the conversation must remain active as there are further SOAP requests to be sent. The ConversationID found must have been returned as a result of a previous 'new' request. An error will occur if the ConversationId ( see below ) provided cannot be found.
End	An existing conversation is active with which the current SOAP message should be associated. When the SOAP request is processed, the conversation must be terminated. The ConversationID ( see below ) found must have been returned as a result of a previous 'new' request. An error will occur if the ConversationId provided cannot be found.

State

Description

New

A new conversation is being started. In this case, the ConversationID ( see below) value must by NULL or an error will occur.

Old

An existing conversation is active with which the current SOAP message should be associated. When the SOAP request is processed, the conversation must remain active as there are further SOAP requests to be sent. The ConversationID found must have been returned as a result of a previous 'new' request.

An error will occur if the ConversationId ( see below ) provided cannot be found.

End

An existing conversation is active with which the current SOAP message should be associated. When the SOAP request is processed, the conversation must be terminated. The ConversationID ( see below ) found must have been returned as a result of a previous 'new' request.

An error will occur if the ConversationId provided cannot be found.

The ConversationId Element

The ConversationId unquely identifies the conversation, and it returned only after a 'New' request is successfully processed. The user should never modify or create this ID. The ConversationId must be present on an 'Old' or 'End' request.

Transaction Processing

In Portus, the platform's Transaction Manager (TM) will be engaged to handle transactions. A default TM is provided as part of the Portus installation. It can be found in <Portus install dir>/libraries/transactionManagerDummyDll.so. The environment variable TMSTUB is used to point to the transaction manager shared object. This shared object provides interfaces to handle the transaction.

Note: The framework for engaging transaction managers is subject to change. Currently the transactionManagerDummyDll.so does not provide any "real" transactionality. Ostia rre current looking for early adopters to work with us to fully implement and test this technology.

In the SOAP Header, the "TransactionState" and "TransactionId" are used for transactional processing; see the table below for more information.

The TransactionState Element

If a transaction involves modifications that will occur over multiple SOAP messages, the conversational processing logic must be used to associate the SOAP messages and thus the transactional information.

If a transaction involves modifications that will all be completed as part of the one SOAP message, the conversational processing logic is not required.

When the request uses an active conversation, and is add/update/delete, a transaction is implicitly started.

If a conversation is ended before the transaction is committed, a implicit back out will occur.

The Transaction State may be one of the following:

State	Description
Commit	This will cause a commit to be issued when the current SOAP message has been processed. If no conversation existed previously for this SOAP request, an error will result. When returned in the SOAP response, it indicates that the transaction has been committed, and transaction ID is provided for reference.
Backout	This will cause a backout to be issued when the current SOAP message has been processed. If no conversation existed previously for this SOAP request, an error will result. When returned in the SOAP response, it indicates that the transaction has been backed out, and transaction ID is provided for reference.

State

Description

Commit

This will cause a commit to be issued when the current SOAP message has been processed.

If no conversation existed previously for this SOAP request, an error will result.

When returned in the SOAP response, it indicates that the transaction has been committed, and transaction ID is provided for reference.

Backout

This will cause a backout to be issued when the current SOAP message has been processed.

If no conversation existed previously for this SOAP request, an error will result.

When returned in the SOAP response, it indicates that the transaction has been backed out, and transaction ID is provided for reference.

The TransactionId Element

The Transaction ID is purely informational, and has no functional bearing on the transaction process. It is returned on any SOAP message and is intended to be used for tracking purposes.

It is not mandatory to provide the Transaction ID. As only 1 transaction can ever be active on a conversation, Portus will auto-reconnect to the current transaction internally.

Adabas specific headers

When working with Adabas services, there are a number of specific SOAP headers that will be available

These headers are listed in the Using Portus with Adabas section.

Relational database specific headers

When working with relational database services, i.e. MySQL, MS SQL Server, DB2, Oracle, etc, the specific SOAP Header are

SOAGateway_Internal_AutoCommit

Turn off the AutoCommit flag on the database

SOAP Operations for Server Configuration

Portus exposes a number of SOAP operations / methods to retrieve and alter the Portus Server Configuration from any SOAP enabled client.

Note: These interfaces are likely to change in the future, they are provided on a trial basis, be aware that you might have to change any "applications" built on top of these interfaces ! As soon as "stable" interfaces are available, this fact will be announced and documented.

adaptorList

This operation is used to load up a Portus driver library, and return the assoicated internal information.

This operation takes 1 input, libraryName should be set to the name of the library to load and query.

configList

This operation is used to list the current configuration in use by the Portus server. The current configuration is useful where you wish to make changes to existing configuration items, or just to make sure you are not trying to add, for example, a resource URI that is already in use.

This operation currently has no options.

The full configuration document, minus the XML header, is returned in the soap response.

configRemove

This operation is used to reset the value of an item in the configuration, or to remove an item from the configuration.

Only certain items or levels of items may be altered using this operation. The definition in the WSDL shows what elements may be used. Refer to it for further details on what type of items may be removed and what items may only have their value reset.

A configuration item which is reset will assume it's default value if it is an item that cannot be removed from the configuration.

Configuration items changed by this operation are effective as soon as the engine can make them so.

This operation currently has no options.

configReplace

This operation is used to replace the current configuration file, or to write a new configuration to file on the server.

If the element 'configFileName' is omitted or left empty, then the configuration file currently in use will be overwritten - if it is in the configuration directory.

If the element 'configFileName' is specified, then the configuration will be written to a file of that name in the configuration directory.

The newly written configuration will not come into effect until the Portus server is next started.

If the element 'configFileName' was specified, and you wish to use this configuration, then before re-starting the Portus server you must alter the system environment variable XMIDDLE_CONFIGURATION_FILE so that it refers to your new configuration file.

This operation currently has no options.

configSet

This operation is used to set the value of an item in the configuration, or to add an item to the configuration.

Only certain items or levels of items may be altered using this operation. The definition in the WSDL shows what elements may be used. Refer to it for further details on what type of items may be added and what items may only have their value altered.

Configuration items changed by this operation are effective as soon as the engine can make them so.

This operation currently has no options.


Portus	Version 2018-08-24	PDF BOOKS \| HOME UP PREV NEXT