- From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 17 May 2007 21:12:32 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv1788
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Editorial changes to get things ready to publish
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -d -r1.56 -r1.57
--- ws-policy-guidelines.html 16 May 2007 15:52:59 -0000 1.56
+++ ws-policy-guidelines.html 17 May 2007 21:12:30 -0000 1.57
@@ -210,7 +210,7 @@
the question.
</p></div><div class="div1">
<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Good Practice Statements</h2><p>The following good practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-specification-parts"><b>1. Parts of an Assertion Specification</b></a></p></li><li><p><a href="#bp-assertion-semantics"><b>2. Semantics of Policy Assertions</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics of an Assertion and its form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Starting to Build an Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Unique QNames</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>6. Clear Semantics</b></a></p></li><li><p><a href="#XMLOutline"><b>7. XML Outline</b></a></p></li><li><p><a href="#bp-assertions-and-message-semantics"><b>8. Assertions and Message Semantics</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>9. Duplication of Asertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>10. Use Parameters for Useful
- Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>11. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>12. Declare Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>13. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>14. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>15. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Assertion description should explicitly indicate that wsp:Optional is allowed.</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 mesage 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-WSDL-policy-subject"><b>21. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>27. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class"div1">
+ Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>11. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>12. Declare Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>13. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>14. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>15. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Assertion description should explicitly indicate that wsp:Optional is allowed.</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 mesage 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-WSDL-policy-subject"><b>21. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>27. Change of the Policy Subject Over Time</b></a></p></li></ul></div><dv class="div1">
<h2><a name="Assertions" id="Assertions"></a>3. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
@@ -941,7 +941,7 @@
should specify a WSDL policy subject – such as service, endpoint, operation and message.
</p></div><p>Assertion authors that wish to utilize WSDL policy subjects need to
understand how the assertions will be
- processed in intersection and merging and the implications of
+ processed in an intersection and merging, and the implications of
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
</p><p> For a given WSDL policy subject, there may be several
@@ -976,7 +976,7 @@
assertion is allowed to be associated with multiple policy
subjects as is possible with WSDL, then the assertion author has
the burden to describe the semantics of multiple instances of the
- same assertion attached to multiple policy subjects at the same
+ same assertion attached to different policy subjects at the same
time in order to avoid conflicting behavior.
</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Good
practice 23: Assertion attachment to multiple policy subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy
@@ -988,7 +988,7 @@
assertion authors should consider the following:</p><ul><li><p> Decompose the semantics with several assertions.</p></li><li><p> Rewrite a single assertion targeting a specific subject. </p></li></ul><p>
<table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">
The following paragraph is likely to change,
- as there is an open issue 4074 against this paragraph.
+ as there is an issue 4074, open against this paragraph.
</td></tr></table>
</p><p>The current set of subjects as mapped to the WSDL 1.1
elements, can also constrain the assertion constructs.
@@ -1012,15 +1012,15 @@
However, this approach only works if the policy subject is a true WSDL
construct other than some other protocol concept that is
layered over WSDL message exchanges. For example, as described previously
- the WS-RM Policy is a capability that governs a target endpoints
- capability to accept sequences that is beyond single message
- exchanges. Therefore, its semantics encompasses the cases when
+ the WS-RM Policy is a capability that governs a target endpoint's
+ capability to accept message sequences that are beyond single message
+ exchange. Therefore, its semantics encompass the cases when
message level policy subjects may be used as attachment but
- considers when sequences are present. In addition, when the
- policy assertions do not target wire-level behaviors but
+ also considers the case when sequences are present. In addition,
+ when the policy assertions do not target wire-level behaviors but
rather abstract requirements, this technique does not apply.
</p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Good
-practice 24: Preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
+practice 24: Specify preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
subject, an assertion author should specify a preferred attachment
point for the chosen policy subject.
</p></div><p>Assertion authors that utilize WSDL policy subjects need to
@@ -1642,4 +1642,6 @@
Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/252">252</a> and
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/255">255</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070516</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Editorial change to section 5.7 to place best practice after the associated
+ explanatory text and to fix grammar.
</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.71
retrieving revision 1.72
diff -u -d -r1.71 -r1.72
--- ws-policy-guidelines.xml 16 May 2007 15:52:59 -0000 1.71
+++ ws-policy-guidelines.xml 17 May 2007 21:12:30 -0000 1.72
@@ -1212,7 +1212,7 @@
<p>Assertion authors that wish to utilize WSDL policy subjects need to
understand how the assertions will be
- processed in intersection and merging and the implications of
+ processed in an intersection and merging, and the implications of
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <bibref ref="WS-Policy-Primer"/>
</p>
@@ -1256,7 +1256,7 @@
assertion is allowed to be associated with multiple policy
subjects as is possible with WSDL, then the assertion author has
the burden to describe the semantics of multiple instances of the
- same assertion attached to multiple policy subjects at the same
+ same assertion attached to different policy subjects at the same
time in order to avoid conflicting behavior.
</p>
@@ -1285,7 +1285,7 @@
<ednote>
<edtext>
The following paragraph is likely to change,
- as there is an open issue 4074 against this paragraph.
+ as there is an issue 4074, open against this paragraph.
</edtext>
</ednote>
</p>
@@ -1314,17 +1314,17 @@
However, this approach only works if the policy subject is a true WSDL
construct other than some other protocol concept that is
layered over WSDL message exchanges. For example, as described previously
- the WS-RM Policy is a capability that governs a target endpoints
- capability to accept sequences that is beyond single message
- exchanges. Therefore, its semantics encompasses the cases when
+ the WS-RM Policy is a capability that governs a target endpoint's
+ capability to accept message sequences that are beyond single message
+ exchange. Therefore, its semantics encompass the cases when
message level policy subjects may be used as attachment but
- considers when sequences are present. In addition, when the
- policy assertions do not target wire-level behaviors but
+ also considers the case when sequences are present. In addition,
+ when the policy assertions do not target wire-level behaviors but
rather abstract requirements, this technique does not apply.
</p>
<p role="practice" id="bp-WSDL-preferred-attachment-point">
- <quote>Preferred attachment point for an Assertion</quote>
+ <quote>Specify preferred attachment point for an Assertion</quote>
<quote>If an assertion can be attached at multiple points within a policy
subject, an assertion author should specify a preferred attachment
point for the chosen policy subject.
@@ -2448,6 +2448,13 @@
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/252">252</loc> and
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/255">255</loc>.
</td>
+ </tr>
+ <tr>
+ <td>20070516</td>
+ <td>PY</td>
+ <td>Editorial change to section 5.7 to place best practice after the associated
+ explanatory text and to fix grammar.
+ </td>
</tr>
</tbody>
</table>
Received on Thursday, 17 May 2007 21:12:36 UTC