- From: David Orchard via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 29 Mar 2007 22:25:45 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv2522
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Changed all <p>Best Practice: to <p role="practice">
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -d -r1.37 -r1.38
--- ws-policy-guidelines.html 22 Mar 2007 05:42:15 -0000 1.37
+++ ws-policy-guidelines.html 29 Mar 2007 22:25:43 -0000 1.38
@@ -59,7 +59,7 @@
<h2><a name="w3c-doctype" id="w3c-doctype"></a>Editors' copy $Date$ @@ @@@@ @@@@</h2><dl><dt>This version:</dt><dd>
<a href="ws-policy-guidelines.html">ws-policy-guidelines.html</a>
</dd><dt>Latest version:</dt><dd><a href="http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;charset=utf-8">http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;charset=utf-8</a></dd><dt>Previous version:</dt><dd>
- <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061221">http://www.w3.org/TR/2006/WD-ws-policy-primer-20061221</a>
+ <a href="http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221">http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221</a>
</dd><dt>Editors:</dt><dd>Asir S Vedamuthu, Microsoft Corporation</dd><dd>David Orchard, BEA Systems, Inc.</dd><dd>Frederick Hirsch, Nokia</dd><dd>Maryann Hondo, IBM Corporation</dd><dd>Prasad Yendluri, webMethods, Inc.</dd><dd>Toufic Boubez, Layer 7 Technologies</dd><dd>Ümit Yalçinalp, SAP AG.</dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © @@@@ <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark/a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>
<em>Web Services Policy 1.5 - Guidelines for Policy Assertion Authors</em> is intended to provide guidance for assertion
@@ -350,8 +350,8 @@
attachment mechanism. Independence from a specific attachment mechanism
allows policy tools to choose the most appropriate mechanism to attach a
policy without having to analyze the contents of the policy.
- </p><p>
- Best practice: Assertion Authors should include the following items in an
+ </p><p class="practice">
+ Assertion Authors should include the following items in an
assertion specification:
</p><p>
<ul><li><p><em>The definition of the assertion's semantic.</em> </p></li><li><p><em>The specification of the set of valid policy subjects to which an
@@ -365,8 +365,8 @@
affect the composition. For example, if an assertion applies to the SOAP
protocol, it would be necessary to consider how its presence must interact
with other policy assertions that are defined for security.</p></li></ul>
- </p><p>
- Best practice: The semantics a policy assertion should not depend on the
+ </p><p class="practice">
+ The semantics a policy assertion should not depend on the
attachment mechanism used.
</p></div><div class="div2">
<h3><a name="compact-full" id="compact-full"></a>4.2 Authoring Styles </h3><p>WS-Policy supports two different authoring styles, compact form and
@@ -436,7 +436,7 @@
policy expression would be when it is processed. As a result, the
description for a policy assertion should not depend on the style used
to author a policy expression that contains the assertion.
- </p><p>Best practice: the semantics of an assertion should be independent of
+ </p><p class="practice">The semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
assertion.</p></div><div class="div2">
<h3><a name="new-guidelines-domains" id="new-guidelines-domains"></a>4.3 Considerations when Modeling New Assertions</h3><p>When creating a new policy domain, it is important to
@@ -468,7 +468,7 @@
good to start with a simple working policy assertion that allows extensibility. As your
design work progresses, you may add more parameters or nested policy assertions to meet
your interoperability needs.
- </p><p>Best practice: Start with a simple working assertion that allows extensibility.
+ </p><p class="practice">Start with a simple working assertion that allows extensibility.
</p></div><div class="div3">
<h4><a name="QName_and_XML_Information_Set_representation" id="QName_and_XML_Information_Set_representation"></a>4.3.2 QName and XML Information Set representation</h4><p>Web Services Policy language allows Assertion Authors to invent
their own XML dialects to represent policy assertions. The policy language relies only
@@ -479,7 +479,7 @@
versus attributes apply.</p><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
document). If the assertion has a nested policy expression then the assertion XML
outline can enumerate the nested assertions that are allowed.
- </p><p>Best practice: Use a unique QName to identify the behavior and provide an XML outline
+ </p><p class="practice">Use a unique QName to identify the behavior and provide an XML outline
(plus an XML schema document) to specify the syntax of an assertion.
</p></div><div class="div3">
<h4><a name="self-describing" id="self-describing"></a>4.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and
@@ -520,7 +520,7 @@
dedicated endpoint may be allocated to ensure the engagement of a
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
- </p><p>Best practice: Policy assertions should not be used to express the semantics of a message.
+ </p><p class="practice">Policy assertions should not be used to express the semantics of a message.
</p></div><div class="div3">
<h4><a name="single-domains" id="single-domains"></a>4.3.4 Single Domains</h4><p>When considering the creation of a
new domain of policy assertions, it is important to identify
@@ -545,7 +545,7 @@
</p><p>A review by a broad community is
the best way to ensure that the granularity of a set of domain
assertions is appropriate.
- </p><p>Best practice: Avoid duplication of assertions.
+ </p><p class="practice">Avoid duplication of assertions.
</p></div></div><div class="div2">
<h3><a name="comparison" id="comparison"></a>4.4 Comparison of Nested and Parameterized Assertions</h3><p>There are two different ways to provide additional information in an
assertion beyond its type. We cover these two cases below followed by a
@@ -573,7 +573,7 @@
<sp:Body/>
<sp:Header/>
</sp:SignedParts>
-</wsp:Policy></pre></div></div><p>Best practice: Define policy assertion parameters for
+</wsp:Policy></pre></div></div><p class="practice">Define policy assertion parameters for
specifying useful pieces of information necessary for engaging
the behavior described by an assertion but not relevant to policy
intersection.
@@ -689,7 +689,7 @@
compatible policy alternative then the assertions in a nested policy expression play a
first class role in the outcome. There is one caveat to watch out for: policy assertions
with deeply nested policy can greatly increase the complexity of a policy and should be
- avoided when they are not needed.</p><p>Best practice: If the assertion
+ avoided when they are not needed.</p><p class="practice">If the assertion
authors want to delegate the processing to the framework,
utilizing nesting should be considered. Otherwise, domain
specific comparison algorithms may need to be devised and be
@@ -781,7 +781,7 @@
approach that is currently taken by WS-RM Policy [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>] is to introduce both message and endpoint
policy subjects for one of its assertions and require the
use of endpoint policy subject when message policy subject is used via attachment.
- </p></li></ul><p>Best Practice: Optional Assertion Authors should explicitly state
+ </p></li></ul><p class="practice">Optional Assertion Authors should explicitly state
how the behavior that is enabled by the assertion would be
engaged when they are designing their assertion, whether by
specific headers or some other means. See also <a href="#self-describing"><b>4.3.3 Self Describing Messages </b></a>.
@@ -905,7 +905,7 @@
policy assertions.</p><div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><i><span>Example 5-2. </span>Message-level Security and WSS: SOAP Message Security 1.1</i></p><div class="exampleInner"><pre><Policy>
<sp:Wss11>…</sp:Wss11>
-</Policy></pre></div></div><p>Best practice: use independent assertions for modeling multiple equivalent
+</Policy></pre></div></div><p class="practice">Use independent assertions for modeling multiple equivalent
behaviors.</p></div><div class="div2">
<h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>5.3 Supporting New Policy Subjects</h3><p>
<a href="#Assertions">Section 2</a> identifies that it is a best practice for policy authors to
@@ -923,8 +923,8 @@
provided that endpoint policy subject is also retained in its design. When
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
- </p><p>Best Practice: An assertion description should specify a policy
- subject.</p><p>Best Practice: If the policy subjects change over time,
+ </p><p class="practice">An assertion description should specify a policy
+ subject.</p><p class="practice">If the policy subjects change over time,
the assertion description should also be versioned to reflect this
change.
</p></div></div><div class="div1">
@@ -1328,7 +1328,7 @@
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/106">106</a>
and bug http://www.w3.org/Bugs/Public/show_bug.cgi?id=3983
</td></tr><tr><td rowspan="1" colspan="1">20070104</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Resolution of Issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3982">3982</a>
- Based on <a href="http://www.w3.org/2006/12/06-ws-policy-irc#T18-55-00)">Minutes for resolution</a>, Minor formatting for consistent use of the term "Assertion Author"
+ Based on <a href="http://www.w3.org/2006/12/06-ws-policy-irc#T18-55-00">Minutes for resolution</a>, Minor formatting for consistent use of the term "Assertion Author"
</td></tr><tr><td rowspan="1" colspan="1">20070104</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Resolution of Issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3980">3980</a>
</td></tr><tr><td rowspan="1" colspan="1">20070108</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of
the Document</b></a>.
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -d -r1.51 -r1.52
--- ws-policy-guidelines.xml 29 Mar 2007 07:45:45 -0000 1.51
+++ ws-policy-guidelines.xml 29 Mar 2007 22:25:43 -0000 1.52
@@ -444,8 +444,8 @@
attachment mechanism. Independence from a specific attachment mechanism
allows policy tools to choose the most appropriate mechanism to attach a
policy without having to analyze the contents of the policy.
- </p><p>
- Best practice: Assertion Authors should include the following items in an
+ </p><p role="practice">
+ Assertion Authors should include the following items in an
assertion specification:
</p><p>
<ulist>
@@ -465,8 +465,8 @@
with other policy assertions that are defined for security.</p></item>
</ulist>
</p>
- <p>
- Best practice: The semantics a policy assertion should not depend on the
+ <p role="practice">
+ The semantics a policy assertion should not depend on the
attachment mechanism used.
</p>
</div2>
@@ -554,7 +554,7 @@
to author a policy expression that contains the assertion.
</p>
- <p>Best practice: the semantics of an assertion should be independent of
+ <p role="practice">The semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
assertion.</p>
</div2>
@@ -599,7 +599,7 @@
design work progresses, you may add more parameters or nested policy assertions to meet
your interoperability needs.
</p>
- <p>Best practice: Start with a simple working assertion that allows extensibility.
+ <p role="practice">Start with a simple working assertion that allows extensibility.
</p>
</div3>
<div3 id="QName_and_XML_Information_Set_representation">
@@ -615,7 +615,7 @@
document). If the assertion has a nested policy expression then the assertion XML
outline can enumerate the nested assertions that are allowed.
</p>
- <p>Best practice: Use a unique QName to identify the behavior and provide an XML outline
+ <p role="practice">Use a unique QName to identify the behavior and provide an XML outline
(plus an XML schema document) to specify the syntax of an assertion.
</p>
</div3>
@@ -667,7 +667,7 @@
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
</p>
- <p>Best practice: Policy assertions should not be used to express the semantics of a message.
+ <p role="practice">Policy assertions should not be used to express the semantics of a message.
</p>
</div3>
<div3 id="single-domains">
@@ -698,7 +698,7 @@
the best way to ensure that the granularity of a set of domain
assertions is appropriate.
</p>
- <p>Best practice: Avoid duplication of assertions.
+ <p role="practice">Avoid duplication of assertions.
</p>
</div3>
</div2>
@@ -739,7 +739,7 @@
</sp:SignedParts>
</wsp:Policy></eg>
</example>
- <p>Best practice: Define policy assertion parameters for
+ <p role="practice">Define policy assertion parameters for
specifying useful pieces of information necessary for engaging
the behavior described by an assertion but not relevant to policy
intersection.
@@ -898,7 +898,7 @@
first class role in the outcome. There is one caveat to watch out for: policy assertions
with deeply nested policy can greatly increase the complexity of a policy and should be
avoided when they are not needed.</p>
- <p>Best practice: If the assertion
+ <p role="practice">If the assertion
authors want to delegate the processing to the framework,
utilizing nesting should be considered. Otherwise, domain
specific comparison algorithms may need to be devised and be
@@ -1021,7 +1021,7 @@
</p>
</item>
</ulist>
- <p>Best Practice: Optional Assertion Authors should explicitly state
+ <p role="practice">Optional Assertion Authors should explicitly state
how the behavior that is enabled by the assertion would be
engaged when they are designing their assertion, whether by
specific headers or some other means. See also <specref ref="self-describing"/>.
@@ -1223,7 +1223,7 @@
<eg xml:space="preserve"><Policy>
<sp:Wss11>…</sp:Wss11>
</Policy></eg></example>
- <p>Best practice: use independent assertions for modeling multiple equivalent
+ <p role="practice">Use independent assertions for modeling multiple equivalent
behaviors.</p>
</div2>
<div2 id="supporting-new-policy-subjects">
@@ -1246,9 +1246,9 @@
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
</p>
- <p>Best Practice: An assertion description should specify a policy
+ <p role="practice">An assertion description should specify a policy
subject.</p>
- <p>Best Practice: If the policy subjects change over time,
+ <p role="practice">If the policy subjects change over time,
the assertion description should also be versioned to reflect this
change.
</p>
Received on Thursday, 29 March 2007 22:25:55 UTC