W3C home > Mailing lists > Public > public-ws-policy-eds@w3.org > May 2007

2006/ws/policy ws-policy-guidelines.html,1.56,1.57 ws-policy-guidelines.xml,1.71,1.72

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
Message-Id: <E1HonGy-0000Tc-Ks@lionel-hutz.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%">&nbsp;</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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:21:03 GMT