SOAP Session Management

DevKit is compatible only with Studio 6 and Mule 3. To build Mule 4 connectors, see the Mule SDK documentation.

To support SOAP-based connector development, DevKit 3.9.0 comes equipped with the option for the connector developer to define a session token for managing SOAP service connections, SOAP sessions or any service operations requiring a token.

Introduction

Create a session token from your connector code within the @Connect method, and utilize it according to any operations the SOAP service requires.

This is a means to managing user access to the service through the connector. For more information on session token placement inside the body see Enriching the SOAP Body With Session Token.

Session management allows you to:

Inject the session token into:
- HTTP cookies, and headers
- SOAP Headers
- SOAP Payload: chain of responsibility for managing the message payload. This might need to be managed by the WSDL Consumer.
Manage session expiration/timeout
Acquire connection management intelligence (about configurations and reconnection)

Requirements

To enable session management for your connector, the Config class must be annotated with @WsdlProvider and @ConnectionManagement, which require implementation of the following methods, respectively:

For WSDL Management:

@WsdlServiceRetriever
@WsdlServiceEndpoint

For Connection Management:

@Connect
@Disconnect
@ValidateConnection

See the stub for the session management-enabled Config class in the @WsdlProvider with Session Management section below.

Connector Lifecycle with Session Management

The lifecycle of the connector will be modified by "session control", during both fetching of metadata and operation invocation. Before fetching metadata and invoking operations, a connector instance is retrieved from or created in the pool, and then the @Connect method would be invoked to initialize the connection.

Connection pooling works like the current Connection Management mechanism; by using the same kind of pool configuration for the connector instances available via a connector configuration tab. Configuration of existing connector instances or creation of new ones is handled by the user from there.

Since the @Connect method is invoked before any of the common @WsdlProvider methods, all the required parameters for connection must be provided via a @Configurable field or @Connect parameter. Initialization may take place inside the @Connect method in order to save results like session tokens.

@WsdlProvider with Session Management

See the structure of the @WsdlProvider Config class below, noting that the session token should be created in the @Connect method and stored in an instance field for use in whichever part of the SOAP message is required, depending on the case:

@WsdlProvider(friendlyName = "Configuration")
@ConnectionManagement
public class Config {

    private String username;
    private String password;

    @Configurable
    @Default("http://localhost:8088/mockTshirt")
    @Placement(order = 3)
    private String endpoint;

    @Connect
    @TestConnectivity
    public void connect(@ConnectionKey String username,  @Password String password)  throws ConnectionException {
        // obtain session token
    }

    @Disconnect
    public void disconnect() {
        // end connection
    }

    @ValidateConnection
    public boolean isConnected() {
        return false;
    }

    @WsdlServiceRetriever
    public ServiceDefinition getServiceDefinition() {
           return new DefaultServiceDefinition("ServiceID", "tshirt", "tshirt.wsdl","TshirtService","TshirtServicePort");
    }

    @WsdlServiceEndpoint
    public String getServiceEndpoint(ServiceDefinition definition) {
         return endpoint;
    }

    @WsdlHeaders
    public List<Document> cookHeaders(ServiceDefinition serviceDefinition, String operationName){
        // Customize headers with session token
    }

    @WsdlTransportRetriever
    public WsdlTransport resolveTransport(ServiceDefinition serviceDefinition) {
        return new HttpBasicWsdlTransport(getUsername(), getPassword());
    }

    // ...
}

Enriching the SOAP Body With Session Token

With the release of DevKit 3.9.0 the @WsdlBodyEnricher can be used to inject the session token into the SOAP body.

@WsdlBodyEnricher

The method marked @WsdlBodyEnricher should receive an object representing the message payload, and return it modified with the session token.

@WsdlBodyEnricher
    public Document cookPayload(ServiceDefinition serviceDefinition, String operationName, Document payload){
        // Customize payload with session token
    }