Design Guide for Specifications Built on the Devices Profile for Web Services

8/2/2019 Design Guide for Specifications Built on the Devices Profile for Web Services

http://slidepdf.com/reader/full/design-guide-for-specifications-built-on-the-devices-profile-for-web-services 1/28

An OASIS White Paper

Design Guide for specifications built on the DevicesProfile for Web Services

By Dan Driscoll (Microsoft Corporation)

For OASIS



Last revision 3 May 2012 2

OASIS (Organization for the Advancement of Structured Information Standards) is a not-for-profit, international consortium

that drives the development, convergence, and adoption of e-business standards. Members themselves set the OASIS technical

agenda, using a lightweight, open process expressly designed to promote industry consensus and unite disparate efforts. The

consortium produces open standards for Web services, security, e-business, and standardization efforts in the public sector and

for application-specific markets. OASIS was founded in 1993. More information can be found on the OASIS website at

http://www.oasis-open.org.

The OASIS Web Services Discovery and Web Services Devices Profile (WS-DD) Technical Committee produces the SOAP-over-

UDP, Web Services Discovery (WS-Discovery), and Devices Profile for Web Services (DPWS) specifications for communicating

SOAP over UDP, providing a lightweight dynamic discovery protocol to locate web services, and profiling existing Web Services

protocols to be suitably implemented on devices, respectively. More information can be found on the OASIS WS-DD website at

http://www.oasis-open.org/committees/ws-dd/.



Design Guide for specifications built on the Devices Profile for Web Services

Table of Contents

Introduction...................................................................................................... 5

Goals and audience....................................................................................... 5

Additional materials ....................................................................................... 5

Overview.......................................................................................................... 5

Terminology .................................................................................................... 6

Section 1: Abstract protocol design on DPWS............................................ 7

Terminology for this section ......................................................................... 7

Organizing services on a device.................................................................. 7

Organizing operations within a service ....................................................... 9Adding parameters to operations .............................................................. 11

Event delivery and filtering ......................................................................... 13

Bindings ......................................................................................................... 14

Service and device types ............................................................................ 15

Faults ............................................................................................................. 16

Abstract service design guidelines ............................................................ 16

Section 2: Creating a specification from an abstract protocol ................. 18

Anatomy of a specification built on DPWS............................................... 18

Referencing DPWS...................................................................................... 19

Choosing a namespace .............................................................................. 21

Section 3: Creating a WSDL/XSD .............................................................. 23

Step 1: Organize abstract protocol definition........................................... 23

Step 2: Copy the WSDL template ............................................................. 23

Step 2: Convert services to WSDL portTypes ......................................... 24

Step 3: Add portTypes for WS-Discovery types ...................................... 25

Step 4: Convert method calls to WSDL operations ................................ 25

Step 5: Add WSDL messages ................................................................... 26

Step 6: Convert types into XSD types ...................................................... 26

Step 7: Define XSD elements .................................................................... 27

Step 8: Include the namespace ................................................................. 28




Introduction

The Devices Profile for Web Services (DPWS) assembles and constrains generic Web Services

specifications so devices can easily and uniformly implement functionality common across many different

device classes, such as embedded sensors, kitchen appliances, printers, and even device emulatorsrunning on servers.

Although DPWS defines discovery and metadata operations common to all devices, it does not define the

operations specific to any particular device class. Instead, it provides a toolkit of profiled optional

functionality that is available from many DPWS implementations, and which may be used to construct

sophisticated device control specifications.

This document provides design guidance for specifications that rely on DPWS, and provides direction on

how to reference and use the various components inside it.

Goals and audience

This guide is intended to provide guidance and best practices in designing a specification that referencesDPWS. It is intended primarily for specification authors building public device control protocols. This

document focuses on the most common uses for DPWS.

This guide is not intended to provide a comprehensive set of requirements and recommendations for

referencing DPWS, and is specifically not designed to address unusual or exotic uses.

Additional materials

The OASIS Web Services Discovery and Web Services Devices Profile (WS-DD) Technical Committee

has produced additional materials describing the DPWS and the other specifications standardized

alongside it (WS-Discovery and SOAP-over-UDP). Business- and technical-level whitepapers on all of

these specifications are available from the WS-DD TC.

A companion document to this guide is the DPWS Toaster Example Version 1.0 specification. The

example specification is annotated with recommendations and best practices and can serve as an

additional resource in producing a specification built on DPWS.

Overview

This document is divided into three sections, each covering one of the aspects of protocol and

specification design. The first section provides direction on abstract protocol design, and can be used to

best identify which parts of DPWS can best be used to solve problems for a particular device class.

The second section describes the process of building normative text that references DPWS and uses the

protocol elements designed earlier.

The last section provides concrete steps for transforming a set of abstract protocol definitions into a

WSDL and XSD file suitable for most Devices Profile stacks.




Terminology

DPWS The Devices Profile for Web Services (DPWS) assembles and constraints

generic Web Services specifications.

Specification In this document, the term specification refers to a protocol specification

specific to a particular device class (e.g., toasters). The DPWS Toaster

Example Version 1.0 is a sample specification built on DPWS.

Client A client is a network endpoint that implements the CLIENT role as defined in

DPWS.

Device A Device consists of a DEVICE and zero or more HOSTED SERVICEs, as defined

in DPWS. DPWS distinguishes the DEVICE service as a special service; this

guide refers to a Device as a collection of services related to a single physical

instance or logical grouping (such as an emulator).

Host Service Synonymous with the DEVICE service

Hosted Service A Hosted Service is a network endpoint that implements the HOSTED SERVICE

role as defined in DPWS.




Section 1: Abstract protocol design on DPWS

The most challenging part of designing a network protocol—even one built on existing frameworks like

DPWS—is defining the structure, contents, and behaviors of the messages sent to and from the device.

Designing the right set of operations is a matter of finding the balance between feature requests,implementation constraints, similar protocols, and technology available in devices.

These factors depend heavily on the environment in which a solution is written. This environment varies

across device classes, and it also varies across individual protocol solutions in each class. Examining

and accommodating these factors is left as an exercise to the reader.

However, there are some general guidelines and best practices that cut across all solutions built on

DPWS, and this section describes those in detail. They are not a substitute for informed protocol design,

but can be used to supplement it.

Terminology for this section

This terminology is used primarily in this section, and in Section 3.

Service A DPWS Hosted Service that exposes functionality to network-attached

clients.

Service type A name that defines a set of operations. A service may implement more than

one type.

Operation A one-way or two-way exchange of messages between a client and a service.

Message A SOAP message with a header and a body. The header contains addressing

and other information, and the body contains parameters.

Parameter Content carried inside a message body. Multiple parameters may bestructured and carried inside a single message.

Organizing services on a device

DPWS describes a basic model for a device: a Host (or “DEVICE”) service handles all discovery and

metadata traffic on the device, and one or more Hosted Services handle control messages specific to a

particular class of devices. Attributes describing those Hosted Services are listed inside the device’s

metadata and can be accessed by client software before connecting to each service.

The organization of Hosted Services within a device is largely unconstrained by DPWS. A device mayhave zero or more services, and those services each have one or more types that describe their

behavior. A single device may contain multiple services; those services may have identical types, they

may have different types defined by a single specification, and they may be of different types defined by

different specifications.




Figure 1 shows a sample service arrangement on a hypothetical toaster/printer device. The first service

implements the Toasting service defined in the attached Toaster example specification. The second

service implements this type and a Printing type—ostensibly since that service can perform both toasting

and printing duties. The last service is a Safety service, as defined in the Toaster specification.

Often, a specification will only define a single service type. This is the most typical solution and is

absolutely acceptable. The attached Toaster example shows a more complex topology with two different

service types, but this complexity is included to illustrate how to properly constrain service composition.

Specification authors should expect that implementers will want to combine services for different device

classes in the same DPWS solution. This composability is one of the core benefits of DPWS and most

specifications are written with this pattern in mind.

In all cases, functionality encapsulated in a particular type should be cohesive and should reflect the

natural breakdown of device services. Individual operations inside a service can be defined as optional,

and so it is usually unwise to artificially split a set of cohesive operations down further into mandatory and

optional components.

Recommendations on organizing services in a device

1. Consider how devices in your class are typically organized and build a structural service model to

best accommodate those designs.

2. Define types that encapsulate cohesive sets of functionality.

Host Service

Hosted Service

Type: Toasting

Hosted Service

Type: Toasting

Type: Printing

Hosted Service

Type: Safety

Figure 1: Example service topology




3. Do not artificially split types into mandatory and optional sections; instead, make individual

operations inside a type optional.

4. Expect that implementers will want to combine your services with services from other

specifications on a single device.

Organizing operations within a service

Once an approximate set of functionality is mapped to a service type, operations inside that service may

be defined for specific protocol behaviors. These operations are at the core of the protocol and typically

result in far more discussion, iteration, and scrutiny than any other part of the specification. The abstract

behaviors that underpin these operations are completely dependent on the application domain, and by

definition cannot be described generically; although, generic interface design guidance is applicable to

Web Services protocols.

This remainder of this section provides an overview of the various styles of operations inside those

services, the parameters those operations may contain, and considerations for producing a robust set of

operation definitions.

Types of operations

DPWS provides facilities for three basic classes of operations:

One-way operations, which consist of a message from the client to the server, and no response.

Two-way operations, which consist of a message from the client to the server and a matching

response from the server to the client.

Event operations, which consist of a message from the server to the client, and no response.

Detailed descriptions for these are included below. A fourth operation class, two-way event operations

(also called Solicit-Response operations), exists but is not widely supported. It is not covered in this

document.One-way operations are lightweight but do not result in a reliable receipt of the message; if a device

consumes a one-way message but fails to process it for any reason, the device is not obligated to

indicate that failure to the client. The client therefore cannot assume that one-way messages are

successfully processed. This one-way pattern is often used for non-critical update messages where

timeliness and light weight is more important than reliable transmission. An example is a client that

periodically sends a temperature reading to an HVAC device; if the temperature is sent every few

minutes, it may not be critical to indicate receipt of every message.

Two-way operations are heavier than one-way operations but provide a channel for response data, and

can also carry enough data to indicate that request was successfully (or unsuccessfully) processed.

Service definitions are often comprised primarily of two-way operations as the response message is used

to carry parameters, an extensibility point, or solely to indicate that the operation completed successfully.

Event operations are unique in allowing a service to send an unsolicited message to a client. These

operations are, just like the one-way and two-way operations, defined by the specification building on

DPWS, although WS-Eventing provides a mechanism for the client and service to negotiate and maintain

a subscription relationship to allow event messages to be sent. Event operations are one-way and do not

provide a way for the client to send parameters back to the service.




Selecting the right operation

Figure 2 illustrates the flow for selecting the operation type for a particular protocol behavior.

The majority of messages in a typical specification built on DPWS are two-way messages, as the

response message provides a receipt that the request was received, and also provides a channel for

returned parameters. A protocol author building on DPWS should consider two-way operations to be the

default choice for message exchanges initiated by a client.

In cases where the response message is genuinely unnecessary, a one-way operation is more efficient.

Lastly, message exchanges initiated by the device should be defined as events.

Recommendations on organizing operations within a service

1. Use the flow chart in Figure 2 to determine whether to make each operation one-way, two-way, or

an event.

2. When deciding whether to make an operation one-way or two-way, weigh the performanceadvantages of the one-way message against the guaranteed receipt of the two-way message.

Who

initiates

this

messageIs a

response

message

necessary?

Event

Client

Device

One-way

Two-way

No

Yes

Figure 2: Flow chart for selecting operation type




Adding parameters to operations

Once the individual operations have been defined, the next step is to define the structure for parameters

to be transmitted inside the operation’s messages. These parameters are the sole contents of the SOAP

Bodies for these messages, and may be as simple or complex as necessary.

The task of populating messages with parameters is specific to the application domain of the protocolbuilt on DPWS. This section does not provide guidance on choosing an appropriate structure; it is

expected that the protocol author will have an approximate idea of how parameters fit together and are

attached to each device behavior or message. Instead, this section touches on the tools available to

define and represent those parameters inside messages.

XML Schema constructs available for defining parameters

In theory, the XML inside each message body may be exotic and nuanced as long as it can be crisply

described within XML Schema and normative specification text. In reality, some of the more unusual

XML constructions are not uniformly implemented and may not be very interoperable. This section (and

Section 3) highlights some of the more common patterns, but it does not provide a list of “safe” or

“unsafe” elements, as the line between these is blurry and can move over time. In general, concretedefinitions (e.g., complexType+sequence ) are better supported than abstract and inherited definitions

(e.g., complexType+model ), and underived base datatypes (string ) are better supported than heavily

derived datatypes (ENTITY ).

Many of the most common XML Schema (XSD) items can be divided into two categories:

Structural definitions, which allow parameters to be grouped into trees, lists, sequences,

attributes, and so forth. These are defined in XML Schema Part 1.

Datatypes, which define the type of data contained inside a specific text field. Examples include

integer, string, and date/time. These are defined in XML Schema Part 2.

Protocol authors can use these two categories of XSD items to create parameter structures inside

messages. Structural definitions can be used to create schema analogues to C/C++ structures, anddatatypes can be used to create fields for strings, integers, identifiers, etc.

The use of XSD to define message content is best shown by example. See the companion DPWS

Toaster Example Version 1.0 specification for XSD and WSDL.

Binary attachments

One special class of parameter is the binary attachment. DPWS describes the use of the Message

Transmission Optimization Mechanism (MTOM) to attach binary streams to SOAP messages. These

streams can be used to move raw data, such as images, packed binary commands, or streaming

audio/video content.

Binary streams are represented by the base64Binary XSD type. All base64Binary fields are attachments,and adding them to the message will result in binary data being appended to the SOAP envelope. Even

though the binary data is not included directly in the SOAP, the base64Binary field should be included in

a natural position inside the message as though the data were embedded directly.

Messages may contain multiple base64Binary fields although they are moved serially and the first

attachment must be closed before subsequent attachments can begin. Typically (although not always)




DPWS stacks allow applications to perform streamed reads and writes to attachment streams, as the

stream content may sometimes be too large to fit into memory.

Extensibility points

An important characteristic of nearly every Web Services specification is the presence of extensibility

points. These points allow implementers and future users of the protocols to add their own informationinto existing messages. Although specific extensibility points have varying levels of utility, extensibility

points in general are critical to the long-term usability of a protocol.

Extending a WSDL by adding new messages, operations, and portTypes is accomplished with a well-

defined namespace revision policy. This allows future revisions of the specification to retroactively add

new messages wholesale, and is described in greater detail in Section 3.

Extending existing messages by inserting new elements and attributes into existing structures is

accomplished by manually inserting extensibility points into the message definitions when first defined.

Specifically, the <xs:any> extensibility point allows insertion of new element data, and <xs:anyAttribute>

allows insertion of new attributes.

Most complex structure definitions (e.g., complexType+sequence ) will contain an extensibility point at theend. A good general policy is to include <xs:any> at the end of every complex type definition, although it

is not strictly necessary and may be omitted when no implementers could conceivably have any data they

ever want to add to contribute to the purpose of the particular structure. Care should be taken to ensure

at least one <xs:any> extensibility point is available inside the SOAP Body of every message (even those

which do not carry parameters).

In contrast, many structures and elements do not contain <xs:anyAttribute>. Attribute extensibility points

are most often added when the interpretation of the content inside the element in question could be

overridden by a new specification.

In the case of <xs:any> and <xs:anyAttribute>, adding extensibility points generally does not incur any

cost above the space taken in the XSD and the number of fields and parameters in generated code.

When in doubt, add <xs:any> to all structures.

A quick note on WSDL style

Readers familiar with WSDL may note that there are several styles of encoding parameters inside

messages. This guide describes the use of a common and interoperable style (wrapped document-literal)

and does not address the others. All readers should consider the style to be immaterial to this

discussion, as this section addresses parameterization nested inside the elements affected by differences

in style. The concrete steps in Section 3 will result in WSDL written in wrapped document-literal style.

Recommendations on adding parameters to operations

1. Choose concrete structural definitions (e.g., complexType+sequence ) and underived base types(e.g., string, anyURI, etc.) for best interoperability.

2. Build ComplexType definitions for structures and reuse these across messages where

appropriate.

3. Consider using xs:anyURI for any identifier fields (job IDs, etc.) instead of xs:string.

4. Use xs:base64Binary to add binary attachment data to a message.




5. Add <xs:any> to all XSD structure definitions, except where clearly unnecessary.

Event delivery and filtering

DPWS applications often include support for events, unsolicited messages sent from the device back to

the client. The structure of event messages is defined in the same way as forward control messages;

WSDL and XSD are used to describe the message and its contents.

In addition to the directionality of the message exchange, events differ from forward control messages in

four important ways:

Clients use the WS-Eventing protocol to manage the lifetime and filtering criteria of the

subscription for event messages.

Events are almost universally one-way messages, as two-way events (also called solicit-

response events) are not generally interoperable.

The number of messages often differs from client-initiated forward control messages. For

instance, a client will usually only send a single message to a single device; in contrast, a device

sending events may send the same message to many different subscribed clients. Thissometimes results in a different programming model for events than for other messages.

Clients are often inaccessible due to network topology, firewall settings, or because the client

dropped offline. This is a problem in all DPWS scenarios, but is particularly troublesome in

eventing because inaccessible clients can cause a delay in event delivery to other clients.

For these reasons, protocol authors should take care when designing events, and should be particularly

cautious that the events do not result in overly burdensome wire traffic or programming models. The

following subsections describe ways to accommodate these differences. Prior sections on designing

WSDL and XSD for control messages are otherwise applicable.

Reliability and latency in events

Because events are generally one-way messages, they do not offer the transmission receipt guaranteed

by two-way messages. A service cannot be sure that any clients successfully processed the events that

it sent. Accordingly, events should not be used to carry critical data; in cases where an event is used to

present results from a long-running operation, the event can be used merely to inform a client that results

are available. The client can then retrieve the results with a traditional two-way operation, guaranteeing

the data is not lost in a dropped event.

When using events, there is also a risk of clients being inaccessible because of network topology, firewall

settings, or because the client simply dropped offline. If the device is obligated to send events to many

different clients, a few inaccessible clients can result in significant delays delivering the event to other

clients. This problem can be somewhat ameliorated with intelligent filtering, but in general, timely delivery

is often very difficult to guarantee in eventing scenarios.

Event filtering

WS-Eventing provides a mechanism for clients to express filtering criteria for events they would like to

receive. The service (to which the client is subscribed) may then send messages that meet the filtering

criteria specified in the subscription. WS-Eventing does not specify any filtering criteria; it only provides a

location for that criteria to be defined and used.




Note that even though many clients may be subscribed for a certain message, the service is not obligated

to send a message to every subscribed client. The filter is merely a way for the client to specify that it is

interested only in certain messages.

DPWS defines a filter that may be reused by applications building on DPWS; this filter allows clients to

specify acceptable WS-Addressing Action values. Action is a common filtering criterion, as it relates

directly to the type of message which will be received. It does not provide more sophisticated (andheavier) filtering semantics, such as the ability to perform an XPath query on the entire message body.

In many cases, the DPWS Action filter is sufficient for clients to meaningfully limit the types of events the

service will send. In other cases (particularly those with a substantial number of subscribed clients and

event traffic), the message content varies enough that additional or different filtering is necessary. There

are a number of options in these cases:

Retain the Action filter, and divide events into more granular events. For instance, the attached

toaster example includes general events suitable for administrators and users, and specific job

events suitable primarily for users. This allows administrators to avoid receiving chatty job-

specific traffic.

Retain the Action filter, but allow the service to filter on additional information. Because the

service is not obligated to send events to every client, it may limit event messages to certain

classes of clients, or to a specific client. For instance, a specific message exchange (or

“session”) may be related by a single identifier; the client may supply this identifier in its

Subscribe message and in messages which may later trigger events; the service may then send

events for a specific operation only back to the client that supplied the identifier.

Define a new filter specific to the application. Although this can be effective in solving complex

filtering problems, it may also be a burden to implementers whose DPWS toolkits do not support

pluggable WS-Eventing filters. It is also preferable to keep the filtering criteria as simple as

possible.

Recommendations on defining events

1. Do not define messages for managing event subscriptions (e.g., Subscribe, Unsubscribe). WS-

Eventing provides these for you.

2. Do not rely solely on events to carry critical data. Instead, provide access to that data through

traditional two-way messages, and use events as one of the ways to inform clients that data is

available.

3. Use the sections on one-way and two-way forward control messages as a guide to define the

structure of each event message.

Bindings

Any protocol built on DPWS is required to support a basic protocol binding of SOAP 1.2 over HTTP. This

binding is very common and is sufficient for most protocols. Protocol authors are encouraged to rely

solely on SOAP 1.2 over HTTP.

In certain (advanced) cases, additional protocol bindings are necessary: such as SOAP 1.1 over HTTP,

or over another base protocol entirely. Both DPWS and WS-Discovery advertise service capabilities in




terms of abstract portTypes, making it cumbersome to determine which bindings are supported by a

service advertising a specific set of abstract operations.

There are two problems protocol authors should consider in extending beyond SOAP 1.2 over HTTP:

1. Clients must know which binding(s) they can use when contacting a service. This may be defined

in the specification (e.g., “a SERVICE MUST support both the SOAP 1.1 and SOAP 1.2 binding”)

or it may be discovered at runtime via WSDL or other mechanisms (e.g., an extensible element in

the device’s metadata). Either way, this behavior must be defined.

2. Because DPWS requires the default binding on every service endpoint, every service that

supports a new binding must also concurrently support the default DPWS binding. Depending on

the specifics of the new binding, it can be difficult to find widespread Web Services stack

implementations that can handle the new and the default DPWS binding.

Recommendations on defining bindings

1. Rely on the default DPWS SOAP 1.2 over HTTP binding if possible.

Service and device types

DPWS requires every service to have a type; this type is used by clients to determine which services they

are able to use. Additionally, the DPWS Host service advertises a set of types so the device can be

discovered using WS-Discovery queries with specific type criteria. In general, service types cannot be

reused at the DPWS Host service because the Host service does not directly accept the application-

specific control messages described by the service type.

Instead, the DPWS Host service advertises a dummy type (not directly associated with any callable

operations) which shows that the device contains related services. For example, a device that advertises

the ToasterDevice type will host at least ToastingService services, and possibly also SafetyService

services. The requirements between the device-level type and the service-level types can be as complex

as necessary; in this case, every toaster is required to have at least one ToastingService but is notrequired to have any SafetyService services. A device that contains a single SafetyService but no

ToastingService is not considered a toaster, and so it cannot advertise the ToasterDevice type.

Often, only a single device-layer type is required even if many different service types are defined. In

cases where there is very little cohesion between function of various services, consider splitting them into

separate protocols before defining distinct device-layer types for each.

In general, applications built on DPWS are designed to be composable so that multiple solutions can be

built into a single piece of hardware. It would be technically possible to build a combination toaster and

printer which advertised both ToasterService services and PrinterService services. Correspondingly, this

device would have to advertise the correct device-layer types, such as ToasterDevice and PrinterDevice.

For this to be possible, the ToasterDevice type cannot preclude the presence of unrelated services on the

device.

In cases where a single device type is chosen, DPWS Appendix C can be used to programmatically

couple all service types to the single device type. If a more complex device topology is necessary, the

relationship between types can be described in written normative text or in more sophisticated type

description languages.




Recommendations on service and device types

1. Define a device-layer type for related groups of service functionality.

2. Use DPWS Appendix C to bind service-layer types with a device type.

3. When necessary, express more complex type relationships with normative text or a type

description language.

Faults

In addition to defining the structure of messages and successful responses, protocol authors should

devote attention to error conditions and, in particular, SOAP Faults.

SOAP Faults are mechanisms that services can use to communicate specific failure data. Many generic

faults are defined by underlying specifications (e.g., WS-Addressing, WS-Eventing, etc.), and these may

be reused by stack implementers to communicate general failures, such as an improperly addressed

message.

In certain cases, a client can take meaningful action when certain errors occur. For instance, if a Toaster

client were unable to begin toasting because the service is already toasting, it could conceivably wait forthe current toast to complete before scheduling a new one. Enabling this fallback logic would require the

toaster service to communicate specific information in the error—the fact that it is already toasting—

because a generic error message would not convey enough information for the client to know to wait and

retry later.

In other cases, the failure may not be particularly meaningful but the error may be useful for the client

software to present to a user or log to a file. In these cases, a generic fault is sufficient as long as it

carries descriptive detail inside the fault.

The concrete steps in Section 3 describe how to add a fault to a protocol definition.

Recommendations on faults1. Define faults to express error conditions where a client could take meaningful action.

2. Do not redefine faults in underlying specifications, such as “Endpoint Unavailable.”

3. Do not define faults simply to carry descriptive text; use existing faults and encourage

implementers to add their own (possibly pre-defined) descriptive text.

Abstract service design guidelines

The preceding subsections provide tools available to specifications authors to create an abstract protocol

definition. These tools provide little guidance on how to arrange various protocol components, as this is

heavily dependent on the application domain.Instead, protocol authors are encouraged to seek out generic design guidance for Web Services (or other

remote method invocation interfaces), and any advice for designing protocols for resource-constrained

devices. A short list of common design notes is provided below, as well.




Recommendations on abstract service design

1. Services should expose core behavioral concepts without tying too heavily into specific

implementations.

2. Long-running operations should be asynchronous (e.g., have separate start and end wire

operations) and should allow clients to either interrogate the service’s process, or subscribe to

status update events.

3. Clients may have varied reasons for using a device—some may actively use it, and others may

simply monitor its progress. Expect clients will be interested in different subsets of device

functionality.

4. Clients and services should not rely heavily on state information, and should expect that

operations may be invoked out of order except in cases where order is absolutely necessary.

5. Services definitions should expect multiple clients to invoke operations simultaneously.

6. Even if designed as an advanced protocol only intended for state-of-the-art hardware, it is not

uncommon for complex protocols to eventually be implemented on very resource-constrained

devices. Protocol authors should take care to accommodate these devices.

7. Resist the urge to simply transcribe service definitions from other protocol frameworks (e.g.,

UPnP). Most protocol suites have different design idioms which do not always translate well to

DPWS.




Section 2: Creating a specification from an abstract protocol

Anatomy of a specification built on DPWS

Many specifications built on DPWS (and otherwise) are composed of three parts:

Normative text, a human-readable description of the specification’s rules and behaviors

WSDL/XSD, a machine-readable description of the specification’s messages and types

Non-normative ancillary materials, which provide additional explanations necessary to

understand and use the specification

While it is not strictly necessary to organize material into these three parts, this arrangement is a

commonplace and tested way to separate specification components into cohesive and focused parts.

Normative text

The normative text is the core of a specification, and is typically the most heavily scrutinized componentof the three. Implementers will refer heavily to the text to determine the intent and behavior of each part

of the protocol it defines, and will turn to it when a dispute arises about what is required, recommended,

allowed, or prohibited.

Application-specific specifications (such as the DPWS Toaster example) build heavily on the rules and

behaviors defined in the referenced specifications, such as DPWS; accordingly, the specification does not

need to redefine these rules and concepts, and can instead be focused almost entirely on the domain-

specific operations and behaviors a device will implement.

WSDL/XSD

The Web Services Description Language (WSDL) and XML Schema (XSD) are languages for expressingassociations between names and various messaging primitives like operations and types. WSDL and

XSD files are often included in a specification so the protocol rules (including a subset of the rules defined

in the normative text) are accessible in a machine-readable format. Figure 3 shows the relationship

between a normative text and WSDL in a typical specification.

Figure 3: Relationship between WSDL and normative text

Normative text

WSDL/XSD




WSDL is unable to express even very rudimentary behavioral or sequencing rules, and so it is typically

insufficient to describe an entire protocol.

In most cases, the normative specification text does not fully describe the relationship between the

abstract messaging concepts and the components in the wire message (e.g., the text is unlikely to

explicitly describe the structure of every message) and so the WSDL does cover some parts of the

protocol that the normative text does not address. WSDL can also express runtime-only information(such as extra WS-Policy assertions) and so can be useful outside the context of the normative text.

WSDL is very useful in development tools, and often aids in rapid production of implementations. WSDL

also improves basic interoperability by providing a known machine-readable description of message

formats.

Ancillary materials

The normative specification text and WSDL specify the rules and behavior of devices built to your

specification, and are the authority when resolving inevitable disputes over what is permitted and what is

not. These documents (and specifically, the normative text) should be focused on crisply defining the

behavior, and should not dilute the rules with too much additional material.

Readers nevertheless often need a richer explanation to fully understand the protocol and its meaning.

Ancillary materials (such as white papers, case studies, and examples) are the appropriate location for

explaining domain-specific concepts. Keeping these topics outside the normative text makes it easy to

separate the intended uses from the actual protocol behavior; as the protocol matures its use may extend

beyond the initial examples, but the normative text will always be directly applicable.

Recommendations on specification structure

1. Consider the normative text, WSDL, and ancillary materials to be equally important components

of the entire specification. Providing all three helps keep each focused.

Referencing DPWS

Each component of a specification (normative text, WSDL/XSD, and non-normative material) refers to

lower protocol layers in a different way. This section describes the correct way to bind DPWS into each

section.

Normative references to DPWS

At a minimum, two references are necessary to require DPWS in an implementation:

1. The DPWS document must be referenced. Typically this is dictated by the citation style of the

organization producing the specification.

2. The specification must specifically call out the required roles to be implemented. Often, it is

sufficient to call out that a device must implement the DEVICE role as defined by DPWS.

Additionally, a specification may call out optional components of DPWS. For example, the attached

DPWS Toaster example makes use of events, and so requires the device to implement WS-Eventing, as

profiled in DPWS. While it may be possible to argue that such support is necessary even without a direct

reference, a clear statement that requires support unambiguously informs the implementer that they must

build this component to be compliant.




WSDL/XSD references to DPWS

The binding between the machine-readable components of a specification (WSDL and XSD) and DPWS

is typically limited to a WS-Policy assertion in the binding section of the WSDL.

Although it is possible to include a reference to the DPWS XSD, this is usually unnecessary; the only

exception is if the specification makes direct use of the types defined in DPWS, and this is very unusual.

Including a reference to the DPWS XSD should otherwise be avoided, as this increases the risk that a

development tool will misinterpret the DPWS structures as being native to the device specification.

The proper way to bind DPWS is to include the WS-Policy assertion (defined in DPWS 1.1 Section 4.4) in

the binding section of the device’s WSDL. Some development tools will skip this assertion (or will not

require this assertion in the first place) but its presence typically does not introduce any problems.

Non-normative descriptions of DPWS and lower-layer protocols

All materials—including ancillary materials—should describe details of lower protocol layers (such as

DPWS) with caution. Although it may initially seem helpful to describe these protocols, there is significant

opportunity to include mistakes or mislead readers. Consider this example of a seemingly innocuous

description:

INCORRECT

The Devices Profile for Web Services (DPWS) defines discovery and metadata behavior common to all devices. It uses

multicast UDP discovery messages (Hello and Probe) to locate devices on the same subnet. It allows a device to express

metadata such as its manufacturer, model name, and connection URL. DPWS also provides events and the ability to move

binary files as attachments.

Even though there is only one factual error in this description (DPWS does not define discovery

messages, WS-Discovery does), it contains many misleading statements:

UDP multicast is not the only way to discover a DPWS device.

Hello and Probe are not the only important WS-Discovery messages.

DPWS metadata defines three URLs (for manufacturer, model, and device presentation page)

and describes endpoint addresses for Hosted Services, but “connection URL” leads the reader to

consider a single connection point for the entire device, which is an oversimplification.

Attachments are binary streams, and may contain data other than file contents.

Instead, consider omitting these details entirely or—if some description is necessary—describe the

abstract properties of these specifications. It is far easier to create an accurate abstract description.

CORRECT




The Devices Profile for Web Services (DPWS) provides common discovery and metadata mechanisms for all device classes,

and assembles additional Web Services technologies so they can be consistently and easily implemented on devices. DPWS

devices can announce themselves or clients can search for them. Clients may retrieve metadata that describes the

characteristics of the device. DPWS also constrains additional technology (such as WS-Eventing and MTOM) that can be

used in control operations specific to a particular device class.

Also consider referring directly to the descriptive materials produced by the WS-DD TC.

Recommendations on referencing DPWS

1. Include citations to DPWS normative material according to the format defined by

2. Refer directly to WS-DD TC white papers and other materials, and only provide abstract

descriptions of lower-layer specifications if additional detail is necessary. Avoid descriptions of

technical or detailed concepts in DPWS or the specifications it references.

Choosing a namespace

Web Services specifications make heavy use of namespaces in XML. Protocols built on DPWS must

declare all wire components (messages, structures, etc.) inside a namespace.

Namespace URI contents

Namespaces in XML are identified by URI, often in the http scheme. These URIs usually reflect the

organization producing the specification—for instance, the OASIS Standard DPWS uses a URI that, when

evaluated as a URL, points to an OASIS web server. Protocol authors building specifications on DPWS

should choose a namespace URI that reflects their organization (a standards body, corporation, or even

an individual).

The value of the URI is not meaningful from a protocol perspective (it merely distinguishes names in

various protocols from each other) and technically, there is no requirement that the URI be a resolvableURL. However, many protocol authors do place an RDDL page at the namespace URL as a

convenience.

Namespace revision policy

In addition to the URI value itself, protocol authors should consider what type of long-term policy will be

associated with this URI. Generally, protocol implementers expect that once a namespace is defined, the

existing contents of that namespace will not be deleted or changed. The addition of new content

(messages, operations, etc.) is more flexible and some specifications clearly call out that future revisions

may reuse an old namespace and add new protocol elements as long as existing ones are not affected.

Defining a namespace policy helps implementers be aware what changes could occur in the future. Italso provides a valuable avenue to add important features to an existing protocol without changing the

content entirely.

Temporary namespace URIs

Often, a protocol is mocked up, prototyped, and discussed before a final namespace can be assigned. In

these cases, it is generally acceptable to use a temporary URI (such as an HTTP-scheme URI with an




authority part of example.org ) but great care should be taken to remove and replace these URIs before

the protocol is implemented in products.

Recommendations

1. Choose a namespace URI that reflects the organization producing the specification.

2. Do not define new protocols in the DPWS namespace.

3. Define a namespace revision policy that defines how content may (or may not) be added to the

namespace over time.

4. Remove temporary and placeholder namespace URIs as soon as a proper namespace is

available.




Section 3: Creating a WSDL/XSD

This section provides a step-by-step process for constructing WSDL and XSD from an abstract protocol

description. Section 1 in this document helps guide the process of forming a protocol description and

Section 2 describes how that can be codified into normative text and WSDL/XSD; those sections providethe groundwork for the instructions below.

WSDL style

This guide provides steps to author a hand-written WSDL. Although tools exist to produce WSDL from a

programming contract defined in another language, these tools sometimes produce idiomatic

constructions which try to fit the WSDL around the programming platform which produced the code. This

generally results in complex (and sometimes confusing) definitions which are difficult to interpret with

tools on other platforms, or by hand. Because device WSDLs are often consumed on many different

platforms and are sometimes scrutinized manually, it is important that the resulting definition is

unambiguous. Hand-authored WSDL is the best way to achieve this result.

There are also different styles of arranging various elements inside the WSDL. This guide will result inWSDLs in the document-literal style, as this is reasonably interoperable in the device world.

Step 1: Organize abstract protocol definition

Section 1 in this document provides a description of how to assemble a service, how to choose

operations for that service, and how to populate those operations with parameters. That abstract

description should include an approximate mapping of how those services, operations, and parameters all

map to real-world behavior. For example, an abstract description of the StartToasting operation in the

Toaster example would include parameters that may define the duration and type of toasting to occur,

and would also note that a successful response would represent the physical toaster element

successfully starting.Collecting and organizing this abstract description is required to complete step 1. Protocol authors may

find it convenient to transcribe this description into an approximate and annotated interface definition

(e.g., a C++ class) even though this definition will not be read by any tools.

Action : organize protocol elements into services, operations, and parameters.

Step 2: Copy the WSDL template

The next step is to copy this WSDL template into a local file. Some development editors natively support

WSDL files, and many text editors support XML. Advanced functionality in these editors may assist in

making changes to the WSDL but only raw text input is necessary to follow this guide.

When saving this file, it is helpful to choose a name related to the service name. Toaster.wsdl or

ToasterService.wsdl are appropriate names for a Toaster WSDL.

<?xml version="1.0" encoding="utf-8"?>

<definitions

xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"

xmlns:dpws="http://docs.oasis-open.org/ws-dd/ns/dpws/2009/01"

xmlns:tns="Step 8"

targetNamespace="Step 8">

<types>

<xs:schema

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:tns="Step 8"

targetNamespace="Step 8">





</xs:schema>

</types>







</definitions>

Further steps in this guide will replace each named “Step” item with XML or namespaces.

Action : Copy and save this WSDL template into a local file.

Step 2: Convert services to WSDL portTypes

The portType section of a WSDL describes the operations that will comprose a single service. A WSDL

file can contain multiple portType sections, although often it will contain only a single functional service

type, and a dummy definition for WS-Discovery types (Step 3 covers the additional portType).

Replace the  heading in the WSDL template with <portType> declarations like the one shown

below, and replace the name with one that relates to the service’s purpose.

<portType name="ToasterService">



</portType>

Action : Replace the  comment in the WSDL. Add a portType section for each service.

Step 3: Add portTypes for WS-Discovery types

Section 1 describes the difference between service-layer types and discovery-layer types; defining at

least one WS-Discovery type is recommended.

For each WS-Discovery type, an empty portType is necessary to ensure the name is declared in the

namespace. Replace the  comment in the WSDL with a portType declaration like the oneshown below.

<portType name="ToasterDevice" />

Optionally, associate each portType with each discovery type using DPWS Appendix C. Add the

dpws:DiscoveryType attribute to the <portType> elements added above, in step 2. Note that the “tns:”

prefix on the ToasterDevice name should be kept as-is; simply replace “ToasterDevice” with the matching

discovery type name.

dpws:DiscoveryType="tns:ToasterDevice"<portType name="ToasterService" >

</portType>

Action : Replace the  comment in the WSDL. Add an empty portType for each WS-

Discovery type. Optionally, add DiscoveryType attributes to bind service portTypes to discovery

portTypes.

Step 4: Convert method calls to WSDL operations

Once the portTypes are mapped, convert each abstract method call into one-way, two-way, or event

operations inside the portType. Operations are composed of input and output messages: one-wayoperations have only an input message; event operations have only an output message; and two-way

messages have both.

Use the template below to add operations to the portType.

…

<operation name="StartToasting">

<input message="tns:StartToastingRequest" />

<output message="tns:StartToastingResponse" />

</operation>

<operation name="AbortToasting">

<input message="tns:AbortToastingRequest" />

</operation>

<operation name="ToastingCompletedEvent">

<output message="tns:ToastingCompletedEvent" />

</operation>

...

Action : Replace the  comment in the WSDL. For each abstract operation in the service,

create an <operation> element inside the <portType> and add <input> and <output> message

references.

Step 5: Add WSDL messages

WSDL contains a <message> definition which is necessary to build a service description, but which does

not have a clear analogue in many other interface definition languages. In this guide, <message>

definitions are added simply to associate parameter structures to operations.

For each input or output message reference added in step 4, add a corresponding <message> definition

following the template below.

...

<message name="StartToastingRequest">

<part name="Body" element="tns:StartToastingRequest" />

</message>

<message name="StartToastingResponse"><part name="Body" element="tns:StartToastingResponse" />

</message>

<message name="AbortToasting">

<part name="Body" element="tns:AbortToasting" />

</message>

<message name="ToastingCompletedEvent">

<part name="Body" element="tns:ToastingCompletedEvent" />

</message>

...

Action : Replace the  comment in the WSDL. For each message reference in each

portType, add a <message> element.

Step 6: Convert types into XSD types

Once each WSDL message has been defined, steps 6 and 7 will populate them with parameters.

Specifically, step 6 defines structures used to contain multiple parameters.

Begin by inspecting the abstract protocol definition and identifying parameters in each operation. These

parameters can be arranged in lists and trees, similar to C/C++ structures.

Each structure is defined on its own; although XSD allows structures to be defined as nested types, it is

cleaner to define each separately and reference them by name. Each structure can contain fields with

simple types (integer, string, etc.), lists of simple fields, references to other structures, and extensibility

points.

In general, the vast majority of type definitions are complexType+sequence. The sequence compositor is

conceptually similar to a C/C++ struct. Other constructs are available in XML Schema but are left to the

reader to explore.

Individual fields are defined by <element> definitions inside the sequence, and are often modified with

minOccurs and maxOccurs values to define items as optional, or as a list (similar to an array). minOccurs

and maxOccurs both default to 1 if not declared.

References to other structures are by <element> definitions referencing other types. Structures may be

reused in many locations—if a single structure is used in many messages, it may be defined once and

referenced from all other structures where it is used.

Remember to add extensibility points as appropriate in complexType definitions. In cases where a

message contains only a single element (e.g., a SetTemperature operation with a single integer value),

consider defining a complexType that contains the integer and an extensibility point. If a message has no

parameters (e.g., GetTemperature), define a complexType that contains only an extensibility point.

Follow the example below to define <complexType> elements for every parameter structure in the

abstract protocol definition.

Note that all definitions in this section must use the xs namespace prefix.

...

<xs:complexType name="StartToastingRequestType">

<xs:sequence>

<xs:element name="HeatLevel" type="xs:integer" />

<xs:element name="Duration" type="xs:duration" minOccurs="0" />

<xs:element name="ImageToBurn" type="xs:base64Binary" minOccurs="0" />

<xs:any namespace="##other" processContent="lax" />

</xs:sequence>

</xs:complexType>

...

Action : Replace the  in the WSDL. For each structure type in the abstract protocol, create

a <complexType> definition and fill it with fields, references to other structures, and extensibility points.

Step 7: Define XSD elements

Once the parameter structures have been defined, they must be wrapped in elements before being

referenced in messages.

For every <message> definition created in step 5, create a matching <element> definition that associates

the element name in the <message> with a <complexType> or simple type definition. These <element>

messages are necessary to wrap the message contents in an XML element inside the SOAP Body.

Note that all definitions in this section must use the xs namespace prefix.

...

<xs:element name="StartToastingRequest" type="tns:StartToastingRequestType" />

<xs:element name="StartToastingResponse" type="tns:StartToastingResponseType" />

<xs:element name="AbortToasting" type="tns:AnyElementType" />

<xs:element name="ToastingCompletedEvent" type="tns:AnyElementType" />

...

Action : Replace the  in the WSDL. For each <message> element, add an <element>

definition.

Step 8: Include the namespace

The final step is to add a namespace. The namespace is listed in two locations in the WSDL part, and in

two locations in the XSD part: once to declare the target namespace where every item will be defined,

and once to bind the “tns” (target namespace) prefix to that namespace so that parts of the WSDL can

internally reference other parts. Be sure to replace all four instances.

Directions on selecting a namespace can be found in Section 2 of this guide.

Action : Replace every occurrence of Step 8 in the WSDL with the namespace URI.

Design Guide for Specifications Built on the Devices Profile for Web Services

Documents

Transcript of Design Guide for Specifications Built on the Devices Profile for Web Services