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.

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.

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.

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.

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.

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.

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.