WS-Policy language basics

Note

Only element descriptions are provided in this section. Concepts relating to WS-Policy are covered in Chapter 7.

The WS-Policy framework establishes a means of expressing service metadata beyond the WSDL definition. Specifically, it allows services to communicate rules and preferences in relation to security, processing, or message content. Policies can be applied to a variety of Web resources, positioning this specification as another fundamental part of the WS-* extensions discussed in this chapter (Figure 17.3).

Figure 17.3. How WS-Policy relates to the other WS-* specifications discussed in this chapter.

The WS-Policy framework is comprised of the following three specifications:

• WS-Policy
• WS-PolicyAssertions
• WS-PolicyAttachments

These collectively provide the following elements covered in this section, which demonstrate how policies are formulated and attached to element or document-level subjects:

• Policy element
• TextEncoding, Language, SpecVersion, and MessagePredicate assertions
• ExactlyOne element
• All element
• Usage and Preference attributes
• PolicyReference element
• PolicyURIs attribute
• PolicyAttachment element

17.3.1. The Policy element and common policy assertions

The Policy element establishes the root construct used to contain the various policy assertions that comprise the policy. The WS-PolicyAssertions specification supplies the following set of common, predefined assertion elements:

• TextEncoding Dictates the use of a specific text encoding format.
• Language Expresses the requirement or preference for a particular language.
• SpecVersion Communicates the need for a specific version of a specification.
• MessagePredicate Indicates message processing rules expressed using XPath statements.

These elements represent assertions that can be used to structure basic policies around common requirements. Policy assertions also can be customized, and other WS-* specifications may provide supplemental assertions.

Each assertion can indicate whether its use is required or not via the value assigned to its Usage attribute. A value of "Required" indicates that its conditions must be met. Additionally, the use of the Preference attribute allows an assertion to communicate its importance in comparison to other assertions of the same type.

Examples of policy assertions are provided in the subsequent sections.

17.3.2. The ExactlyOne element

This construct surrounds multiple policy assertions and indicates that there is a choice between them, but that one must be chosen.

Case Study

As explained in the case study example provided at the end of the Policies section in Chapter 7, TLS initially produced a policy definition giving partner requestors the option of sending bulk invoice submission messages that comply to one of two versions of the WS-ReliableMessaging specifications.

Following is a sample policy definition that uses the ExactlyOnce construct to communicate the SpecVersion policy alternative. The SpecVersion element's Preference attribute expresses TLS's preferred option.

Example 17.9. The ExactlyOne construct housing two alternative policy assertions, one of which must be used.

 ExactlyOne>
 
 
 ExactlyOne>

 

17.3.3. The All element

The All construct introduces a rule that states that all of the policy assertions within the construct must be met. This element can be combined with the ExactlyOne element, where collections of policy assertions can each be grouped into All constructs that are then further grouped into a parent ExactlyOne construct. This indicates that the policy is offering a choice of assertions groups but that the assertions in any one of the alternative All groups must be met.

Case Study

TLS later expands its original policy definition to enforce a standard text encoding format. It adds the same TextEncoding assertion to each of its policy alternatives and groups the assertions using the All construct, as shown here:

Example 17.10. The All and ExactlyOne constructs used together to provide two alternative policy groups.

 
 All>
 
 
 All>
 All >
 
 
 All>
 

 

Note that a separate OneOrMore construct can also be used to group policy assertions much like the All construct, except that one (or more) of the policy assertions must be met.

 

17.3.4. The Usage attribute

As you've seen in the previous examples, a number of WS-Policy assertion elements contain a Usage attribute to indicate whether a given policy assertion is required. This attribute is a key part of the WS-Policy framework as its values form part of the overall policy rules. The Usage attribute actually has a number of settings worth knowing about, as shown in Table 17.4.

Table 17.4. Possible settings for the Usage attribute.

Attribute Value	Description
Required	The assertion requirements must be met, or an error will be generated.
Optional	The assertion requirements may be met, but an error will not be generated if they are not met.
Rejected	The assertion is unsupported.
Observed	The assertion applies to all policy subjects.
Ignored	The assertion will intentionally be ignored.

 

17.3.5. The Preference attribute

Policy assertions can be ranked in order of preference using this attribute. This is especially relevant if a service provider is flexible enough to provide multiple policy alternatives to potential service requestors.

The Preference attribute is assigned an integer value. The higher this value, the more preferred the assertion. When this attribute is not used, a default value of "0" is assigned to the policy assertion.

17.3.6. The PolicyReference element

So far we've only been discussing the creation of policy documents. However, we have not yet established how policies are associated with the subjects to which they apply. The PolicyReference element is one way to simply link an element with one or more policies. Each PolicyReference element contains a URI attribute that points to one policy document or a specific policy assertion within the document. (The ID attribute of the policy or grouping construct is referenced via the value displayed after the "#" symbol.)

If multiple PolicyReference elements are used within the same element, the policy documents are merged at runtime.

Note

PolicyReference elements can reside within the Policy construct, allowing for the creation of reusable policy modules.

Case Study

If TLS wanted to place policies relating to its Employee Service documents in separate definitions it could do so by using the PolicyReference elements, as shown here:

Example 17.11. Separate PolicyReference elements referencing two policy documents.

 PolicyReference URI=
 "http://www.xmltc.com/tls/policy1.xml#Employee1"/>
 PolicyReference URI=
 "http://www.xmltc.com/tls/policy2.xml#Employee2"/>

 

17.3.7. The PolicyURIs attribute

Alternatively, the PolicyURIs attribute also can be used to link to one or more policy documents. The attribute is added to an element and can be assigned multiple policy locations. As with PolicyReference, these policies are then merged at runtime.

Case Study

TLS could also reference its employee policy definitions by using the PolicyURIs attribute, as shown here:

Example 17.12. The PolicyURIs attribute referencing two policy documents.

PolicyURIs=
 "http://www.xmltc.com/tls/policy1.xml#Employee1"
 "http://www.xmltc.com/tls/policy2.xml#Employee2"/>

 

17.3.8. The PolicyAttachment element

Another way of associating a policy with a subject is through the use of the PolicyAttachment construct. The approach taken here is that the child AppliesTo construct is positioned as the parent of the subject elements. The familiar PolicyReference element then follows the AppliesTo construct to identify the policy assertions that will be used.

Case Study

Finally, TLS can embed the policy assertion reference using the PolicyAttachment and AppliesTo constructs. In the following example, the policy assertion is attached to a specific endpoint reference.

Example 17.13. The PolicyAttachment construct using the child AppliesTo construct to associate a policy with a WS-Addressing EndpointReference construct.

PolicyAttachment>
 AppliesTo>
 
 
 http://www.xmltc.com/tls/ep1
 
 
 emp:EmployeeInterface
 
 
 emp:Employee
 
 
 AppliesTo>
 
PolicyAttachment>

 

17.3.9. Additional types of policy assertions

It is important to note that policy assertions can be utilized and customized beyond the conventional manner in which they are displayed in the preceding examples.

For example:

• Policy assertions can be incorporated into WSDL definitions through the use of a special set of policy subjects that target specific parts of the definition structure. A separate UsingPolicy element is provided for use as a WSDL extension.
• WS-ReliableMessaging defines and relies on WS-Policy assertions to enforce some of its delivery and acknowledgement rules.
• WS-Policy assertions can be created to communicate that a Web service is capable of participating in a business activity or an atomic transaction.
• A policy assertion can be designed to express a service's processing requirements in relation to other WS-* specifications.
• WS-Policy assertions commonly are utilized within the WS-Security framework to express security requirements.

SUMMARY OF KEY POINTS

• WS-Policy specifications establish an extensible policy definition framework that can be used to add a layer of messaging integrity to SOAs.
• Policies can consist of one or more policy assertions, which can further be grouped and offered as alternatives using the ExactlyOne, All, or OneOrMore constructs.
• There are different options as to how policies can be attached to the resources they govern, as provided by the PolicyAttachment and PolicyReference elements and the PolicyURIs attribute.