2.10 Referencing Policy Expressions

Company-X has numerous Web service offerings that provide different kinds of real-time quotes and book information on securities such as GetRealQuote, GetRealQuotes and GetExtendedRealQuote. To accommodate the diversity of Company-X’s customers, Company-X supports multiple WSDL bindings for these Web services. Company-X provides consistent ways to interact with their services and wants to represent these capabilities and requirements consistently across all of their offerings without duplicating policy expressions multiple times. How? It is simple - a policy expression can be named and referenced for re-use.

Section 2.2 Simple Message, showed how a policy expression can be attached directly to a binding inline. A single policy expression may be used in several parts of a WSDL document. In this case it is desirable to use references to the policy expression rather than to directly inline the policy expression.

A policy expression may be identified by an IRI and referenced for re-use as a standalone policy or within another policy expression. There are three mechanisms to identify a policy expression: the wsu:Id, xml:id and Name attributes. A PolicyReference element can be used to reference a policy expression identified using either of these mechanisms.

<Policy wsu:Id="common">
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

In the example above, the wsu:Id attribute is used to identify a policy expression. The value of the wsu:Id attribute is an XML ID. The relative IRI for referencing this policy expression (within the same document) is #common. If the policy document IRI is http://x.example.com/policy.xml then the absolute IRI for referencing this policy expression is http://x.example.com/policy.xml#common. (The absolute IRI is formed by combining the document IRI, # and the value of the wsu:Id attribute.)

In addition to the Example 2-12, Company-X could have used either the xml:id or wsu:Id. An example of the use of xml:id similar to that of wsu:Id is shown in Example 2-13.

<Policy xml:id="common">
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

Conditions and constraints on the use of the |xml:id| attribute in conjunction with Canonical XML 1.0 are specified in Appendix C of XML ID and are further detailed in C14N 1.0 Note. Significant care is suggested in the use of xml:id.

For re-use, a PolicyReference element can be used to reference a policy expression as a standalone policy or within another policy expression. The example below is a policy expression that re-uses the common policy expression above.

<PolicyReference URI="#common"/>

For referencing a policy expression within the same XML document, Company-X uses the wsu:Id attribute for identifying a policy expression and an IRI to this ID value for referencing this policy expression using a PolicyReference element.

The example below is a policy expression that re-uses the common policy expression within another policy expression. This policy expression requires the use of addressing, one of transport- or message-level security for protecting messages and allows the use of optimization.

<Policy wsu:Id="secure">
  <All>
    <PolicyReference URI="#common"/>
    <ExactlyOne>     
      <sp:TransportBinding>…</sp:TransportBinding>
      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </ExactlyOne>
  </All>
</Policy>

The Name attribute and referencing policy expressions outside of the same document are discussed in section 3.6.

3.6 Policy Retrieval

Just as other service metadata languages, Web Services Policy does not mandate any specific policy retrieval mechanism. Any combination of any retrieval mechanisms in any order may be used for referencing policy expressions. Example retrieval mechanisms are:

• Do nothing. A policy expression with the referenced IRI is already known to be available in a local cache or chip (embedded systems).

• Use the referenced IRI and retrieve an existing policy expression from the containing XML document: a policy element with an XML ID.

• Use the referenced IRI and retrieve a policy expression from some policy repository (local or remote), registry, or catalog. Policy tools or policy-aware clients may use any protocols (say UDDI or Web Services Metadata Exchange) for such metadata retrieval. These protocols may require additional out of band information.

• Attempt to resolve the referenced IRI on the Web. This may resolve to a policy element or a resource that contains a policy element.

If the referenced policy expression is in the same XML document as the reference, then the policy expression should be identified using the wsu:Id|xml:id (XML ID) attribute and referenced using an IRI reference to this XML ID value as described in 2.10 Referencing Policy Expressions.

If the referenced policy expression is not in the same XML document as the reference, then the referenced policy expression should be identified using the Name attribute. The value of the Name attribute is an absolute IRI and is independent of the location of the XML document where the identified policy expression resides in. As such, referencing a policy expression using the Name attribute relies on additional out of band information and is outside the scope of the Web Services Policy Framework and Attachment. In the example below, the Name attribute identifies the policy expression. The IRI that identifies this policy expression is http://x.example.com/policy/common, but its location for the purpose of retrieval may be http://repository.example.com/policy/common.

<Policy Name="http://x.example.com/policy/common">
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

The example below is a policy expression that re-uses the common policy expression above.

<PolicyReference URI="http://x.example.com/policy/common"/>

The following example shows a policy expression identified using a UDDI key, which may refer to a tModel that references the reusable policy expression as described in section 6.3 of [Web Services Policy Attachment].

<PolicyReference URI="uddi:3bed4710-1f46-11dc-899e-391cf3b1899c"/>

The reusable policy expression could be registered in UDDI using a tModel as shown in Example xxx.

<tModel tModelKey="uddi:3bed4710-1f46-11dc-899e-391cf3b1899c">
  <name>…</name>
  <description xml:lang="EN">
Policy Expression for example's Web services
  </description>
  <overviewDoc>
    <description xml:lang="EN">Web Services Policy Expression</description>
    <overviewURL>http://repository.example.com/policy/common</overviewURL>
  </overviewDoc>
  <categoryBag>
    <keyedReference
      keyName="Reusable policy Expression"
      keyValue="policy"
      tModelKey="uddi:w3.org:ws-policy:v1.5:attachment:policytypes" />
    <keyedReference
      keyName="Policy Expression for example's Web services"
      keyValue="http://x.example.com/policy/common"
      tModelKey="uddi:w3.org:ws-policy:v1.5:attachment:remotepolicyreference" />
  </categoryBag>
</tModel>

WSDL 1.1 [WSDL 1.1] section 2.1 and WSDL 2.0 [WSDL 2.0 Core Language] chapter 4 allow to import or include WSDL documents into another WSDL document with the wsdl11:import, wsdl20:import, and wsdl20:include statements. The importing and imported WSDL documents constitute separate XML documents each. If e.g. the importing WSDL document references a policy in the imported WSDL document, the rules for policy references between separate XML documents apply as described above.

As policy expressions are composed from other policy expressions and assertions from different domains are used in a policy expression, complex expressions will emerge. Naming parts of complex expressions for reuse and building more complex policies through referencing enables building more complicated policy scenarios easily. This approach enables the association of additional policy subjects to identified policy expressions. It also promotes manageability of the expressions as they are uniquely identified and allows profiles for common scenarios to be developed. Note that when a named expression has assertions that contains parameterized expressions, care must be given to ensure that the parameterized content is statically available to enable reuse.