org.iids.aos.systemservices
Interface WSGateway

All Superinterfaces:

SystemService

All Known Implementing Classes:

WSGatewayAgentModule, WSGatewayAgentModule.WSGatewayAgent

public interface WSGateway
extends SystemService

Interface of the web service gateway. SOAP-specific, but SOAP transport-independent.

Author:

Patrick Verkaik See separate design document on the web service extension to AOS.

Field Summary

static int	ERROR_COULD_NOT_PARSE_WSDL In requestWSDLAccess(), an error occurred while parsing the WSDL document.
static int	ERROR_IO In sendSOAPRequest(), an error occurred while communicating with the web service.
static int	ERROR_LEASE_EXPIRED In sendSOAPRequest(), parameter 'leaseID' expired or was invalid, for the given agent ID.
static int	ERROR_MALFORMED_SOAP_REQUEST In sendSOAPRequest(), parameter 'request' was not a valid SOAP request.
static int	ERROR_MALFORMED_URL In requestWSDLAccess(), parameter 'wsdl' was not a valid URL.
static int	ERROR_NO_EXCLUSIVE_TRANSPORT In requestWSDLAccess(), the WS gateway did not grant 'exclTransport = true'.
static int	ERROR_UNKNOWN_PORT In sendSOAPRequest(), parameter 'portName' was invalid or not found.
static java.lang.String	WSGATEWAY_ADDRESS WSGateway's principal ID registration in the lookup service.

Method Summary

void	publishService(java.lang.String serviceName, AgentHandle publisher, java.lang.String className, byte[] jar)
int	requestWSDLAccess(java.lang.String wsdl, java.lang.String serviceName, java.lang.String serviceNameSpace, java.lang.Boolean exclTransport, AgentHandle handle) Called by an agent server (on behalf of an agent) to request access to a web service specified by a WSDL document.
java.lang.String	sendSOAPRequest(java.lang.String request, java.lang.String portName, java.lang.Integer leaseID, AgentHandle handle) Called by an agent server (on behalf of an agent) to carry out a SOAP operation.
void	unPublishService(java.lang.String serviceName)

Methods inherited from interface org.iids.aos.systemservices.SystemService

pingService, shutdown, unbind

Field Detail

ERROR_MALFORMED_URL

static final int ERROR_MALFORMED_URL

In requestWSDLAccess(), parameter 'wsdl' was not a valid URL.

See Also:

MalformedURLException, Constant Field Values

ERROR_COULD_NOT_PARSE_WSDL

static final int ERROR_COULD_NOT_PARSE_WSDL

In requestWSDLAccess(), an error occurred while parsing the WSDL document.

See Also:

CouldNotParseWSDL, Constant Field Values

ERROR_NO_EXCLUSIVE_TRANSPORT

static final int ERROR_NO_EXCLUSIVE_TRANSPORT

In requestWSDLAccess(), the WS gateway did not grant 'exclTransport = true'.

See Also:

NoExclusiveTransport, Constant Field Values

ERROR_LEASE_EXPIRED

static final int ERROR_LEASE_EXPIRED

In sendSOAPRequest(), parameter 'leaseID' expired or was invalid, for the given agent ID.

See Also:

LeaseExpired, Constant Field Values

ERROR_UNKNOWN_PORT

static final int ERROR_UNKNOWN_PORT

In sendSOAPRequest(), parameter 'portName' was invalid or not found.

See Also:

UnknownPort, Constant Field Values

ERROR_MALFORMED_SOAP_REQUEST

static final int ERROR_MALFORMED_SOAP_REQUEST

In sendSOAPRequest(), parameter 'request' was not a valid SOAP request.

See Also:

MalformedSOAPRequest, Constant Field Values

ERROR_IO

static final int ERROR_IO

In sendSOAPRequest(), an error occurred while communicating with the web service.

See Also:

RemoteException, Constant Field Values

WSGATEWAY_ADDRESS

static final java.lang.String WSGATEWAY_ADDRESS

WSGateway's principal ID registration in the lookup service.

See Also:

Constant Field Values

Method Detail

requestWSDLAccess

int requestWSDLAccess(java.lang.String wsdl,
                      java.lang.String serviceName,
                      java.lang.String serviceNameSpace,
                      java.lang.Boolean exclTransport,
                      AgentHandle handle)
                      throws org.apache.xmlrpc.XmlRpcException

Called by an agent server (on behalf of an agent) to request access to a web service specified by a WSDL document. As part of this call, the WS gateway creates a lease, which acts a context in which the agent interacts with the web service. Multiple leases may be requested for the same parameter set.

SOAP communicates over transport sessions whose protocols and contact points are specified in the WSDL document. (Typically these are HTTP sessions.) Some web services associate client state with the transport sessions. An agent may optionally specify that it requires the same transport sessions to be used consistently by this lease and that other leases (of other agents or of the same agent) cannot share the transport sessions.

Parameters:

wsdl - a URL pointing to a WSDL document

serviceName - the requested web service in the WSDL document

serviceNameSpace - the XML name space of serviceName

exclTransport - if true, the agent requires transport sessions to be maintained for the duration of the lease, not to be shared by other leases, and to use at most one transport session per web service port

handle - the agent identifier

Returns:

a lease ID

Throws:

org.apache.xmlrpc.XmlRpcException - containing one of: ERROR_MALFORMED_URL, ERROR_COULD_NOT_PARSE_WSDL, ERROR_NO_EXCLUSIVE_TRANSPORT

sendSOAPRequest

java.lang.String sendSOAPRequest(java.lang.String request,
                                 java.lang.String portName,
                                 java.lang.Integer leaseID,
                                 AgentHandle handle)
                                 throws org.apache.xmlrpc.XmlRpcException

Called by an agent server (on behalf of an agent) to carry out a SOAP operation. The operation is carried out by sending a SOAP request to a web service and receiving the SOAP response.

Parameters:

request - a SOAP envelope containing the request, including the name of the operation

portName - port inside the web service that contains the SOAP operation

leaseID - a lease identifier returned by requestWSDLAccess

handle - the agent identifier, which must correspond to the agent identifier passed to requestWSDLAccess

Returns:

a SOAP envelope containing the response

Throws:

org.apache.xmlrpc.XmlRpcException - containing one of: ERROR_LEASE_EXPIRED, ERROR_UNKNOWN_PORT, ERROR_MALFORMED_SOAP_REQUEST, ERROR_IO

publishService

void publishService(java.lang.String serviceName,
                    AgentHandle publisher,
                    java.lang.String className,
                    byte[] jar)
                    throws WSGatewayException

Throws:

WSGatewayException

unPublishService

void unPublishService(java.lang.String serviceName)
                      throws WSGatewayException

Throws:

WSGatewayException