About Stateful Web Services

Stateful Web services are those that can preserve their state for long running or distributed transactions. Typically, Web service calls are "stateless", which means that subsequent invocations are completely independent. Since the Host Integrator can suspend sessions, Verastream Web services uses stateful Web services to support this behavior. Stateful Web services automatically use the session server suspend/resume functionality.

Invoking stateful Web services

There are two different ways to invoke Verastream Host Integrator Web services.

The first, and preferred, method is:

• Standards-based method Host Integrator SOAP Web services implement the WS-Resource standard, which includes WS-Addressing. If the Web service client understands WS-Resource and WS-Addressing, it can automatically offer stateful behavior with minimal additional programming.

  REST services do not understand WS-Resource or WS-Addressing. REST stateful services use environment variables to carry the session ID.

• rsResourceCreate is called to suspend the session (create a resource) and returns a session ID. The session ID can be used for any number of transactions.

• rsResourceDestroy is called to free the session when it is no longer needed.

The second method is:

• Inband support method - SOAP services If the Web service client does not understand WS-Resource and WS-Addressing, or has difficulty importing WSDLs that contain references to WS-Resources and WS-Addressing, you can disable this feature on the session server Web service property page in the Administrative Console. However, disabling standards support does not disable stateful Web services in Host Integrator. You can use inband support.

  What does "inband" support mean?

  Inband support uses proprietary data types in the Web service document payload, instead of using the SOAP header which WS-Resources and WS-Addressing normally require. Because the Web service client tools don't automatically know how to use our proprietary inband support, you have to manually program stateful Web services.

  • Use wsResourceCreate to allocate a resource (a VHI session) that you will use for multiple invocations on the Web service. The return document includes the session id. You will use this session id for subsequent Web service invocations.

  • Invoke as many methods on the service, as many times as you need. For each invocation, you need to send the session id obtained in step one, in the session id field of the optional environment variables defined in the WSDL.

  • When you are finished with the resource (VHI session), use wsResourceDestroy to free the session. For wsResourceDestroy, you need to send the session id obtained in step one, in the session id field of the optional environment variables defined in the WSDL.

The Web service configuration setting suspend timeout controls how long you can leave the session inactive. The Web service will return a SOAP fault, saying the requested resource is not available if you attempt to use the resource after you have destroyed it, or after the suspend timeout has expired.

Load Balancing and Failover

Web Services are not load balanced but rather the session server on which the Web service resides can be load balanced.

In order for clients to take advantage of the VHI load balancing and fail over feature when using Web services they must specify the "connect via domain" or "specify a domain server" in the SOAP request or use environment variables to ensure that the Web service calls the appropriate session server. Refer to the VHI domain documentation for further information on VHI load balancing and fail over, especially Configuring Management Servers for Failover under General Management Services.