- From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 26 Sep 2006 20:44:49 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv20498
Modified Files:
ws-policy-primer.xml
Log Message:
Made a first pass at making the editorial changes reported by Paul Cotton. Acknowledgements and Reference fix-up pending
Index: ws-policy-primer.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-primer.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- ws-policy-primer.xml 26 Sep 2006 07:31:51 -0000 1.10
+++ ws-policy-primer.xml 26 Sep 2006 20:44:46 -0000 1.11
@@ -107,7 +107,7 @@
policy assertions, outlines guidelines for designing policy assertions and enumerates the
minimum requirements for describing policy assertions in specifications.</p>
<p>This is a non-normative document and does not provide a definitive specification of the Web
- Services Policy language. <specref ref="xml-namespaces"/> lists all the that are used in
+ Services Policy language. <specref ref="xml-namespaces"/> lists all the namespaces that are used in
this document. (XML elements without a namespace prefix are from the Web Services Policy XML
Namespace.)</p>
</div1>
@@ -168,10 +168,10 @@
</soap:Envelope></eg>
</example>
<p>This message uses message addressing headers. The <code>wsa:To</code>
- and<code>wsa:Action</code> header blocks identify the destination and the semantics
+ and <code>wsa:Action</code> header blocks identify the destination and the semantics
implied by this message respectively. (The prefix <code>wsa</code> is used here to denote
the Web Services Addressing XML Namespace. <specref ref="xml-namespaces"/> lists all the
- and prefixes that are used in this document.)</p>
+ namespaces and prefixes that are used in this document.)</p>
<p>Let us look at a fictitious scenario used in this document to illustrate the features of
the policy language. Tony is a Web service developer. He is building a client application
that retrieves real time stock quote information from Contoso, Ltd. Contoso supplies real
@@ -211,7 +211,7 @@
<code>wsap</code> is used here to denote the Web Services Addressing – WSDL Binding XML
Namespace.) This assertion identifies the use of Web Services Addressing information
headers. A policy-aware client can recognize this policy assertion, engage addressing
- automatically, and use headers such as<code>wsa:To</code> and <code>wsa:Action</code> in
+ automatically, and use headers such as <code>wsa:To</code> and <code>wsa:Action</code> in
SOAP Envelopes.</p>
<p>It is important to understand the association between the SOAP message and policy
expression in the above example. As you can see by careful examination of the message,
@@ -332,10 +332,10 @@
<p>Policy assertions can be combined in different ways to express consistent combinations of
behaviors (capabilities and requirements). There are three policy operators for combining
policy assertions: <code>Policy</code>, <code>All</code> and <code>ExactlyOne</code>
- (the<code>Policy</code> operator is a synonym for<code>All).</code></p>
+ (the <code>Policy</code> operator is a synonym for <code>All).</code></p>
<p>Let us consider the <code>All</code> operator first. The policy expression in the example
below requires the use of addressing and transport-level security. There are two policy
- assertions. These assertions are combined using the<code>All</code> operator. Combining
+ assertions. These assertions are combined using the <code>All</code> operator. Combining
policy assertions using the <code>Policy</code> or <code>All</code> operator means that
all the behaviors represented by these assertions are required.</p>
<example>
@@ -359,7 +359,7 @@
assertion identifies the use of message-level security – such as <emph>WS-Security
1.0</emph> - for protecting messages. Policy-aware clients can recognize this policy
assertion, engage message-level security for protecting messages and use headers such
- as<code>wss:Security</code> in SOAP Envelopes.</p>
+ as <code>wss:Security</code> in SOAP Envelopes.</p>
<p>To allow the use of either transport- or message-level security, Contoso uses the
<code>ExactlyOne</code> policy operator. Policy assertions combined using the
<code>ExactlyOne</code> operator requires exactly one of the behaviors represented by
@@ -374,7 +374,7 @@
</example>
<p>Contoso requires the use of addressing and requires the use of either transport- or
message-level security for protecting messages. They represent this combination using
- the<code>All</code> and <code>ExactlyOne</code> operators. Policy operators can be mixed
+ the <code>All</code> and <code>ExactlyOne</code> operators. Policy operators can be mixed
to represent different combinations of behaviors (capabilities and requirements). The
policy expression in the example below requires the use of addressing and one of
transport- or message-level security for protecting messages.</p>
@@ -462,7 +462,7 @@
<p>In the example below, the child <code>Policy</code> element is a nested policy expression
and further qualifies the behavior of the <code>sp:TransportBinding</code> policy
assertion. The <code>sp:TransportToken</code> is a nested policy assertion of
- the<code>sp:TransportBinding</code> policy assertion. The<code>sp:TransportToken</code>
+ the <code>sp:TransportBinding</code> policy assertion. The <code>sp:TransportToken</code>
assertion requires the use of a specific transport token and further qualifies the
behavior of the <code>sp:TransportBinding</code> policy assertion (which already requires
the use of transport-level security for protecting messages).</p>
@@ -485,7 +485,7 @@
</sp:TransportBinding></eg>
</example>
<p>The <code>sp:AlgorithmSuite</code> is a nested policy assertion of
- the<code>sp:TransportBinding</code> policy assertion. The<code>sp:AlgorithmSuite</code>
+ the <code>sp:TransportBinding</code> policy assertion. The <code>sp:AlgorithmSuite</code>
assertion requires the use of the algorithm suite identified by its nested policy
assertion (<code>sp:Basic256Rsa15</code>
<emph>in the example above</emph>) and further qualifies the behavior of the
@@ -500,7 +500,7 @@
<head>Referencing Policy Expressions</head>
<p>Contoso has numerous Web service offerings that provide different kinds of real-time
quotes and book information on securities such as
- <code>GetRealQuote</code>,<code>GetRealQuotes</code> and
+ <code>GetRealQuote</code>, <code>GetRealQuotes</code> and
<code>GetExtendedRealQuote</code>. To accommodate the diversity of Contoso’s customers,
Contoso supports multiple WSDL bindings for these Web services. Contoso provides
consistent ways to interact with their services and wants to represent these capabilities
@@ -527,7 +527,7 @@
<code>http://real.contoso.com/policy.xml#common. (</code>The absolute IRI is formed by
combining the document IRI, <code>#</code> and the value of the <code>wsu:Id</code>
attribute.)</p>
- <p>For re-use, a<code>PolicyReference</code> element can be used to reference a policy
+ <p>For re-use, a <code>PolicyReference</code> 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.</p>
<example>
@@ -580,13 +580,13 @@
descriptions.</p>
<p>In the example below, the <code>SecureBinding</code> WSDL binding description defines a
binding for an interface that provides real-time quotes and book information on
- securities. (The prefixes<code>wsdl</code> and <code>tns</code> are used here to denote
+ securities. (The prefixes <code>wsdl</code> and <code>tns</code> are used here to denote
the Web Services Description language XML namespace and target namespace of this WSDL
document.) To require the use of security for these offerings, Contoso attaches the secure
policy expression in the previous section to this binding description. The WSDL
<code>binding</code> element is a common policy attachment point. The secure policy
expression attached to the <code>SecureBinding</code> WSDL binding description applies to
- any message exchange associated with any<code>port</code> that supports this binding
+ any message exchange associated with any <code>port</code> that supports this binding
description. This includes all the message exchanges described by operations in the
<code>RealTimeDataInterface</code>.</p>
<example>
@@ -601,7 +601,7 @@
provides other kinds of data through Web services such as quotes delayed by 20 minutes and
security symbols through Web services (for example <code>GetDelayedQuote</code>,
<code>GetDelayedQuotes,</code>
- <code>GetSymbol</code> and<code>GetSymbols</code>). Contoso does not require the use of
+ <code>GetSymbol</code> and <code>GetSymbols</code>). Contoso does not require the use of
security for these services, but requires the use of addressing and allows the use of
optimization.</p>
<example>
@@ -687,8 +687,8 @@
Policy. A policy expression consists of a <code>Policy</code> wrapper element and a
variety of child and descendent elements. Child and descendent elements from the policy
language are <code>Policy, All</code>, <code>ExactlyOne</code>
- and<code>PolicyReference</code>. Other child elements of<code>Policy</code>,
- <code>All</code> and<code>ExactlyOne</code> are policy assertions. (The<code>Policy</code>
+ and <code>PolicyReference</code>. Other child elements of<code>Policy</code>,
+ <code>All</code> and <code>ExactlyOne</code> are policy assertions. (The <code>Policy</code>
element plays two roles: wrapper element and operator.) Policy assertions can contain a
nested policy expression. Policy assertions can also be marked optional to represent
behaviors that may be engaged (capabilities) for an interaction. The optional marker is
@@ -709,8 +709,8 @@
</Policy></eg>
</example>
<p>The <code>Policy</code> element is the wrapper element. The <code>All</code>
- and<code>ExactlyOne</code> elements are the policy operators. All other child elements
- of the<code>All</code> and <code>ExactlyOne</code> elements are policy assertions from
+ and <code>ExactlyOne</code> elements are the policy operators. All other child elements
+ of the <code>All</code> and <code>ExactlyOne</code> elements are policy assertions from
domains such as messaging, addressing, security, reliability and transactions.</p>
</div2>
<div2 id="normal-form-for-policy-expressions">
@@ -743,7 +743,7 @@
<p>The normal form consists of a <code>Policy</code> wrapper element and has one child
<code>ExactlyOne</code> element. This <code>ExactlyOne</code> element has zero or more
<code>All</code> child elements. Each of these <code>All</code> elements has zero or
- more policy assertions. The<code>PolicyReference</code> element and
+ more policy assertions. The <code>PolicyReference</code> element and
<code>wsp:Optional</code> attribute are not used in the normal form. And, a nested policy
expression in the normal form has at most one policy alternative.</p>
<p>The normal form represents a policy as a collection of policy alternatives and a policy
@@ -930,7 +930,7 @@
</item>
<item>
<p>The <code>Policy</code> wrapper element and policy alternatives which correspond to
- the<code>Policy/ExactlyOne</code> element map to a policy.</p>
+ the <code>Policy/ExactlyOne</code> element map to a policy.</p>
</item>
</ulist>
<p>The diagram below describes this mapping from the normal form of a policy expression to
@@ -1014,8 +1014,8 @@
<p>In <specref ref="basic-concepts-policy-expression"/>, we looked into how Contoso attached
their policy expressions to the WSDL <code>binding</code> element. In addition to the WSDL
<code>binding</code> element, a policy expression can be attached to other WSDL elements
- such as <code>service</code>,<code>port</code>, <code>operation</code>
- and<code>message</code>. These elements are the WSDL policy attachment points in a WSDL
+ such as <code>service</code>, <code>port</code>, <code>operation</code>
+ and <code>message</code>. These elements are the WSDL policy attachment points in a WSDL
document.</p>
<p>The WSDL attachment points are partitioned (as illustrated below) into four policy
subjects: message, operation, endpoint and service. When attached, capabilities and
@@ -1026,7 +1026,7 @@
<p>The WSDL <code>service</code> element represents the service policy subject. Policy
expressions associated with a service policy subject apply to any message exchange using
any of the endpoints offered by that service.</p>
- <p>The WSDL <code>port</code>,<code>binding</code> and <code>portType</code> elements
+ <p>The WSDL <code>port</code>, <code>binding</code> and <code>portType</code> elements
collectively represent the endpoint policy subject. Policy expressions associated with an
endpoint policy subject apply to any message exchange made using that endpoint.</p>
<p>The WSDL <code>binding/operation</code> and <code>portType/operation</code> elements
@@ -1087,7 +1087,7 @@
<p>Multiple policy expressions may be attached to WSDL constructs. Let us consider how
Contoso could have used multiple policy expressions in a WSDL document. In the example
below, there are two policy expressions <code>#common2</code> and <code>#secure2</code>
- attached to the <code>SecureBinding</code> WSDL binding and<code>RealTimeDataPort</code>
+ attached to the <code>SecureBinding</code> WSDL binding and <code>RealTimeDataPort</code>
WSDL port descriptions.</p>
<example>
<head>Multiple Policy Expressions Attached to Endpoint Policy Subject </head>
@@ -1126,10 +1126,10 @@
<p>The effective policy is the combination of two or more policy expressions attached to the
same policy subject. The combination of two policy expressions, also known as the merged
policy expression, is a new policy expression that combines these two policy expressions
- using the<code>All</code> policy operator.</p>
+ using the <code>All</code> policy operator.</p>
<p>The policy expression below is the combination of the two policy expressions attached to
the <code>SecureBinding</code> WSDL binding and <code>RealTimeDataPort</code> WSDL port
- descriptions. The<code>#common2</code> policy expression has two policy alternatives. The
+ descriptions. The <code>#common2</code> policy expression has two policy alternatives. The
<code>#secure2</code> policy expression has two policy alternatives<code>.</code> The
combination of these two policies is equivalent to Contoso’s secure policy in <specref
ref="basic-concepts-policy-expression"/> and has four policy alternatives. In other
@@ -1161,8 +1161,8 @@
<div2 id="extensibility-and-versioning">
<head>Extensibility and Versioning</head>
<p>Web Services Policy language is an extensible language by design. The
- <code>Policy</code>,<code>ExactlyOne</code>, <code>All</code>
- and<code>PolicyReference</code> elements are extensible. The <code>Policy</code>,
+ <code>Policy</code>, <code>ExactlyOne</code>, <code>All</code>
+ and <code>PolicyReference</code> elements are extensible. The <code>Policy</code>,
<code>ExactlyOne</code> and <code>All</code> elements allow child element and attribute
extensibility. The <code>PolicyReference</code> element allows attribute extensibility.
Extensions must not use the policy language XML namespace name. A consuming processor
@@ -1293,10 +1293,10 @@
identified by this policy assertion.</p>
<p>The <code>sp:IssuedToken</code> policy assertion has three parameters:
<code>@sp:IncludeToken</code>, <code>sp:Issuer</code>
- and<code>sp:RequestSecurityTokenTemplate</code>.</p>
+ and <code>sp:RequestSecurityTokenTemplate</code>.</p>
<p>The <code>sp:IncludeToken</code> attribute is a parameter that contains information on
whether a security token should be included in messages or an external reference to the
- key of this security token should be used. The<code>sp:Issuer</code> parameter is an
+ key of this security token should be used. The <code>sp:Issuer</code> parameter is an
endpoint reference to a security token issuer. The
<code>sp:RequestSecurityTokenTemplate</code> parameter contains the necessary information
to request a security token from the specified issuer. Parameters are the opaque payload
@@ -1436,7 +1436,7 @@
<head>Optional Behaviors</head>
<p>A policy assertion identifies a domain specific behavior that is a requirement relevant
to a Web Service interaction. Policy assertions can be marked optional using
- the<code>wsp:Optional</code> attribute marker to represent behaviors that may be
+ the <code>wsp:Optional</code> attribute marker to represent behaviors that may be
engaged (capabilities) for an interaction. It is important to note that behavior (policy
assertion) and optional representation (<code>wsp:Optional</code> attribute) are
distinct ideas of the Web Services Policy language. Conflating these distinct ideas
@@ -1592,7 +1592,13 @@
behaviors.</p>
</div3>
<div3 id="versioning-policy-language"><head>Versioning Policy Language</head>
- <p>EdNote: The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited</p>
+ <p>
+ <ednote>
+ <edtext>
+ The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited
+ </edtext>
+ </ednote>
+ </p>
<p>Over time, the Policy WG or third parties can version or extend the Policy Language with new or modified constructs. These constructs may be compatible or incompatible with previous versions. Some of the possible new constructs that have been mentioned previously are: new operators, operator cardinality, policy identification, compact syntax, Policy Inclusion, security, referencing, attachment points, alternative
priority, effective dating, negotiation. </p>
<p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
@@ -1659,8 +1665,8 @@
</wsp:ExactlyOne>
</wsp:Policy>]]></eg>
</example>
-<p>Because the wsp16:Choice alternative isn't understand in either normalized form, it will not be chosen as one of the alternatives and will effectively be ignored. Policy intersection may be more difficult with such compatible extensions. For example, the previous will "look"
-like it has a wsp16:Choice typed assertion. To determine intersection with a Policy that does not have the wsp16:Choice type assertion, domain specific processing would have to be done. However, there is an alternative that does not have the wsp16:Choice, so intersection would yield the expecteded result.
+<p>Because the wsp16:Choice alternative isn't understood in either normalized form, it will not be chosen as one of the alternatives and will effectively be ignored. Policy intersection may be more difficult with such compatible extensions. For example, the previous will "look"
+like it has a wsp16:Choice typed assertion. To determine intersection with a Policy that does not have the wsp16:Choice type assertion, domain specific processing would have to be done. However, there is an alternative that does not have the wsp16:Choice, so intersection would yield the expected result.
</p>
<p>Note: it is possible to add new names to the existing namespace, such as: </p>
<example><head>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</head>
@@ -1754,7 +1760,7 @@
...]]></eg>
</example>
-<p>The PolicyReference is attribute extensible. One example of an addition is a list of backup URIs for the policyReference:</p>
+<p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p>
<example><head>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</head>
<eg><![CDATA[<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
@@ -1773,7 +1779,7 @@
<wsdl11:operation name="GetLastTradePrice" > ....
...]]></eg>
</example>
-<p>The policy framework specification says that any unknown attributes are ignored. Policy 1.5 processor will not understand the wsp16:alternateURI attribute, it will be ignored. A Policy 1.6 processor will understand the alternate URIs so it won't be ignored.</p>
+<p>The policy framework specification says that any unknown attributes are ignored. A Policy 1.5 processor will not understand the wsp16:alternateURI attribute, it will be ignored. A Policy 1.6 processor will understand the alternate URIs so it won't be ignored.</p>
<p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p>
</div4>
@@ -2106,7 +2112,14 @@
to insert a reference to the Security Considerations section from the Framework document.
</td>
</tr>
-
+ <tr>
+ <td>20060926</td>
+ <td>PY</td>
+ <td>Made a first pass at making the editorial changes
+ <loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2006Sep/0165.html">reported by Paul Cotton.</loc>
+ Acknowledgements and Reference fix-up pending
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Tuesday, 26 September 2006 20:44:58 UTC