- From: Toufic Boubez via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 13 Sep 2007 21:06:29 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv26778
Modified Files:
ws-policy-guidelines.xml ws-policy-guidelines.html
Log Message:
Implemented the resolution for issue 4861.
Editors' action 353 with the caveats and clarifications expressed in message 2007Sep-0002 of the editors mailing list
http://lists.w3.org/Archives/Public/public-ws-policy-eds/2007Sep/0002.html
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.102
retrieving revision 1.103
diff -u -d -r1.102 -r1.103
--- ws-policy-guidelines.html 13 Sep 2007 20:16:24 -0000 1.102
+++ ws-policy-guidelines.html 13 Sep 2007 21:06:27 -0000 1.103
@@ -125,10 +125,10 @@
5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
5.5 <a href="#Ignorable">Designating Ignorable Behavior</a><br>
- 5.5.1 <a href="#d3e803">Ignorable behavior in authoring</a><br>
- 5.5.2 <a href="#d3e816">Ignorable behavior at runtime</a><br>
+ 5.5.1 <a href="#d3e812">Ignorable behavior in authoring</a><br>
+ 5.5.2 <a href="#d3e825">Ignorable behavior at runtime</a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e831">Optional behavior at runtime</a><br>
+ 5.6.1 <a href="#d3e840">Optional behavior at runtime</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment</a><br>
5.7.1 <a href="#general-attachment-guidelines">General Guidelines</a><br>
5.7.2 <a href="#wsdl-attachment-guidelines">Considerations for Policy Attachment in WSDL</a><br>
@@ -193,7 +193,7 @@
</p></div><div class="div1">
<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practice Statements</h2><p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-semantics"><b>1. Semantics Independent of
Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Define assertions relevant to compatibility tests</b></a></p></li><li><p><a href="#bp-ignorable-for-not-related-to-compatibility-tests"><b>3. Mark Ignorable Assertions not related to compatibility</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>4. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>5. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>6. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>7. Provide an XML definition</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>8. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>9. Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>10. Document Use of the Ignorable
-Attribute in XML </b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>11. Allow use of wsp:Optional</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>12. Define message format only</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>13. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>14. Use Parameters for Useful
+Attribute in XML </b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>11. Assertion Authors should allow use of wsp:Optional</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>12. Define message format only</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>13. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>14. Use Parameters for Useful
Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>15. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>16. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>17. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-leverage-defined-attachment-mechanisms"><b>21. Leverage Defined Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-use-defined-policy-subjects"><b>22. Use Defined Policy Subjects</b></a></p></li><li><p><a href="#bp-identify-policy-subjects"><b>23. Identiy Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>24. Specify WSDL Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>25. Choose the Most Granular WSDL Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>26. Define Rules for Attachment of an Assertion
type to Multiple WSDL policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>27. Specify Preferred WSDL Attachment Point</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>28. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>29. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>30. Independent Assertions for Different Versions of a
Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>31. Document changes to policy
@@ -604,11 +604,11 @@
</pre></div></div><p> The Policy Framework provides two modes of authoring policy expressions:
compact and normal form. One of the mechanisms that the Policy Framework
provides to policy authors for purposes of writing compact policy
-expressions is the wsp:Optional attribute. Assertion Authors should allow
-for the use of the wsp:Optional attribute in the XML outline and/or schema
+ expressions is the <code>wsp:Optional</code> attribute. Assertion Authors should allow
+for the use of the <code>wsp:Optional</code> attribute in the XML outline and/or schema
definition of an assertion as this will allow policy expression authors to
compose compact policy expressions.</p><div class="boxedtext"><p><a name="bp-assertion-xml-allow-optional" id="bp-assertion-xml-allow-optional"></a><span class="practicelab">Best
-Practice 11: Allow use of wsp:Optional</span></p><p class="practice">An assertion's XML outline and/or schema definition should allow the use
+Practice 11: Assertion Authors should allow use of wsp:Optional</span></p><p class="practice">An assertion's XML outline and/or schema definition should allow the use
of the wsp:Optional attribute so as to enable policy authors to compose
compact policy expressions.</p></div><p>For example, consider the following two equivalent policy expressions:</p><div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Normal form expression:</i></p><div class="exampleInner"><pre><wsp:Policy>
@@ -627,7 +627,11 @@
<wsp:Policy/>
</wsam:Addressing>
</wsp:Policy></pre></div></div><p>
-If the assertion author had not provided for the wsp:Optional attribute to be included on the assertion, then policy expression authors would be forced to express the optionality of a behavior as two explicit policy alternatives, one with and one without that assertion when including assertions of that type in their policies.</p></div><div class="div3">
+If the assertion author had not provided for the <code>wsp:Optional</code> attribute
+to be included on the assertion, then policy expression authors would be forced to
+express the optionality of a behavior as two explicit policy alternatives,
+one with and one without that assertion when including assertions of that type in their
+policies.</p></div><div class="div3">
<h4><a name="self-describing" id="self-describing"></a>5.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and
behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One
of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business
@@ -847,16 +851,16 @@
certificate will not be able to use this provider solely on the basis
of intersection algorithm alone.</p></div></div><div class="div2">
<h3><a name="Ignorable" id="Ignorable"></a>5.5 Designating Ignorable Behavior</h3><div class="div3">
-<h4><a name="d3e803" id="d3e803"></a>5.5.1 Ignorable behavior in authoring</h4><p>
+<h4><a name="d3e812" id="d3e812"></a>5.5.1 Ignorable behavior in authoring</h4><p>
The Policy Framework provides an intersection algorithm that has two defined modes for processing (lax and strict). The Framework also defines an attribute (wsp:Ignorable) that can be used to influence whether assertions are part of the compatibility assessment between two alternatives. [see <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> and <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>]. Assertion authors should consider whether the behavior represented by the Assertion they are defining can be safely ignored for the purposes of intersection, and should follow <a href="#DefineIgnorable"><b>9. Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>10. Document Use of the Ignorable
Attribute in XML </b></a> to include this guidance in the assertion's definition.</p></div><div class="div3">
-<h4><a name="d3e816" id="d3e816"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should
+<h4><a name="d3e825" id="d3e825"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should
indicate the semantic of the runtime behavior in the description of the assertion.
</p><p>
As said in <a href="ws-policy-primer.html#strict-lax-policy-intersection">section 3.4.1 Strict and Lax Policy Intersection</a> in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>, "Regardless of the chosen intersection mode, ignorable assertions do not express any wire-level requirements on the behavior of consumers - in other words, a consumer could choose to ignore any such assertions that end up in the resulting policy after intersection, with no adverse effects on runtime interactions." Therefore, any assertion that is marked with ignorable should not impose any wire-level requirements on the part of consumers. Assertion Authors are reminded that regardless of whether an assertion is marked as ignorable, policy consumers using strict intersection will not 'ignore' the assertion.
</p></div></div><div class="div2">
<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.6 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e831" id="d3e831"></a>5.6.1 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e840" id="d3e840"></a>5.6.1 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
both the provider and the consumer, behaviors that must
always be engaged by a consumer must not be marked as
"optional" with a value "true" since this would allow the
@@ -1643,4 +1647,9 @@
</td></tr><tr><td rowspan="1" colspan="1">20070912</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Implemented the resolution for issue
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5043">5043</a>. Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/357">357</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070913</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Implemented the resolution for issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4861">4861</a>. Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/353">353</a>
+ with the caveats and clarifications expressed in message
+ <a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2007Sep/0002.html">2007Sep-0002</a>.
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.117
retrieving revision 1.118
diff -u -d -r1.117 -r1.118
--- ws-policy-guidelines.xml 12 Sep 2007 21:11:21 -0000 1.117
+++ ws-policy-guidelines.xml 13 Sep 2007 21:06:27 -0000 1.118
@@ -748,12 +748,12 @@
<p> The Policy Framework provides two modes of authoring policy expressions:
compact and normal form. One of the mechanisms that the Policy Framework
provides to policy authors for purposes of writing compact policy
-expressions is the wsp:Optional attribute. Assertion Authors should allow
-for the use of the wsp:Optional attribute in the XML outline and/or schema
+ expressions is the <code>wsp:Optional</code> attribute. Assertion Authors should allow
+for the use of the <code>wsp:Optional</code> attribute in the XML outline and/or schema
definition of an assertion as this will allow policy expression authors to
compose compact policy expressions.</p>
<p role="practice" id="bp-assertion-xml-allow-optional">
- <quote>Allow use of wsp:Optional</quote>
+ <quote>Assertion Authors should allow use of wsp:Optional</quote>
<quote>An assertion's XML outline and/or schema definition should allow the use
of the wsp:Optional attribute so as to enable policy authors to compose
compact policy expressions.</quote>
@@ -780,7 +780,11 @@
</wsp:Policy></eg>
</example>
<p>
-If the assertion author had not provided for the wsp:Optional attribute to be included on the assertion, then policy expression authors would be forced to express the optionality of a behavior as two explicit policy alternatives, one with and one without that assertion when including assertions of that type in their policies.</p>
+If the assertion author had not provided for the <code>wsp:Optional</code> attribute
+to be included on the assertion, then policy expression authors would be forced to
+express the optionality of a behavior as two explicit policy alternatives,
+one with and one without that assertion when including assertions of that type in their
+policies.</p>
</div3>
@@ -2692,6 +2696,16 @@
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/357">357</loc>.
</td>
</tr>
+ <tr>
+ <td>20070913</td>
+ <td>TIB</td>
+ <td>Implemented the resolution for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4861">4861</loc>. Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/353">353</loc>
+ with the caveats and clarifications expressed in message
+ <loc href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2007Sep/0002.html">2007Sep-0002</loc>.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Thursday, 13 September 2007 21:06:33 UTC