Web Service Description Usage Scenarios

2.1.1.1 Scenario Definition

Ability to describe a one way operation of a web service that has no guaranteed delivery semantics. The input message received as part of such an operation MAY be lost.

2.1.1.2 Relates To

VP2

2.1.1.3 Scenario Description

A metrics collection service exposes an operation to client applications to report their application usage metrics. These applications opt to update their individual reporting metrics to such a web service, instead of reporting individual metric. Consequently, a loss of a message is not critical as the next update would provide an updated summary. The target web service exposes an interface to report those metrics. For the sake of efficiency and simplicity, the client applications are not interested in receiving any faults; they simply want to send a message and forget about it until the next time.

<binding ...>						
	...
	<operation name="UpdateStatus">
		<soap:operation delivery="fire-and-forget">
			<input message="UpdateStatusInput"/>
		</soap:operation>
	</operation>
</binding>
						

2.1.2.1 Scenario Definition

Ability to describe a one way operation of a web service that has guaranteed delivery semantics. The input operation received as part of such an operation MUST NOT be lost.

2.1.2.2 Relates To

VP2, VP3

2.1.2.3 Scenario Description

A web service provides a messaging service. This web service is a higher level interface over enterprise messaging capabilities such as JMS. On the publisher side, it exposes an interface that allows applications to publish messages to a logical messaging channel. The publishing clients do not expect to receive a response to their invocation however it is important for them to know that the message has been delivered. So while they make a one-way request, they do want to receive faults if the message could not be successfully published, whether due to a system error on the server side or due to an application error on the server side.

<binding ...>						
	...
	<operation name="CreatePO">
		<soap:operation delivery="guaranteed">
			<input message="CreatePOInput"/>
		</soap:operation>
	</operation>
</binding>
						

2.1.3.1 Scenario Definition

Ability to describe an operation of a web service that MAY include message parts that are document attachments along with other regular messages.

2.1.3.2 Relates To

VP2

2.1.3.3 Scenario Description

A web service is an ebXML [ebXML] web service that requires document-oriented computing. The operations that its interface includes are all actually asynchronous messages with no parameters. All the data to the messages is sent as document attachments. Its description document will then describe the data expected by its operations in terms of the expected attachments and not in terms of its parameters.

<types>
	<complexType name="ReimbursementRequest"/>						
		<element name="amount" type="xsd:float"/>
		<element name="date=" type="xsd:string"/>
	</complexType>
	...
</types>
	
<message name="ReimbursementRequestInput">
	<part name="employeeId" type="xsd:string"/>
	<part name="info" type="ReimbursementRequest"/>
	<attachment name="hotelReceipt" 
		uri="uri to image of hotel receipt"/>
	<attachment name="carRentalReceipt" 
		uri="uri to image of rental car receipt"/>
</message>

<operation name="Reimburse">
	<input message="ReimbursementRequestInput"/>
</operation>
	
						

2.1.4.1 Scenario Definition

Ability to describe an operation of a web service that responds with an output message or a fault based on at least one or more input messages received.

2.1.4.2 Editors' Comments

If UC0001 and UC0002 are accepted, the implications must be well understood and described.

Since the bindings would determine how the messages are actually sent, there may be a need to correlate the request with the response.

2.1.4.3 Relates To

VP1, VP2

2.1.4.4 Scenario Description

Two parties wish to conduct electronic business by the exchange of business documents. The sending party packages one or more documents into a request message, which is then sent to the receiving party. The receiving party then processes the message contents and responds to the sending party. Examples of the sending party's documents may be purchase order requests, manufacturing information and patient healthcare information. Examples of the receiving party's responses may include order confirmations, change control information and contractual acknowledgements.

<binding ...>						
	...
	<operation name="handleRequest">
			<input message="inputData"/>
		<output message="outputData"/>
	</operation>
</binding>
						

2.1.5.1 Scenario Definition

Ability to describe an operation of a web service that returns output message.

2.1.5.2 Editors' Comments

Are the events as described in the scenario of different types? Does it make sense to have an associated semantics of guaranteed delivery?

2.1.5.3 Relates To

VP1

2.1.5.4 Scenario Description

An application subscribes to notifications of certain named events from an event source. When such events occur, notifications are sent back to the originating application (first party notification) or to another application (third party notification). For example, an application can subscribe to notification of various aspects of a printer's status (e.g., running out of paper, ink etc.). The notifications of such events could be delivered to a management application.

2.1.6.1 Scenario Definition

Capture the synchronicity of the operations

2.1.6.2 Relates To

VP2

2.1.6.3 Scenario Description

To negotiate proper communication sequence WS provider has to be able to describe if certain operations can be handled asynchronously, must be handled asynchronously or synchronously and what is the expected execution time. This would allow process orchestration system to properly adjust the flow and not run into unexpected blocking.

Here is an example of operation definitions.

<portType> 
	<operation ... handling="sync async" replyTime="10000"/> <!-- up to the client -->
	<operation ... /> <!-- only sync -->
	<operation ... handling="async" replyTime="unknown"> <!-- long running, human dependent -->
</portType>

WS client would then get to use operations properly. Similar to this.

AsyncContext ctx = service.start_myAsyncOp(...);
MyResult result = service.waitFor_myAsyncOp(ctx);

The underlying WS framework would then initiate proper SOAP [SOAP 1.2 Part 1] messaging sequence with acknowledgement and notification phases. SOAP protocol must support asynchronous messaging.

2.1.7.1 Scenario Definition

Capture event management model for web services

2.1.7.2 Relates To

VP1,VP2

2.1.7.3 Scenario Description

A WS provider can describe events generated by a service as follows:

<message name="hasDataIn">
	<part name="container" type="data:Container"/>
</message>
<message name="hasDataOut">
	<part name="context" type="data:Context"/>
</message>
<portType>
	<operation...
	<event name="hasData1" mode="poll" interval="10">
		<input message="interface:hasDataIn"/>
		<output message="interface:hasDataOut"/>
	</event>
	<event name="hasData2" mode="push">
		<input message="inerface:hasDataIn"/>
		<output message="interface:hasDataOut"/>
	</event>
</portType>

And this way WS client may subscribe to events like this

service.subscribe_hasData1(new data.Container(...),new myServiceListener()) 
service.subscribe_hasData2(new data.Container(...),new myServiceListener())

And implement a proper handler

class myServiceListener
{
	void hasData1(data.Context ctx) { ... }
	void hasData2(data.Context ctx) { ... }
}

The underlying WS framework would take care of the event by either polling (sending a SOAP request) with a specified interval or registering a SOAP listener (endpoint) with the target WS (according to the event definition in WSDL).

We should also describe the SOAP protocol sequence (registration/acknowledgement/notification) for the events in accordance with asynchronous SOAP messaging.

2.2.1.1 Scenario Definition

Declaration of a method that raises multiple faults

2.2.1.2 Relates To

VP1, VP2, VP3

2.2.1.3 Scenario Description

A web service interface method can fail due to several reasons. The faults raised by the method may be semantically different from each other and further more, some of the faults may be standard faults defined for a group of web services. For example, in an accounting system, there may be a general ?creation fault? defined for indicating the failure such as out of resources or PO already exists. The creation of PO could also fail because the data provided to initialize the PO is invalid. The web service method ?createPO? might then fail because of any of the reasons described above and may want to raise separate faults depending on the reason for failure.

<message name="GenericCreationError">
	<part name="reason" type="xsd:string"/>
</message>

<message name="PODataValidationError">
	<part name="inValidField" type="xsd:string"/>
	<part name="reason" type="xsd:string"/>
</message>

<operation name="CreatePO">
	<input message="CreatePOInput"/>
	<output message="CreatePOOutput"/>
	<fault name="CreationFault" message="GenericCreationError"/>
	<fault name="ValidationFault" message="DataValidationError"/>
</operation>
					

2.2.2.1 Scenario Definition

Declaration of service level attributes

2.2.2.2 Relates To

VP1, VP2, VP3

2.2.2.3 Scenario Description

Two web services, implementing the interface for ?looking up for insurance providers?, from different sources are offered in a registry. One of the two services actually performs extensive data validation on the data provided, for example making sure that the zip codes in the address provided are valid?, while the other web service assumes that the data provided is valid and searches for insurance providers has already been validated and uses it to perform its search without any further validation. The interface was developed by an industry consortium that agreed to reflect the data validation capability of the services as a service-level attribute. Some intelligent registries may then actually allow search criteria that can be predicated on these service-level attributes or alternatively, the client application may check the value of the service level attribute itself at runtime to find out its value. The service-level attribute may be mapped to accessor methods which can be invoked either by the intelligent registry as part of executing the search query or by the client application itself.

<types>
	<complexType name="CompanyInfo"/>
		<element name="CompanyName" type="xsd:string"/>						
		<element name="Address" type="xsd:string"/>
	</complexType>
	...
</types>

<portType name="InsuranceProviderPort">
	<attribute name="version" type="xsd:string"/>
	<attribute name="validates" type="xsd:boolean"/>
	<attribute name="companyInfo" type="CompanyInfo"/>
	
	<operation name="ProvideQuote">
		<input message="ProvideQuoteInput"/>
		<input message="ProvideQuoteOutput"/>
		<fault name="quoteFailed" message="ProvideQuoteError"/>
	</operation>
	...
</portType>
						

These attributes are part of the meta data of the service. Although you could possibly model the meta data as operations, this meta data is modeled much more cleanly modeled as attributes.

2.2.3.1 Scenario Definition

Declaration of operational level attributes

2.2.3.2 Relates To

VP1, VP2, VP3

2.2.3.3 Scenario Description

In an advanced architecture where distributed transactions are supported, a web service may want to declare some of its operations as transactional as opposed to the entire interface being transactional. A web service offering various financial related web services may be able to verify a buyer?s credit in a non-transactional manner but may require the client application to start a transaction before invoking the operation to prepare an invoice. The target web service may have a declarator on the method specification that indicates that the operation for invoicing requires transaction.

<operation name="ProvideQuote">
	
	<attribute name="isTransactional" type="xsd:boolean"/>
		
	<input message="ProvideQuoteInput"/>
	<input message="ProvideQuoteOutput"/>
	<fault name="quoteFailed" message="ProvideQuoteError"/>
</operation>

						

2.2.4.1 Scenario Definition

To maintain namespaces through service providers and clients

2.2.4.2 Relates To

VP1, VP3

2.2.4.3 Scenario Description

A service can have an OO model like this:

my.app.model.Address is a base class to represent 
data my.app.impl.Address inherits my.app.model.Address my.app.model.AddressBook is an interface.  my.app.impl.AddressBook is an 
implementation of my.app.model.AddressBook

It is possible to represent this model in WSDL and associated XML Schema [XML Schema Part 1] placing schema and interfaces in the proper XML namespaces. It has to be required that namespaces are not getting lost between service provider and the client. It should be part of WSDL compliance.

Here is a brief example:

<definitions xmlns:model="urn:my.app.model" xmlns:impl="urn:my.app.impl">
<types>
<schema targetNamespace="urn:my.app.model">...
<schema targetNamespace="urn:my.app.impl">...
</types>
<message targetNamespace="urn:my.app.model" ...
<message targetNamespace="urn:my.app.impl" ...
<portType targetNamespace="urn:my.app.model" ...
<portType targetNamespace="urn:my.app.impl" ...

2.2.5.1 Scenario Definition

Specifying interface versioning

2.2.5.2 Relates To

VP1

2.2.5.3 Scenario Description

A WS provider can describe versions of interfaces implemented by a service. Such as this

<definitions xmlns:interface-latest="urn:myService-latest" 
							xmlns:interface-ver1="urn:myService-ver1" ... >
	<binding targetNamespace="urn:myService-latest" 
		version="2.0.0.0"> ... 
	<binding targetNamespace="urn:myService-ver1" 
		version="1.0.0.0"> ... 
	<service name="myServiceService"> 
		<port name="myService" 
			binding="interface-latest:myServiceSoapBinding"> 
			... 
		<port name="myService" 
			binding="interface-ver1:myServiceSoapBinding"> 
			... 
	</service>

WS client can bind to the necessary interface version. This way there is no ambiguity when WS provider changes service interfaces and client has created a static proxy that uses previous version of interfaces.

WS provider can deprecate and remove interfaces as desired, and the client would know that. Client would send a SOAP request that would not be accepted (as namespaces do not match), as opposed to client trying to send a SOAP request that could be accepted, but improperly executed.

2.2.6.1 Scenario Definition

Use case for DR053

2.2.6.2 Relates To

VP1 and VP3

2.2.6.3 Scenario Description

Imagine a component framework in which components and their operations (building finally the component's functionality) should be described with WSDL. In the framework the components are using operations from each other dynamically: in the program code there is no "hard-wired" function call but instead a "semantic description/reference" of what kind of operation to use, which will be dissolved just in time before execution. With this "semantic description" a search for suitable operations could be started in a (logical) centralized registry (maybe with UDDI). The registry contains (WSDL) information of all currently available components/operations within the framework. Result of the search query are the concrete binding parameters (protocol, URL, operation signature, etc.) of the matching operations. Finding a suitable match _automatically_ (without manual/human interaction) will be done by searching in the registered WSDL files for the specified "semantic description". One half of this "semantic description" are the parameters defined with complex XML schema types. The other one should be the determination of the operation (i.e. its functionality). But only considering the operation name has the same drawbacks as comparing parameters only by their name (or even simple types like integer, string, etc.): only operations with exactly the same name as chosen from the operation's programmer are returned. So with introducing a kind of "type system" for operations (or maybe a classification) would bring the benefit that the result set of the above mentioned query could return operations with different names, but which are implementing the same functionality/behavior. With this it would also be possible to exchange one component (respectively their operation/s) with another independently developed one, which has the same functionality but with (maybe only slightly) different operation name(s) - and this without further manual interaction.

2.2.7.1 Scenario Definition

Need to have a hint of how long it will take for the service to process the request.

2.2.7.2 Relates To

VP2

2.2.7.3 Scenario Description

My service invocation contains a routing header in which I specify the return path (the path I want the response to use to come back to me). I may want to provide a different routing path whether I expect the respond to come in one second or in two weeks. For example, for a very quick turnaround I might want to have the response sent directly to me via HTTP [IETF RFC 2616] post because I know I will have a listener available during the next 10 seconds, but if the processing is going to take days I'd rather have the reply go through another route, using always-on intermediary that can store the message for me until I am ready to receive it. In order to be able to choose the most appropriate return path, I need to find in the WSDL an indication of how long the service plans to take to fulfill my request. Note: this use case is not about how to specify the use of a SOAP routing header. It is about how to provide in the WSDL information that allows someone to build the message in a smarter way (for example by optimizing the routing header) because s/he knows more about the expected completion time for the request.

Following is a sample of the routing header as specified according to SOAP binding of WSDL

<binding...>
	<soap:binding ..../>
	<operation ... >	
		<soap:operation .../>
		<input>
			<soap:body ... />
			<soap:header message="some predefined message" 
				part="a part of that message"/>
		</input>
	</operation>
</binding>
						

2.2.8.1 Scenario Definition

Specifying streaming with input or output

2.2.8.2 Relates To

VP1, VP2

2.2.8.3 Editor's Comment

It seems like this would require specifying header elements to indicate streaming

2.2.8.4 Scenario Description

A webcam is plugged in to a network. A user sends through the network an HTTP request to get the video. The webcam answers to this request by streaming the video to the user. The user sends another request to stop the streaming. I think WSDL should provide a way to express that it will use streaming at some point. Streaming might be used at two levels: - at the protocol level : the service may transmit the result by streaming - at the data type level : the service may indicate that it will receive/send streaming as input/output..

<binding...>
	<soap:binding ..../>
	<operation ... >	
		<soap:operation .../>
		<input>
			<soap:body ... />
			<soap:header message="some predefined message" part="a part of that message"/>
		</input>
	</operation>
</binding>
						

2.2.9.1 Scenario Definition

Extend existing portTypes to make new ones by including and reusing features/behavior specified by the existing portTypes.

2.2.9.2 Relates To

VP1, VP2

2.2.9.3 Scenario Description

Vertical standards organizations like the UPnP Forum [UPnP] are defining device-specific standards, ranging from home appliances, to entertainment, to small office appliances. The UPnP Forum and others would like to use WSDL as their machine-readable description language.

A working committee within UPnP may wish to define a core set of behaviors to be implemented by all devices of a particular type as well as an extended set of behaviors to be implemented by advanced devices. For example, imagine that an audio-visual working committee is defining analog TV tuner functionality; to support standardized behavior in inexpensive as well as expensive TV sets, they define two sets of operations: a minimal set (like channel up / down) and an extended set (like minimal plus jump to previous channel). Within WSDL, a natural way for such a working committee to define these behaviors is to use port types: a "basic tuner" port type with the core operations and an "extended tuner" port type that has the superset.

This has the mildly awkward disadvantage that the definition of the "extended tuner" must re-list each of the operations previously defined in "basic tuner".

When building a UPnP TV device, a vendor may wish to include two analog TV tuners to support a feature like picture-in-picture. Within WSDL, a natural way to expose this is as two ports of the correct type. This works as expected if the device includes two analog tuners with only basic functionality: there are two ports, each of type "basic tuner". Clients that wish to control the device can parse the WSDL for the device and correctly recognize that the device supports two tuners with the basic functionality.

However, consider the case where the vendor wishes to include two analog tuners with extended functionality. At a minimum, within the WSDL for that device, they need to include two ports of type "extended tuner". In order to support down-level clients (say written only to use "basic tuner"), a vendor would be inclined to also include two ports of type "basic tuner". However, such WSDL would likely be very confusing to a client: how many tuners does the device actually contain?

For the sake of completeness, note working committees in the UPnP Forum also define standards for how many of each port type are in a type of device. Thus, the vendor's dilemma is also encountered within the standard WSDL descriptions a working committee would produce.

A possible solution to this would be to allow one port type to derive from another by extending the set of operations supported. The description of the "extended tuner" would not have to re-list the operations defined by the "basic tuner", but more importantly, the dual-tuner device could list just two ports of type "extended tuner", and down-level clients could look at the derivation of the port type to recognize the "basic tuner".

2.3.1.1 Scenario Definition

To support passing references to web services as operation input or output.

2.3.1.2 Relates To

VP1, VP2, VP3

2.3.1.3 Scenario Description

A WS provider can define operations that return and/or take as a parameter a reference to another WS interface.

Here is an example of extended attribute definitions and inclusion.

The definition would look as follows:

<definitions ... xmlns:ref="http://schemas.xmlssoap.org/wsdl/ref> 
<message name="..."> 
	<part name="param" type="ref:ref"> 
<message> 

A schema for http://schemas.xmlssoap.org/wsdl/ref is as follows :

<schema targetNamespace="http://schemas.xmlssoap.org/wsdl/ref" xmlns:ref="http://schemas.xmlssoap.org/wsdl/ref">
	<complexType name="ref">
	<all>
		<element name="description" nillable="true" type="xsd:string"/>
		<element name="service" type="xsd:QName"/>
		<element name="port" nillable="true" type="xsd:string"/>
	</all>
	</complexType>
	<element name="ref" type="ref:ref"/>
</schema>

Then a WS client can use references to the interfaces as follows:

MyExtSvc esvc = new MyExtSvc(service.myMethodReturnungRef(...))

The underlying WS framework would support instantiation of a service based on reference (like most already instantiate based on an endpoint URL).

I believe systinet does something similar, but unless it's mandated by the WSDL standard it is as good as private app-specific extension.

2.4.1.1 Scenario Definition

Capture service related meta data

2.4.1.2 Relates To

VP1, VP2

2.4.1.3 Scenario Description

A WS provider can decorate various elements of the service description with custom attributes. These attributes may be application specific and would be described by the WS provider in an additional documentation. Such custom attributes may be defined in a specific schema. WS provider may include such extra information as owner e-mail, link to SLA, security and session requirements for a particular message, etc.

Here is an example of extended attribute definitions and inclusion.

<descriptions ... > 
<extend xmlns:myExt="..."> 
<myExt:owner id="owner1" email="myadmin@mycorp.com/> 
<myExt:sec id="sec1" signatureRequired="yes"/> <myExt:sess id="sess1" cookie="MYCTX"/> 
</extend> 
<types>... 
<message extend="sec1 sess1" ... <portType... <binding ... <service extend="owner1" ...

A WS client can interrogate the metadata attributes as follows:

NodeList ext = service.getExtend();

Similarly for message descriptions.

2.5.1.1 Scenario Definition

This scenario provides requires web services to have predefined method for obtaining wsdl from the web service

2.5.1.2 Relates To

VP1

2.5.1.3 Scenario Description

A webcam is plugged in to a network. This webcam can describe its services through a pre-loaded WSDL file. I think it is important to keep in mind that WSDL files may be published by such devices (where space is valuable and/or read-only) as well as by big servers. It should also be possible for a user to contact the webcam and get its WSDL description. Should we make a standard way to retrieve from a web service its description (like making an HTTP get request to an HTTP web service will trigger the web service to send its description)? Is it let to a higher level ?

2.5.2.1 Scenario Definition

The WSDL specification should define a notion of equivalence of definitions that would be used by registry and repository implementors.

2.5.2.2 Relates To

VP1

2.5.2.3 Scenario Description

WSDL documents will be registered in registries such as [UDDI] and stored in repositories. The operations of storage and retrieval must preserve the meaning of the WSDL.

The definitions in a WSDL document do not exactly match the entities stored in a UDDI registry. There is a Best Practices document [UDDI Best Practices] that specifes a mapping between WSDL and UDDI. When a service described by a WSDL document is registered in UDDI, some of the WSDL definitions are converted to UDDI entities. When a user discovers a service in a UDDI registry, processors will extract some entities from UDDI and convert them to WSDL definitions. The result of storing and retrieving WSDL information must preserve its meaning.

Similarly, WSDL documents may be stored in repositories that stored them in a non-WSDL format, for example a relational database. When the documents are retrieved as WSDL their meaning must be preserved.

The WSDL specification should define a notion of equivalence of definitions that would be used by registry and repository implementors.