Introduction

Requirements

Stream

Stream Formats

Subscription Manager

Example

Notations and Terminology

Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define normative outlines for messages:

  • The syntax appears as an XML instance, but values in italics indicate data types instead of values.
  • Characters are appended to elements and attributes to indicate cardinality:
    • "?" (0 or 1)
    • "*" (0 or more)
    • "+" (1 or more)
  • The character "|" is used to indicate a choice between alternatives.
  • The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.
  • The characters "[" and "]" are used to call out references and property names.
  • Ellipsis (i.e. "...") indicate a point of extensibility.
  • XML namespace prefixes (see Table 3-1) are used to indicate the namespace of the element being defined.

In addition to Message Information Header properties [WS-Addressing], this specification uses the following properties to define messages:

[Headers]
Unordered message headers.

[Action]
The value to be used for the wsa:Action IRI.

[Body]
A message body.

These properties bind to a SOAP Envelope as follows:

<s:Envelope>
  <s:Header>
    [Headers]
    <wsa:Action>[Action]</wsa:Action>
    ...
  </s:Header>
  <s:Body>[Body]</s:Body>
</s:Envelope>

This specification can be used in terms of XML Information Set (Infoset) [XML Infoset], even though the specification uses XML 1.0 terminology. Valid Infoset for this specification is the one serializable in XML 1.0, hence the use of XML 1.0.

The term "generate" is used in relation to the various faults defined by this specification to imply that a fault is produced and no further processing SHOULD be performed. In these cases the fault SHOULD be transmitted. However, there might be reasons when a compliant implementation can choose not to transmit the fault - for example, security concerns - in these situations the service MAY choose not to transmit the fault.

Terminology

Service Consumer
A network endpoint that transmits messages in order to use the capabilities offered by a Service Provider to fulfil a particular task / need.

Service Provider
A network endpoint that transmits messages in order to offer the use of its capabilities (functions and functionality) by means of a Web Service.

Web Service
A mechanism to enable access to one or more capabilities (function and functionalities) of a device or system, where the access is provided using a prescribed interface and is exercised consistent with constraints and policies as specified by the service description.

Stream
Messages sent over a network to transmit data.

Stream Source
A sending network endpoint that delivers at least one Stream.

Stream Source Provider
A Service Provider that describes the access to at least one Stream Source.

Stream Sink
A receiving network endpoint that consumes at least one Stream.

Subscription
A registration of interest in consuming a Stream from a Stream Source. Subscriptions MAY be created, renewed, expired or cancelled. A Subscription is "active" when it has been created but has not been expired or canceled.

Subscriber
A Service Consumer that creates, renews, and/or deletes Subscriptions.

Subscription Manager
A Web Service that manages, gets the status of, renews, and/or deletes Subscriptions on behalf of an Stream Source.

Schema Files

TODO

Compliance

TODO

XML Namespaces

TODO

Stream Source Policy Model

This specification defines policy assertions for the streaming capabilities for Web services. These assertions are primarily designed to represent the stream providing capabilities of a Service Provider.

The primary goal of this specification is to define a set of assertions that represent a common way to describe streams that are announced by a service provider. The intent is to allow flexibility in terms of stream management and negotiation protocols (RTSP, SOAP-over-UDP Streaming,...) or transport bindings of the stream (RTP, SOAP-over-UDP Multicast).

In general, assertions defined in this specification allow additional attributes, based on schemas, to be added on to the assertion element as an extensibility mechanism but the WS-Policy framework will not match based on these attributes. Attributes specified on the assertion element that are not defined in this specification or in WS-Policy are to be treated as informational properties.

Stream Assertion Model

The goal to provide richer semantics for combinations of streaming constraints and requirements and enable first-level QName matching, is enabled by the assertions defined in this specification being separated into four simple patterns.

How are Subscriptions dealt with?

Assertions identifying the mechanisms that allow Subscribers and Subscription Managers to handle Subscriptions, are referred to as Stream Subscription Assertions.

How is a Stream controlled?

Assertions that identify aspects of controlling the stream source by issuing VCR-like commands, such as play and pause, to facilitate real-time control of the stream transmission are referred to as Stream Controlling Assertions.

How is a Stream transmitted over network?

To indicate the mechanisms that are utilized to transmit a stream Stream Transmission Assertions are used.

What mechanism is used for a stream?

The Stream Type Assertion is a logical grouping which contains the information on how about a stream. For example, that SOAP-over-UDP is used for stream transmission, and that a Subscriber create a Subscription by listening on a provided multicast address and port. At its simplest form, the stream type is just a URI that implies all the associated processing rules.

Nested Policy Assertions

Assertions may be used to further qualify a specific aspect of another assertion. For example, an assertion describing a compression algorithm to use may qualify the specific behavior of a streaming binding. If the schema outline below for an assertion type requires a nested policy expression but the assertion does not further qualify one or more aspects of the behavior indicated by the assertion type (i.e., no assertions are needed in the nested policy expression), the assertion MUST include an empty <wsp:Policy/> element. For further information consult the section Policy Assertion Nesting of [WS-Policy].

Stream Binding Abstraction

TODO

Policy Considerations

The following sections discuss details of WS-Policy and WS-PolicyAttachment relevant to this specification.

Nested Policy

This specification makes extensive use of nested policy assertions as described in the Policy Assertion Nesting section of WS-Policy.

Policy Subjects

WS-PolicyAttachment defines various attachment points for policy. This section defines properties that are referenced later in this document describing the recommended or required attachment points for various assertions.

Note: This specification does not define any assertions that have a scope of [Message Policy Subject], [Operation Policy Subject], and [Service Policy Subject].

[Endpoint Policy Subject]

A token assertion instance with Endpoint Policy Subject indicates usage of the token for the entire set of messages described for the endpoint:

wsdl:portType

A policy expression containing one or more assertions with Endpoint Policy Subject MUST be attached to a wsdl:portType.

wsdl:binding

A policy expression containing one or more of the assertions with Endpoint Policy Subject MUST NOT be attached to a wsdl:binding.

wsdl:port

A policy expression containing one or more of the assertions with Endpoint Policy Subject MUST NOT be attached to a wsdl:port.

Stream Type Assertion

A Stream Source Provider MAY indicate its support of WS-Streaming, or its features, by including the WS-Streaming StreamSource within its WSDL. This policy assertion has [Endpoint Policy Subject]. By doing so the Stream Source Provider is indicating that information about at least one Stream according to policies defined in the WS-Streaming specification is provided and that operations defined in the WS-Streaming specification are supported by the Stream Source Provider. The operations are implicitly defined and MAY not explicitly appear in its WSDL (ie. the WS-Streaming operations do not appear in the WSDL that MAY be retrievable by using WS-MetadataExchange GetWSDL to that endpoint).

The WS-Streaming WSDL containing the operations indicated by the StreamSource MAY be exposed by including the WSDL as a child of the appropriate Policy assertion or by including a reference to it using the mex:Location or mex:Reference element ( as described in WS-MetadataExchange (TODO: ref WS-MetadataExchange) Section 9).

This WS-Streaming WSDL can be annotated to indicate any endpoint specific metadata that might be needed by clients interacting with the WS-Streaming operations. For example, the WSDL MAY have policy assertions that indicate a particular security mechanism used to protect the WS-Streaming operations supported by this endpoint.

StreamSource Assertion

Services indicate support for the WS-Streaming's definition of a stream source through the use of the Web Services Policy - Framework (TODO: ref WS-Policy) and Web Services Policy - Attachment (TODO: ref WS-Policy Attachment) specifications.

This specification defines a policy assertion (wsstm:StreamSource). The normative outline of this assertion is:

<wsstm:StreamSource ...>
  <wsstm:StreamDescriptions streamType="xs:anyURI" targetNamespace="xs:anyURI" name="xs:NCName" ...>
    xs:any*
  </wsstm:StreamDescriptions>+
  xs:any*
</wsstm:StreamSource>

The following describes additional, normative constraints on the outline listed above:

/wsstm:StreamSource
This policy assertion has Endpoint Policy Subject. When present in a policy alternative, it indicates that the subject is a stream source provider.

/wsstm:StreamSource/wsstm:StreamDescriptions
This element contains the declarations of all the Stream Types that apply to a given context. It wraps the description of the stream and may contain nested assertions on how to deal with Subscriptions, how the Stream is transmitted or how the Stream is controlled.

/wsstm:StreamSource/wsstm:StreamDescriptions@streamType
This MANDATORY attribute indicates that the StreamDescriptions follows the specifications of the provided type. This value should be compared directly, as a case-sensitive string, with no attempt to unescape or to otherwise canonicalize it.

/wsstm:StreamSource/wsstm:StreamDescriptions@name
This attribute provides a name for this Stream Description which MUST be unique amongst all the Stream Descriptions defined by the enclosing wsstm:StreamSource element. In conjunction with a Prefix that is associated with the value of @targetNamespace namespace URI, the value of this attribute MAY be used as the LocalPart of a QName that identifies this Stream Description outside the context of the enclosing wsstm:StreamSource element.

/wsstm:StreamSource/wsstm:StreamDescriptions@targetNamespace
This attribute defines the namespace affiliation of stream specific elements and attributes including those that might be nested in Stream Transmission, Stream Subscription, or Stream Controling Assertions declared within the StreamDescriptions element. Its value MUST be an absolute IRI [RFC 3987]. It SHOULD be dereferenceable.

Stream Transmission Assertions

<wsstm:StreamSource ...>
  <wsstm:StreamDescriptions streamType="xs:anyURI"  targetNamespace="xs:anyURI" name="xs:NCName" ...>
    <wsstm:StreamTransmission type="xs:anyURI"? ...>
      xs:any*
    </wsstm:StreamTransmission>?
    xs:any*
  </wsstm:StreamDescriptions>+
  xs:any*
</wsstm:StreamSource>

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission
This OPTIONAL assertion describes a specific mechanism for the transmission of the Stream. If omitted it is implied that necessary information for receiving a stream is handled by other means, e.g. during subscription process.

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission@type
This OPTIONAL attribute references the mechanism for stream transmission. If omitted the value /wsstm:StreamSource/wsstm:StreamDescriptions@streamType is implied.

The following is an example of a wsstm:StreamTransmission policy assertion:

(01) <wsstm:StreamSource>
(02)    <wsstm:StreamDescriptions
(03)        streamType="http://???/Mechanism/soap-over-udp"
(04)        targetNamespace="http://www.example.org/oceanwatch/stream"
(05)        name="RealTimeWindReportStream"
(06)        xmlns:ow="http://www.example.org/oceanwatch"
(07)        xmlns:sudps="http://???/Mechanism/soap-over-udp">
(08)        <sudps:types>...</sudps:types>
(09)        <wsstm:StreamTransmission type="http://???/Mechanism/soap-over-udp">
(10)             <sudps:stream element="ow:WindReport" actionURI="http://www.example.org/oceanwatch/2010/WindReportStream">
(11)                    <sudps:streamPeriod>PT0.02S</sudps:streamPeriod>
(12)                    <sudps:streamAddress>soap.udp://239.12.23.23:12345</sudps:streamAddress>
(13)             </sudps:stream>
(14)        </wsstm:StreamTransmission>
(15)    </wsstm:StreamDescriptions>
(16)  </wsstm:StreamSource>

Stream Subscription Assertions

Wrapper Assertion ONLY. TODO

<wsstm:StreamSource ...>
  <wsstm:StreamDescriptions streamType="xs:anyURI"  targetNamespace="xs:anyURI" name="xs:NCName" ...>
    <wsstm:StreamSubscription type="xs:anyURI"? ...>
      xs:any*
    </wsstm:StreamSubscription>?
    xs:any*
  </wsstm:StreamDescriptions>+
  xs:any*
</wsstm:StreamSource>

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamSubscription
The OPTIONAL policy assertion describes a specific mechanism on how to handle subscriptions to the described Stream. If omitted it is implied that the necessary information for receiving the stream is handled by other means, e.g. implicitly by providing a multicast address for stream transmission.

/wsstm:StreamSubscription@type:: This OPTIONAL attribute identifies the mechanism for stream subscription. If omitted the value /wsstm:StreamSource/wsstm:StreamDescriptions@streamType is implied.

Stream Controlling Assertions

Wrapper Assertion ONLY. TODO

<wsstm:StreamSource ...>
  <wsstm:StreamDescriptions streamType="xs:anyURI"  targetNamespace="xs:anyURI" name="xs:NCName" ...>
    <wsstm:StreamControl type="xs:anyURI"? ...>
      xs:any*
    </wsstm:StreamControl>?
    xs:any*
  </wsstm:StreamDescriptions>+
  xs:any*
</wsstm:StreamSource>

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamControl
The OPTIONAL policy assertion describes a specific mechanism on how issue control commands to the described Stream Source. If omitted it is implied that the necessary information for receiving allowed stream control command is handled by other means, e.g. during subscription process.

/wsstm:StreamControl@type:: This OPTIONAL attribute identifies the mechanism for stream control. If omitted the value /wsstm:StreamSource/wsstm:StreamDescriptions@streamType is implied.

The following is an example of wsstm:StreamControl and wsstm:StreamSubscription policy assertions to describe a stream that uses RTSP (RFC2326) for Subscription handling and stream control.

(01) <wsstm:StreamSource>
(02)    <wsstm:StreamDescriptions
(03)        streamType="http://tools.ietf.org/html/rfc2326"
(04)        targetNamespace="http://www.example.org/oceanwatch/stream"
(05)        name="RealTimeWindReportStream">
(06)        <wsstm:StreamSubscription type="http://tools.ietf.org/html/rfc2326"/>
(07)        <wsstm:StreamControl type="http://tools.ietf.org/html/rfc2326"/>
(08)    </wsstm:StreamDescriptions>
(09)  </wsstm:StreamSource>

Runtime Considerations

It is also useful to make the StreamDescriptions available via WS-MetadataExchange. Especially, to extract information that might not be included in a general StreamDescriptions within a StreamSource policy due to fact that the information is only available at runtime.

The value of the @Dialect attribute MUST be equal to wsstm:StreamDescriptions. The value of the @Identifier attribute, if present, for this MetadataSection MUST be equal to the value of its wsstm:StreamDescriptions/@targetNamespace. A stream source MAY have more than one StreamDescriptions document.

Example:

  <mex:MetadataSection Dialect="wsstm:StreamDescriptions"
                       Identifier="http://www.example.org/oceanwatch/stream">
    <wsstm:StreamDescriptions>
      <!-- Stream description data removed for brevity -->
    </wsstm:StreamDescriptions>
  </mex:MetadataSection>

Security Considerations

(TODO: define security considerations)

Implementation Considerations

References

Normative References

TODO

Informal References

WS-Eventing
 W3C Working Draft "Web Services Eventing (WS-Eventing)", Doug Davis, Ashok Malhotra, Katy Warr, Wu Chou, Editors, World Wide Web Consortium (W3C), 5 August 2010.

Appendices

Exemplary Stream Type Bindings

SOAP-over-UDP Stream Type Binding

Normative outline of the SOAP-over-UDP Stream Type Binding

<wsstm:StreamSource ...>
...
  <wsstm:StreamDescriptions streamType="http://???/Mechanism/soap-over-udp"  targetNamespace="xs:anyURI" name="xs:NCName" ...>
   <sudps:types>
      <xs:schema ...>
        ...
      </xs:schema>
      xs:any*
    </sudps:types>?
    <sudps:stream element="xs:QName" actionURI="xs:anyURI"? ...>
      <sudps:streamPeriod>duration-type </sudps:streamPeriod>?
      <sudps:streamAddress>endpoint-reference-type </sudps:streamAddress>?
      xs:any*
    </sudps:streamType>+
    xs:any*
  </wsstm:StreamDescriptions>+
...
<wsstm:StreamSource>
/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamSubscription

StreamSubscription assertion SHOULD not be used in a SOAP-over-UDP Stream Type Binding. A Subscriber SHOULD subscribe to the provided ../wsstm:StreamTransmission/sudps:stream/sudps:streamAddress in order to act as a Stream Sink.

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamControl

StreamControl assertion SHOULD not be used in a SOAP-over-UDP Stream Type Binding. No means for stream control are provided within this specification.

/wsstm:StreamSource/wsstm:StreamDescriptions/sudps:types
This OPTIONAL element encloses data type definitions that are relevant to the declared Stream Transmission assertion belonging to this StreamDescriptions.
/wsstm:StreamSource/wsstm:StreamDescriptions/sudps:types/xs:schema
The content of the transmitted Stream is defined by a Global Element Declaration (GED) in XML Schema. This element contains collections of imported and inlined schema components that describe the GEDs that are used to define Stream Transmission content.
/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/@type

Optional type that if provided MUST equal  http://???/Mechanism/soap-over-udp

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/sudps:stream

This element describes the properties of this SOAP-over-UDP Stream transmission.

/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/sudps:stream/@element
This attribute refers to a GED defined or imported in the /wsstm:StreamDescriptions/wsstm:types element. The referenced GED serves as the definition of this Stream Type.
/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/sudps:stream/@actionURI
This OPTIONAL attribute provides a value for the 'action' property used to transmit the Stream, serve as a potential aid to identifying the semantics implied by the message. When not present the implied value of this attribute is the concatenation of the wsstm:StreamDescriptions' @targetNamespace attribute and the wsstm:streamType name attribute separated by the '/' character.
/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/sudps:stream/sudps:streamPeriod
This element (XML schema duration type) contains the duration with a fractional second (If the stream source publishes data with 50 Hz it is PT0.02S).
/wsstm:StreamSource/wsstm:StreamDescriptions/wsstm:StreamTransmission/sudps:stream/sudps:streamAddress
This element (endpoint reference type according to WS-Addressing) specifies the multicast address that needs to be joined for receiving the stream. The scheme of the EPR must be soap.udp (e.g.,  soap.udp://239.12.23.23:12345) or derived scheme.

Note: Instead of specifying a streamPeriod it could be used a deadlinePeriod that specifies the maximum duration between two stream packets. (Further discussions required!)

Binding

The stream messages are embedded in unwrapped SOAP messages.

Compression

Due to the fact that SOAP-over-UDP is restricted in the message size that could be transmitted over network. It might be useful to compress the SOAP message using some sort of compression algorithm. To indicate that the SOAP message is compressed, the scheme of the streamAddress should be prefixed with the compression format used.

Example:

<sudps:streamAddress>exi.soap.udp://239.12.23.23:12345</sudps:streamAddress>

exi.soap.udp://239.12.23.23:12345 indicates that the Efficient XML Interchange (EXI) format is used to compress the SOAP message.