Application Data Feature Policy

Overview

Defines a list of qualified names, each of which identifies a header 'understood' by service to which RECEIVED actions are targeted (policy does not affect SENT actions.) For more information regarding how policy is used, e.g. how and where it may be attached and the difference between public and private policy, please see the user guide.

Vocabulary 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0" xmlns:tns="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0" elementFormDefault="qualified">
  <xs:element name="UnderstoodHeaders">
    <xs:annotation>
      <xs:documentation>Defines assertion with policy scope SERVICE, ENDPOINT, OPERATION or MESSAGE used to constrain the 'Application Data' feature.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Header" maxOccurs="unbounded">
          <xs:annotation>
            <xs:documentation>Defines qualified name of a message header targeted to 'ultimate destination' understood by the receiving node.</xs:documentation>
          </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Examples

Note that the type of policy used to constrain this feature module is an extension to the core EOA specification. The examples below use policy which complies with version 1.5 of the ws-policy specification.

Public Policy

This feature does not support public policy.

Private Policy

Note that the following examples use the "default engine" provider to demonstrate private policy attachements. The structure employed by other providers should be similar. The following WSDL descriptions are referenced within the examples below (note that the abstract component defs within the WSDL 1.1 definition have been elided for clarity.)

WSDL Descriptions 
<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <components>
    <wsdl:description xmlns:wsdl="http://www.w3.org/ns/wsdl" targetNamespace="http://com.mycompany/eoa/1.0" xmlns:tns="http://com.mycompany/eoa/1.0">
      <wsdl:types>
        <xs:import xmlns:xs="http://www.w3.org/2001/XMLSchema" namespace="http://mycompany.com" />
      </wsdl:types>
      <wsdl:interface name="MyInterface" xmlns:tns1="http://mycompany.com">
        <wsdl:operation name="MyOperation1" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="tns1:myElement" />
          <wsdl:output element="tns1:myElement" />
        </wsdl:operation>
        <wsdl:operation name="MyOperation2" pattern="http://www.w3.org/ns/wsdl/in-out">
          <wsdl:input element="tns1:myElement" />
          <wsdl:output element="tns1:myElement" />
        </wsdl:operation>
      </wsdl:interface>
      <wsdl:binding name="MyBinding" type="http://www.w3.org/ns/wsdl/soap" xmlns:wsoap="http://www.w3.org/ns/wsdl/soap" wsoap:version="1.2" wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/" />
      <wsdl:service name="MyService" interface="tns:MyInterface">
        <wsdl:endpoint name="MyEndpoint1" binding="tns:MyBinding" address="http://someuri/MyEndpoint1/" />
        <wsdl:endpoint name="MyEndpoint2" binding="tns:MyBinding" address="http://someuri/MyEndpoint2/" />
      </wsdl:service>
      <ext:application xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="MyApplication">
        <ext:role name="http://myRole" interface="tns:MyInterface" />
      </ext:application>
      <ext:engine xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="MyEngine" application="tns:MyApplication">
        <ext:actor role="http://myRole" service="tns:MyService" />
      </ext:engine>
    </wsdl:description>
    <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://partnercompany.com" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://partnercompany.com">
      <wsdl:portType name="PortType">
        <wsdl:operation name="lookupValue">
          <wsdl:input xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" message="ns0:lookupValueRequest" wsam:Action="urn:lookupValue" />
          <wsdl:output xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" message="ns0:lookupValueResponse" wsam:Action="urn:lookupValueResponse" />
          <wsdl:fault xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" message="ns0:NameNotFoundException" name="NameNotFoundException" wsam:Action="urn:lookupValueNameNotFoundException" />
        </wsdl:operation>
      </wsdl:portType>
      <wsdl:binding name="Binding" type="tns:PortType">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
        <wsdl:operation name="lookupValue">
          <soap:operation soapAction="urn:lookupValue" style="document" />
          <wsdl:input>
            <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
            <soap:body use="literal" />
          </wsdl:output>
          <wsdl:fault name="NameNotFoundException">
            <soap:fault use="literal" name="NameNotFoundException" />
          </wsdl:fault>
        </wsdl:operation>
      </wsdl:binding>
      <wsdl:service name="ValueLookupService">
        <wsdl:port name="ValueLookupServicePort" binding="tns:Binding">
          <soap:address location="http://somehost:8080/services/ValueLookupService" />
        </wsdl:port>
      </wsdl:service>
      <ext:application xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="ValueLookupApplication">
        <ext:role name="http://partnerRole" interface="tns:PortType" />
      </ext:application>
      <ext:engine xmlns:ext="http://bluestemsoftware.org/specification/eoa/1.0/component/wsdl/ext" name="ValueLookupEngine" application="tns:ValueLookupApplication">
        <ext:actor role="http://partnerRole" service="tns:ValueLookupService" />
      </ext:engine>
    </wsdl:definitions>
  </components>
</deployment>
Defining Headers Understood by 'My' Service

If a header targeted to 'ultimate destination' is marked as 'must understand', the qualified name of header must be defined via private policy. Note that the rules which define the term 'ulimate destination' and 'must understand' are messaging protocol specific, e.g. SOAP. Using the SOAP rules, header blocks where role is undefined, where soap version is 1.2 and value of role is soap 1.2 'ultimate receiver' uri or value of role is soap version specific 'next' uri, would be considered to be targeted at the 'ultimate destination.'

All four policy subjects SERVICE, ENDPOINT, OPERATION and MESSAGE are supported when using the wsad:UnderstoodHeaders assertion as defined within the example below:

Defining Understood Request Headers

Using the example WSDL description listed above, to define request headers understood by locally hosted service "MyService" requires the following private policy, which uses three different policy scopes for the purpose of demonstration.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:MyEngine">
      <partners>
        <engineReference xmlns:ns="http://com.mycompany/eoa/1.0" engineName="ns:MyEngine">
          <serviceReference serviceName="ns:MyService">
            <endpointReference endpointName="MyEndpoint1">
              <operationReference operationName="ns:MyOperation1">
                <!-- 
                  policy with subject operation, which affects only request
                  actions defined on referenced operation
                -->
                <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                  <!-- 
                    identifies headers 'understood' by targeted service.
                    headers in request message targeted to 'ultimate
                    destination' and flagged as mustUnderstand, must
                    appear in this list or a fault is thrown
                  -->
                  <wsad:UnderstoodHeaders xmlns:wsad="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0">
                    <wsad:Header xmlns:ns="http://e">ns:E</wsad:Header>
                    <wsad:Header xmlns:ns="http://f">ns:F</wsad:Header>
                  </wsad:UnderstoodHeaders>
                </wsp:Policy>
              </operationReference>
              <!-- 
                policy with subject endpoint, which affects only request
                actions defined on referenced endpoint
              -->
              <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                <!-- 
                  identifies headers 'understood' by targeted service.
                  headers in request message targeted to 'ultimate
                  destination' and flagged as mustUnderstand, must
                  appear in this list or a fault is thrown
                -->
                <wsad:UnderstoodHeaders xmlns:wsad="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0">
                  <wsad:Header xmlns:ns="http://c">ns:C</wsad:Header>
                  <wsad:Header xmlns:ns="http://d">ns:D</wsad:Header>
                </wsad:UnderstoodHeaders>
              </wsp:Policy>
            </endpointReference>
            <!-- 
              policy with subject service, which affects all request
              actions defined on referenced service
            -->
            <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
              <!-- 
                identifies headers 'understood' by targeted service.
                headers in request message targeted to 'ultimate
                destination' and flagged as mustUnderstand, must
                appear in this list or a fault is thrown
              -->
              <wsad:UnderstoodHeaders xmlns:wsad="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0">
                <wsad:Header xmlns:ns="http://a">ns:A</wsad:Header>
                <wsad:Header xmlns:ns="http://b">ns:B</wsad:Header>
              </wsad:UnderstoodHeaders>
            </wsp:Policy>
          </serviceReference>
        </engineReference>
      </partners>
    </engine>
  </providers>
</deployment>

Using the example above, the private policy which configures the application data module for request action defined on "MyEndpoint1" and "MyOperation1" defines six understood headers:

  • {http://a}A
  • {http://b}B
  • {http://c}C
  • {http://d}D
  • {http://e}E
  • {http://f}F

The private policy which configures the application data module for request action defined on "MyEndpoint1" and "MyOperation2" defines four understood headers (operation policy is not in scope for this action):

  • {http://a}A
  • {http://b}B
  • {http://c}C
  • {http://d}D

The private policy which configures the application data module for request action defined on "MyEndpoint2" and "MyOperation1" defines two understood headers (operation policy and endpoint policy are not in scope for this action - only service policy is in scope).

  • {http://a}A
  • {http://b}B

The private policy which configures the application data module for request action defined on "MyEndpoint2" and "MyOperation2" defines two understood headers (operation policy and endpoint policy are not in scope for this action - only service policy is in scope).

  • {http://a}A
  • {http://b}B
Defining Understood Response Headers

Using the example WSDL description listed above, to define response headers understood by locally hosted service "MyService" requires the following private policy, which uses policy subject MESSAGE for the purposes of demonstration, i.e. you'd use whatever scope is appropriate.

<deployment xmlns="http://bluestemsoftware.org/specification/eoa/1.0/deployment">
  <providers>
    <engine xmlns="http://bluestemsoftware.org/specification/eoa/ext/engine/default/1.0" xmlns:tns="http://com.mycompany/eoa/1.0" name="tns:MyEngine">
      <partners>
        <engineReference xmlns:ns="http://partnercompany.com" engineName="ns:ValueLookupEngine">
          <serviceReference serviceName="ns:ValueLookupService">
            <endpointReference endpointName="ValueLookupServicePort">
              <operationReference operationName="ns:lookupValue">
                <actionReference action="urn:lookupValueResponse">
                  <!-- 
                    policy with subject message, which affects only this
                    specific response action
                  -->
                  <wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
                    <!-- 
                      identifies headers 'understood' by targeted service,
                      i.e. service receiving the response. headers in response
                      message targeted to 'ultimate destination' and flagged as
                      mustUnderstand must appear in this list or a fault is thrown
                    -->
                    <wsad:UnderstoodHeaders xmlns:wsad="http://bluestemsoftware.org/specification/eoa/ext/feature/ws/ad/policy/1.0">
                      <wsad:Header xmlns:ns="http://g">ns:G</wsad:Header>
                      <wsad:Header xmlns:ns="http://h">ns:H</wsad:Header>
                    </wsad:UnderstoodHeaders>
                  </wsp:Policy>
                </actionReference>
              </operationReference>
            </endpointReference>
          </serviceReference>
        </engineReference>
      </partners>
    </engine>
  </providers>
</deployment>

Using the example above, the private policy which configures the application data module for response action "urn:lookupValueResponse" defined on operation "ns:lookupValue" and endpoint "ValueLookupServicePort" defines two understood headers:

  • {http://g}G
  • {http://h}H

Note that no understood headers are defined for the response action "urn:lookupValueNameNotFoundException" Policy with MESSAGE scope defined on response action "ns:lookupValue" is not visible relevant to the fault action.