- From: Frederick Hirsch via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 12 Sep 2007 21:11:23 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv10378
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Implemented the resolution for issue 5043. Editors' action 357.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.100
retrieving revision 1.101
diff -u -d -r1.100 -r1.101
--- ws-policy-guidelines.html 12 Sep 2007 19:50:49 -0000 1.100
+++ ws-policy-guidelines.html 12 Sep 2007 21:11:21 -0000 1.101
@@ -162,8 +162,8 @@
<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
- 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 Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>25. Choose the Most Granular 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 Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>27. Specify Preferred 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
+ 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
subject</b></a></p></li></ul></div><div 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
@@ -283,7 +283,7 @@
policy. This selected alternative is then used to govern the creation of a message
to send to the subject to which the policy alternative was
attached. The WS-Policy Attachment specification defines a
- set of attachment models for use with common web service
+ set of attachment mechanisms for use with common web service
subjects: WSDL definitions [<cite><a href="#WSDL11">WSDL 1.1</a></cite>, <cite><a href="#WSDL20">WSDL 2.0 Core Language</a></cite>], and UDDI directory entries [<cite><a href="#UDDIAPI20">UDDI API 2.0</a></cite>, <cite><a href="#UDDIDataStructure20">UDDI Data Structure 2.0</a></cite>,
<cite><a href="#UDDI30">UDDI 3.0</a></cite>].
</p><p>
@@ -351,7 +351,7 @@
<ul><li><p>The definition of the assertion's semantic
(See best practice <a href="#AssertionDefinitions"><b>8. Specify Semantics Clearly</b></a>).</p></li><li><p>The specification of the set of valid policy subjects to which an
assertion may be attached
- (See best practice <a href="#bp-WSDL-policy-subject"><b>24. Specify Policy Subject(s)</b></a>).</p></li><li><p>The scope of the assertion in the context of a particular policy
+ (See best practice <a href="#bp-WSDL-policy-subject"><b>24. Specify WSDL Policy Subject(s)</b></a>).</p></li><li><p>The scope of the assertion in the context of a particular policy
subject (See best practices in Section <a href="#levels-of-abstraction"><b>5.7 Considerations for Policy Attachment</b></a>).</p></li><li><p>Any composition considerations if the assertion is used with
other assertions in a context
(See best practice <a href="#bp-specify-composition"><b>29. Specify Composition with Related Assertions</b></a>).</p></li></ul>
@@ -913,7 +913,7 @@
unknown) attachment mechanisms in mind.
</p><div class="boxedtext"><p><a name="bp-leverage-defined-attachment-mechanisms" id="bp-leverage-defined-attachment-mechanisms"></a><span class="practicelab">Best
Practice 21: Leverage Defined Attachment Mechanisms</span></p><p class="practice">
- Assertion Authors should leverage defined attachment models when
+ Assertion Authors should leverage defined attachment mechanisms when
possible to extend the deployment of their policy assertions and ensure
that there are no additional semantics implied by their
assertions.</p></div><p>Assertion authors are also encouraged to use the policy subjects defined by the policy attachments
@@ -934,7 +934,7 @@
Practice 23: Identify Policy Subjects</span></p><p class="practice">
Assertion
Authors should review the policy subjects defined in
- WS-PolicyAttachments and identify existing policy subjects when possible
+ Web Services Policy 1.5 - Attachment and identify existing policy subjects when possible
to facilitate the deployment of their policy assertions and include this
information in the definition of the assertions.</p></div><p>
An example of this is
@@ -948,7 +948,7 @@
assertion". This is illustrative of how the domain assertion author can
specify additional constraints and assumptions for attachment and
engagement of behavior in addition to the capabilities specified in
- WS-PolicyAttachment [<cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>]. Such
+ Web Services Policy 1.5 - Attachment [<cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>]. Such
additional constraints must be clearly specified by the assertion
authors.
</p></div><div class="div3">
@@ -962,8 +962,8 @@
subject is the service policy subject. </p></li><li><p>If the behavior applies to any message exchange
made using an endpoint then the subject is the endpoint policy subject. </p></li><li><p>If the behavior applies to any message exchange
defined by an operation then the subject is the operation policy subject. </p></li><li><p>If the behavior applies to an input message then
- the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Best
-Practice 24: Specify Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant policy subjects with which
+ the subject is the message policy subject - similarly for output and fault message WSDL policy subjects.</p></li></ul><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Best
+Practice 24: Specify WSDL Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant WSDL policy subjects with which
the assertion may be associated. For instance, if a policy assertion is to be used with
WSDL, the assertion description should specify a WSDL policy subject - such as service,
endpoint, operation and message.
@@ -986,36 +986,36 @@
</p><p> In using WSDL attachment, it should be noted that the
service policy subject is a collection of endpoint policy
subjects. The endpoint policy subject is a collection of
- operation policy subjects and so on. As a result, the WSDL
+ operation WSDL policy subjects and so on. As a result, the WSDL
policy subjects compose naturally. It is quite tempting to
associate the identified behavior to a broader policy subject
than to a fine granular policy subject. For instance, it is
convenient to attach a supporting token assertion (defined by
the Web Services Security Policy specification) to an endpoint
policy subject instead of a message policy subject. However such
- policy attachments to policy subjects of broader scope and granularity
+ policy attachments to WSDL policy subjects of broader scope and granularity
should be done only after careful evaluation.
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best
-Practice 25: Choose the Most Granular Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular policy subject
+Practice 25: Choose the Most Granular WSDL Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular WSDL policy subject
to which the behavior represented by a policy assertion applies.
</p></div><p>
For authoring convenience, Assertion Authors may allow the
- association of an assertion to multiple policy subjects within the same context of
+ association of an assertion to multiple WSDL policy subjects within the same context of
use (e.g in the same WSDL description). If an assertion is allowed to be
- associated with multiple policy subjects as is possible with WSDL, then
+ associated with multiple WSDL policy subjects as is possible with WSDL, then
the Assertion Authors have the burden to describe the rules
when multiple instances of the same assertion are attached to different
- policy subjects in order to avoid non-interoperable behavior.
+ WSDL policy subjects in order to avoid non-interoperable behavior.
</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Best
Practice 26: Define Rules for Attachment of an Assertion
- type to Multiple Policy Subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy subjects,
+ type to Multiple WSDL policy subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple WSDL policy subjects,
the assertion author should describe the rules for multiple
- instances of the same assertion attached to multiple policy subjects in
+ instances of the same assertion attached to multiple WSDL policy subjects in
the same context.
</p></div><p>
To give one example, section 2.3 of the
Web Services Reliable Messaging Policy Assertion specification
- [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>] gives rules on which Policy Subjects may be associated with the RM
+ [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>] gives rules on which WSDL policy subjects may be associated with the RM
Policy assertion, and which WSDL 1.1 elements may have RM Policy assertions attached.
</p><p>If the capability may imply
different semantics with respect to attachment points, the
@@ -1030,12 +1030,12 @@
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
+ message level WSDL policy subjects may be used as attachment 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">Best
-Practice 27: Specify Preferred Attachment Point</span></p><p class="practice">If an assertion can be attached at multiple attachment points
+Practice 27: Specify Preferred WSDL Attachment Point</span></p><p class="practice">If an assertion can be attached at multiple attachment points
within a policy subject, Assertion Authors should specify a
preferred attachment point for the chosen policy subject.
</p></div><p>Assertion Authors that utilize WSDL policy subjects need to
@@ -1123,7 +1123,7 @@
<sp:Wss11>…</sp:Wss11>
</Policy></pre></div></div></div><div class="div2">
<h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>6.3 Supporting New Policy Subjects</h3><p>
- The best practice <a href="#bp-WSDL-policy-subject"><b>24. Specify Policy Subject(s)</b></a> specifies that policy authors should
+ The best practice <a href="#bp-WSDL-policy-subject"><b>24. Specify WSDL Policy Subject(s)</b></a> specifies that policy authors should
define the set of policy subjects to which policy assertions can be
attached. Over time, new policy subjects may need to be defined. When
this occurs, policy Assertion Authors may update the list of policy
@@ -1608,4 +1608,7 @@
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5041">5041</a>.
Editors' action:
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/347">356</a>.
+ </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></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.116
retrieving revision 1.117
diff -u -d -r1.116 -r1.117
--- ws-policy-guidelines.xml 12 Sep 2007 19:50:49 -0000 1.116
+++ ws-policy-guidelines.xml 12 Sep 2007 21:11:21 -0000 1.117
@@ -337,7 +337,7 @@
policy. This selected alternative is then used to govern the creation of a message
to send to the subject to which the policy alternative was
attached. The WS-Policy Attachment specification defines a
- set of attachment models for use with common web service
+ set of attachment mechanisms for use with common web service
subjects: WSDL definitions [<bibref ref="WSDL11" />, <bibref
ref="WSDL20" />], and UDDI directory entries [<bibref
ref="UDDIAPI20" />, <bibref ref="UDDIDataStructure20" />,
@@ -1233,7 +1233,7 @@
<p role="practice" id="bp-leverage-defined-attachment-mechanisms">
<quote>Leverage Defined Attachment Mechanisms</quote><quote>
- Assertion Authors should leverage defined attachment models when
+ Assertion Authors should leverage defined attachment mechanisms when
possible to extend the deployment of their policy assertions and ensure
that there are no additional semantics implied by their
assertions.</quote> </p>
@@ -1259,7 +1259,7 @@
<quote>Identify Policy Subjects</quote><quote>
Assertion
Authors should review the policy subjects defined in
- WS-PolicyAttachments and identify existing policy subjects when possible
+ Web Services Policy 1.5 - Attachment and identify existing policy subjects when possible
to facilitate the deployment of their policy assertions and include this
information in the definition of the assertions.</quote> </p>
<p>
@@ -1275,7 +1275,7 @@
assertion". This is illustrative of how the domain assertion author can
specify additional constraints and assumptions for attachment and
engagement of behavior in addition to the capabilities specified in
- WS-PolicyAttachment [<bibref ref="WS-PolicyAttachment "/>]. Such
+ Web Services Policy 1.5 - Attachment [<bibref ref="WS-PolicyAttachment "/>]. Such
additional constraints must be clearly specified by the assertion
authors.
</p>
@@ -1306,13 +1306,13 @@
</item>
<item>
<p>If the behavior applies to an input message then
- the subject is the message policy subject - similarly for output and fault message policy subjects.</p>
+ the subject is the message policy subject - similarly for output and fault message WSDL policy subjects.</p>
</item>
</ulist>
<p role="practice" id="bp-WSDL-policy-subject">
- <quote>Specify Policy Subject(s)</quote>
- <quote>Assertion Authors should specify the set of relevant policy subjects with which
+ <quote>Specify WSDL Policy Subject(s)</quote>
+ <quote>Assertion Authors should specify the set of relevant WSDL policy subjects with which
the assertion may be associated. For instance, if a policy assertion is to be used with
WSDL, the assertion description should specify a WSDL policy subject - such as service,
endpoint, operation and message.
@@ -1341,45 +1341,45 @@
<p> In using WSDL attachment, it should be noted that the
service policy subject is a collection of endpoint policy
subjects. The endpoint policy subject is a collection of
- operation policy subjects and so on. As a result, the WSDL
+ operation WSDL policy subjects and so on. As a result, the WSDL
policy subjects compose naturally. It is quite tempting to
associate the identified behavior to a broader policy subject
than to a fine granular policy subject. For instance, it is
convenient to attach a supporting token assertion (defined by
the Web Services Security Policy specification) to an endpoint
policy subject instead of a message policy subject. However such
- policy attachments to policy subjects of broader scope and granularity
+ policy attachments to WSDL policy subjects of broader scope and granularity
should be done only after careful evaluation.
</p>
<p role="practice" id="bp-WSDL-policy-subject-Granularity">
- <quote>Choose the Most Granular Policy Subject</quote>
- <quote>Assertion Authors should choose the most granular policy subject
+ <quote>Choose the Most Granular WSDL Policy Subject</quote>
+ <quote>Assertion Authors should choose the most granular WSDL policy subject
to which the behavior represented by a policy assertion applies.
</quote>
</p>
<p>
For authoring convenience, Assertion Authors may allow the
- association of an assertion to multiple policy subjects within the same context of
+ association of an assertion to multiple WSDL policy subjects within the same context of
use (e.g in the same WSDL description). If an assertion is allowed to be
- associated with multiple policy subjects as is possible with WSDL, then
+ associated with multiple WSDL policy subjects as is possible with WSDL, then
the Assertion Authors have the burden to describe the rules
when multiple instances of the same assertion are attached to different
- policy subjects in order to avoid non-interoperable behavior.
+ WSDL policy subjects in order to avoid non-interoperable behavior.
</p>
<p role="practice" id="bp-WSDL-multiple-policy-subjects">
<quote> Define Rules for Attachment of an Assertion
- type to Multiple Policy Subjects</quote>
- <quote>If an assertion is allowed to be associated with multiple policy subjects,
+ type to Multiple WSDL policy subjects</quote>
+ <quote>If an assertion is allowed to be associated with multiple WSDL policy subjects,
the assertion author should describe the rules for multiple
- instances of the same assertion attached to multiple policy subjects in
+ instances of the same assertion attached to multiple WSDL policy subjects in
the same context.
</quote>
</p>
<p>
To give one example, section 2.3 of the
Web Services Reliable Messaging Policy Assertion specification
- [<bibref ref="WS-RM-Policy "/>] gives rules on which Policy Subjects may be associated with the RM
+ [<bibref ref="WS-RM-Policy "/>] gives rules on which WSDL policy subjects may be associated with the RM
Policy assertion, and which WSDL 1.1 elements may have RM Policy assertions attached.
</p>
@@ -1407,14 +1407,14 @@
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
+ message level WSDL policy subjects may be used as attachment 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>Specify Preferred Attachment Point</quote>
+ <quote>Specify Preferred WSDL Attachment Point</quote>
<quote>If an assertion can be attached at multiple attachment points
within a policy subject, Assertion Authors should specify a
preferred attachment point for the chosen policy subject.
@@ -2684,6 +2684,14 @@
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/347">356</loc>.
</td>
</tr>
+ <tr>
+ <td>20070912</td>
+ <td>FJH</td>
+ <td>Implemented the resolution for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5043">5043</loc>. Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/357">357</loc>.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 12 September 2007 21:11:32 UTC