5.2 Features and Properties

After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion.  They'll do this using the WSDL features and properties mechanisms.

NOTE: This section assumes the existence, for demonstration purposes, of a security feature named “http://features.example.com/2005/securityFeature” which defines, in the abstract, the idea of message confidentiality.  This feature has a property, "http://features.example.com/2005/securityFeature/securityLevel", which defines various safety levels (from 0, cleartext, all the way through 10, involving  highly complex cryptographic algorithms with keys in the tens of thousands of bits).  We also assume that a SOAP module, named "http://features.example.com/2005/modules/Security", has been defined which implements the security feature described above.

GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer).  Now they'd like to advertise and control the usage of these extensions using WSDL.

5.2.1 SOAP Modules

The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:

Example 5-x.  Requiring a SOAP module in an endpoint
<service name="reservationService" 
       interface="tns:reservationInterface">

     <endpoint name="reservationEndpoint" 
               binding="tns:reservationSOAPBinding"
               address ="http://greath.example.com/2004/reservation">
       <wsoap:module uri="http://features.example.com/2005/modules/Security"
                     required="true"/>
     </endpoint>
        
  </service>


This syntax indicates that a SOAP Module is required by this endpoint.  This means that anyone using this endpoint must a) understand the specification that the module URI refers to, and b) use that specification when communicating with the endpoint in question, which typically means including appropriate SOAP headers on transmitted messages.

If the "required" attribute was not present, or it was set to "false", then the <wsoap:module> syntax would indicate the availability of the referenced module, rather than a requirement to engage it.  [Ed note(Glen) : explain here about requiredness differences when implementing WSDL as a service provider rather than consumer]

5.2.2 Abstract Features

Since GreatH began the web service improvements, they have been talking to several travel agents.  The possibility of making their simple hotel interface an industry standard amongst a consortium of hotels has come up, and as such they would like to enable specifying the requirement for the "makeReservation" operation to be secure at the interface level – in other words indicating that the operation must be secure, but without specifying exactly how that should concretely be achieved (to enable maximal reuse of the interface).  Therefore our next example uses the WSDL feature element.

Example 5.x.  Declaring an abstract feature requirement
<interface name="reservationInterface">
 <operation name="makeReservation">
  <feature uri="http://features.example.com/2005/securityFeature"
           required="true"/>
  ... rest of operation description is unchanged ... 
 </operation>
</interface>

This declaration indicates that understanding of and compliance with the specified security feature is required for all uses of the "makeReservation" operation.  The security feature is <b>abstract</b>, which means although it defines semantics and a level of detail into general operation, it expects some more concrete component (like a SOAP module or binding) to actually realize the functionality.

By definition, if you understand a SOAP module, you understand which (if any) abstract features it implements.  Therefore, since the Security Module in this example is defined as an implementation of the security feature, we know that the use of this module satisfies the requirement to engage the feature.  Therefore users of the HTTP endpoint we defined above (with the required SOAP module) will be fine.  GreatH also defines a new endpoint:

Example 5.x. A SOAP binding over a secure HTTP protocol
<binding name="reservationSecureSOAPBinding"
    interface="tns:reservationInterface"
    type="http://www.w3.org/2004/08/wsdl/soap12"
    wsoap:protocol="http://bindings.example.com/SOAPBindings/secureHTTP">
  ...
</binding>
...
<service name="reservationService">
  ...
  <endpoint name="secureReservationEndpoint"
            binding="tns:reservationSecureSOAPBinding"
            address="https://greath.example.com/2004/secureReservation"/>
</service>

The user will have a choice as to which of the endpoints, and therefore which binding, is to be used, but they both satisfy the abstract feature requirement specified in the interface.

Note that it is not necessary to declare the abstract feature in order to use/require the SOAP module, or in order to use/require the secure binding.  Abstract feature declarations serve purely to indicate requirements which must be fulfilled by more concrete components such as modules or bindings.  In other words, the abstract feature declaration allows components such as interfaces to be reused without caring exactly which SOAP modules or bindings satisfy the feature.

5.2.3 Properties

So far we've discussed how to indicate the availability or the "requiredness" of features and modules.  Often it isn't enough to indicate that a particular extension is available/required - you also need some way to tweak aspects of its behavior.  This is achieved by the use of <b>properties</b>.  Each feature, SOAP module, or SOAP binding may express a variety of <b>properties</b> in its specification.  These properties are very much like variables in a programming language.  If GreatH would like to indicate that the securityLevel property should be 5 for the "makeReservation" operation, it would look like this:

<interface name="reservationInterface">
 <operation name="makeReservation">
  <property
      uri="http://features.example.com/2005/securityFeature/securityLevel">
   <value>5</value>
  </property>
  ... rest of operation definition ...
 </operation>
</interface>

The <property> element describes which property is to be set.  By using the <value> element, the user of the WSDL is informed that the securityLevel property must be set to 5 (the particular meanings of any such values are up to the implementations of the modules/bindings which use them).  The <property> element can be placed at many different levels in a WSDL document (see "Property Composition Model", section 2.8.1.1 in the Core spec).

It is also possible to provide a <b>constraint</b> on the value space for a given property.  This allows the WSDL author to indicate that several valid values for the property are possible for a given scope, limiting the value space already described in the specification that defined the property.  Here's an example to make this clearer:

The security feature specification defines securityLevel as an integer which has values between 1 and 10, each of which indicates, according to the spec, a progressively higher level of security.  The GreatH service authors, having read the relevant specifications, have decided that any security level between 3 and 7 will be supported by their infrastructure.  Levels less than 3 are deemed unsafe for GreatH's purposes, and levels greater than 7 require too much in the way of resources to make it worthwhile.  We can express this in WSDL as follows:

Example 5.x.  Using property constraints
<types>
 <schema>
  <simpleType name="securityLevelConstraint">
   <restriction base="xs:int">
    <min 3, max 7> <!-- check schema for syntax -->
   </restriction>
  </simpleType>
 </schema>
</types>
...
<property uri="http://features.example.com/2005/securityFeature/securityLevel">
  <constraint type="tns:securityLevelConstraint">
</property>
...

First we define, in the <types> section, an XML Schema restriction type over integers with minimum and maximum values as per our discussion above.  Then instead of using the <value> element inside <property>, we use <constraint> and refer to the restriction type.  This informs the implementation that the property must have the appropriate values – this information might be useful to a deployment user interface, for example, which might allow an administrator to set this value with a slider when deploying the service.