- From: Frederick Hirsch via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 24 Apr 2007 01:14:38 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv17254
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Updated 5.5 Designating Optional Behaviors for issue 3989. Added informative reference for MTOMPolicy. Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -d -r1.41 -r1.42
--- ws-policy-guidelines.html 16 Apr 2007 19:27:47 -0000 1.41
+++ ws-policy-guidelines.html 24 Apr 2007 01:14:36 -0000 1.42
@@ -119,7 +119,7 @@
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc">1. <a href="#introduction">Introduction</a><br>
2. <a href="#best-practices-list">List of Best Practices Statements</a><br>
3. <a href="#Assertions">What is an Assertion? </a><br>
-4. <a href="#d3e228">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e236">Who is involved in authoring Assertions? </a><br>
4.1 <a href="#roles"> Roles and Responsibilities </a><br>
4.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
4.1.2 <a href="#consumers">Consumers</a><br>
@@ -137,8 +137,9 @@
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
5.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br>
5.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.5.1 <a href="#d3e642">Optional behavior in Compact authoring</a><br>
- 5.5.2 <a href="#d3e650">Optional behavior at runtime</a><br>
+ 5.5.1 <a href="#d3e650">Optional behavior in Compact authoring</a><br>
+ 5.5.2 <a href="#d3e658">Optional behavior at runtime</a><br>
+ 5.5.2.1 <a href="#d3e703">Example</a><br>
5.6 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>
5.7 <a href="#interrelated-domains">Interrelated domains</a><br>
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -206,7 +207,7 @@
the Socratic style of beginning with a question, and then answering
the question.
</p></div><div class="div1">
-<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practices Statements</h2><p>TBD:</p><ol class="enumar"><li><p><a href="#bp-assertion-specification-parts">Parts of an Assertion Specification</a></p></li><li><p><a href="#bp-assertion-semantics">Semantics of Policy Assertions</a></p></li><li><p><a href="#bp-semantics-and-form">Semantics of an Assertion and its form</a></p></li><li><p><a href="#bp-assertion-start">Starting to Build an Assertion</a></p></li><li><p><a href="#bp-unique-qnames">Unique QNames</a></p></li><li><p><a href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</a></p></li><li><p><a href="#bp-assertion-duplication">Duplication of Assertions</a></p></li><li><p><a href="#bp-assertion-definition">Definition of Policy Assertions</a></p></li><li><p><a href="#bp-nesting">Nesting of Assertions</a></p></li><li><p><a href="#bp-optional-assertions">Optional Assertions</a></p></li><li><p><a href="#bp-independent-assertions">Independent Assertions</a>/p></li><li><p><a href="#bp-policy-subject-change">Change of the Policy Subject Over Time</a></p></li></ol></div><div class="div1">
+<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practices Statements</h2><p>TBD:</p><ol class="enumar"><li><p><a href="#bp-assertion-specification-parts">Parts of an Assertion Specification</a></p></li><li><p><a href="#bp-assertion-semantics">Semantics of Policy Assertions</a></p></li><li><p><a href="#bp-semantics-and-form">Semantics of an Assertion and its form</a></p></li><li><p><a href="#bp-assertion-start">Starting to Build an Assertion</a></p></li><li><p><a href="#bp-unique-qnames">Unique QNames</a></p></li><li><p><a href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</a></p></li><li><p><a href="#bp-assertion-duplication">Duplication of Assertions</a></p></li><li><p><a href="#bp-assertion-definition">Definition of Policy Assertions</a></p></li><li><p><a href="#bp-nesting">Nesting of Assertions</a></p></li><li><p><a href="#bp-limit-optional-assertions">Limit use of Optional Assertions</a></p></li><li><p><a href="#bp-entire-mep-for-optional">Considr entire message exchange pattern when specifying Assertions that may be optional</a></p></li><li><p><a href="#bp-indicate-optional-assertion-use">Indicate use of an Optional Assertion</a></p></li><li><p><a href="#bp-independent-assertions">Independent Assertions</a></p></li><li><p><a href="#bp-policy-subject-change">Change of the Policy Subject Over Time</a></p></li></ol></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
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
@@ -265,7 +266,7 @@
best practices will be an assertion specification that describes
a contract for the consumers and providers of the capabilities and constraints of the domain.
</p></div><div class="div1">
-<h2><a name="d3e228" id="d3e228"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e236" id="d3e236"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
express their own domain knowledge, it is necessary to provide basic
functionality that all domains could exploit and then allow
points of extension where authors of the various WS-Policy
@@ -746,95 +747,102 @@
delegated to the specific domain handlers that are not visible
to the WS-Policy framework.</p></div></div></div><div class="div2">
<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.5 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e642" id="d3e642"></a>5.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors which may be engaged by a consumer. When using the
- compact authoring form for assertions, behaviors are marked by
- using <code>wsp:Optional</code> attribute that has a value,
- "true". During the process of normalization, the runtime
- behavior is indicated by two policy alternatives, one with and
- one without the assertion. In a consumer/provider
- scenario, the choice of engaging the runtime behavior is upon
- the consumer although the provider is capable of engaging the
- runtime behavior. In order to simplify reference to such
- assertions, we just use the term optional assertions in this section.
- </p></div><div class="div3">
-<h4><a name="d3e650" id="d3e650"></a>5.5.2 Optional behavior at runtime</h4><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an
- example that proposes the use of <cite><a href="#MTOM">MTOM</a></cite> as an
- optional behavior that can be engaged by a consumer. The
- primer proposes that an assertion that identifies the use of
- MIME Multipart/Related serialization (see <cite><a href="#MTOM">MTOM</a></cite>,
- <cite><a href="#XOP">XOP</a></cite> for messages to enable a Policy-aware
- clients to recognize the policy assertion and if they select
- an alternative with this assertion, they engage Optimized MIME
- Serialization for messages. </p><p>The semantics of this assertion declare that the behavior
- is reflected in messages: they use an optimized wire format
- (MIME Multipart/Related serialization). Note that in order for
- an optional behavior to be engaged, the wire message that
- would utilize the specific assertion must be self
- describing. For example, an inbound message to a web service
- that asserts MTOM, must evaluate, the protocol format of the
- message to determine whether the incoming message adheres to
- the Optimized MIME Serialization. By examining the message,
- the provider can determine whether the policy alternate that
- contains the MTOM assertion is being selected.</p><p>Assertion Authors should be aware that optional behaviors,
- like utilizing optional support for Optimized MIME
- Serialization require some care considering the scoping of the assertion that is applicable. </p><ul><li><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 presence of two
- alternatives due to normalization enables a consumer to
- choose the alternative that does not contain the assertion,
- and thus making the behavior not being engaged in an interaction.
- </p></li><li><p>As demonstrated in the MIME optimization behavior, behaviors must be engaged
- with respect to messages that are targeted to the provider
- so that the provider can determine that the optional
- behavior is engaged. In other words, the requirement of self
- describing nature of messages [<a href="#self-describing"><b>5.3.3 Self Describing Messages </b></a>] in order to engage behaviors must
- not be forgotten with regard to the client's ability to
- detect and select the alternative if it is to participate in the exchange.
- </p></li><li><p> The target scope of an optional assertion is an important factor for
- Assertion Authors to consider as it determines the
- <em>granularity</em> where the behavior is optionally
- engaged. For example, if the assertion is targeted for an
- endpoint policy subject, it is expected to govern all the
- messages that are indicated by the specific endpoint when
- optional behavior is <em> engaged </em>. Since the
- behavior would be applicable to policy subject that is
- designated, it is important for the Assertion Authors
- to choose the appropriate level of granularity for optional
- behaviors, to consider whether a specific message or all messages, etc. are targeted.
- </p></li><li><p> Attaching optional assertions to outbound-messages using message policy subject
- require some care. An explicit, out of band mechanism may be necessary to enable a client to indicate that
- the optional behavior is engaged. Currently such a mechanism is outside the scope of WS-Policy Framework.
- </p></li><li><p>When optional behaviors are indicated by attaching assertions with only
- one side of an interaction, such as an inbound message of
- a request-response, the engagement of the rest of the
- interaction will be <em>undefined</em>. For example,
- if a request-response interaction only specified MTOM
- optimization for an inbound message, it would not be clear
- whether the outbound message from the provider could also
- utilize the behavior. Therefore, the Assertion Authors are
- encouraged to consider how the attachment on a message
- policy subject on a response message should be treated
- when optional behaviors are specified for message
- exchanges within a request response for response messages,
- using message policy subject. Leaving the semantics
- not specified or incompletely specified may result in providers making assumptions
- (i.e. if the incoming message utilized the optimization,
- the response will be returned utilizing the MTOM
- serialization). Similarly, if engagement of a behavior is
- only specified for an outbound message, the
- Assertion Authors should consider describing the
- semantics if the incoming messages also utilized the
- behavior. This is especially important if the assertion is
- applicable to more than one specific policy subject. One
- 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><div class="boxedtext"><p><a name="bp-optional-assertions" id="bp-optional-assertions"></a><span class="practicelab">Good
-practice 10: Optional Assertions</span></p><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 .</p></div></div></div><div class="div2">
+<h4><a name="d3e650" id="d3e650"></a>5.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
+ compact authoring form for assertions, such behaviors are marked by
+ using <code>wsp:Optional</code> attribute with a value of
+ "true". (In order to simplify reference to such assertions,
+ we just use the phrase “optional assertions” in this section.)
+ During the process of normalization the runtime
+ behavior is indicated by two policy alternatives, one with and
+ one without the assertion. In a consumer/provider
+ scenario, the choice of engaging the runtime behavior is upon
+ the consumer by selecting the appropriate policy alternative.
+ The provider may influence what is possible by choosing whether or not to
+ include policy alternatives in a policy expression, by using
+ the wsp:Optional attribute.
+ </p></div><div class="div3">
+<h4><a name="d3e658" id="d3e658"></a>5.5.2 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
+ consumer to select the policy alternative that does not contain the assertion,
+ and thus not engaging the behavior.
+ </p><div class="boxedtext"><p><a name="bp-limit-optional-assertions" id="bp-limit-optional-assertions"></a><span class="practicelab">Good
+practice 10: Limit use of Optional Assertions</span></p><p class="practice">Assertion Authors should not use optional assertions for behaviors that must be present
+ in compatible policy expressions.</p></div><p> The target scope of an optional assertion is an important factor for
+ Assertion Authors to consider as it determines the
+ <em>granularity</em> where the behavior is optionally
+ engaged. For example, if the assertion is targeted for an
+ endpoint policy subject, it is expected to govern all the
+ messages that are indicated by the specific endpoint when
+ optional behavior is <em> engaged </em>. Since the
+ behavior would be applicable to policy subject that is
+ designated, it is important for the Assertion Authors
+ to choose the appropriate level of granularity for optional
+ behaviors, to consider whether a specific message or all messages, etc. are targeted.
+ </p><p>
+ When optional behaviors are indicated by attaching assertions with
+ only one side of an interaction, such as an inbound message of a
+ request-response, the engagement of the rest of the interaction will
+ be undefined. Therefore, the Assertion Authors are encouraged to
+ consider how the attachment on a message policy subject on a response
+ message should be treated when optional behaviors are specified for
+ message exchanges within a request response for response messages,
+ using message policy subject. Leaving the semantics not specified or
+ incompletely specified may result in providers making assumptions.
+ Similarly, if engagement of a behavior is only specified for an
+ outbound message, the Assertion Authors should consider describing
+ the semantics if the incoming messages also utilized the behavior.
+ This is especially important if the assertion is applicable to more
+ than one specific policy subject. One 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><div class="boxedtext"><p><a name="bp-entire-mep-for-optional" id="bp-entire-mep-for-optional"></a><span class="practicelab">Good
+practice 11: Consider entire message exchange pattern when specifying Assertions that may be optional</span></p><p class="practice">Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest
+ possible granularity to limit the degree to which optionality applies.</p></div><p>
+ Behaviors must be engaged
+ with respect to messages that are targeted to the provider
+ so that the provider can determine that the optional
+ behavior is engaged. In other words, the need for self
+ describing messages [<a href="#self-describing"><b>5.3.3 Self Describing Messages </b></a>] should
+ not be forgotten.
+ An explicit, out of band mechanism might be necessary to enable a
+ client to indicate that
+ the optional behavior is engaged.
+ (Such an out of band mechanism is outside the scope of WS-Policy
+ Framework).
+ </p><div class="boxedtext"><p><a name="bp-indicate-optional-assertion-use" id="bp-indicate-optional-assertion-use"></a><span class="practicelab">Good
+practice 12: Indicate use of an Optional Assertion</span></p><p class="practice">When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
+ either out of band or as reflected by the message content.</p></div><div class="div4">
+<h5><a name="d3e703" id="d3e703"></a>5.5.2.1 Example</h5><p>
+ The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an example that outlines the
+ use of
+ <cite><a href="#MTOM">MTOM</a></cite> as an optional behavior that can be engaged by a consumer.
+ Related to this
+ behavior is an assertion that identifies the use of MIME Multipart/Related
+ serialization [<cite><a href="#MTOMPolicy">MTOMPolicy</a></cite>]. Policy-aware clients that recognize and engage this policy
+ assertion will use Optimized MIME Serialization for messages.
+ </p><p>
+ The semantics of the MTOM assertion declare that the behavior must be reflected in
+ messages by requiring that they use an obvious wire format (MIME Multipart/Related
+ serialization). Thus, this optional behavior is self describing. For example, an
+ inbound message to a web service that requires MTOM must adhere to Optimized MIME
+ Serialization. By examining the message, the provider can determine whether the policy
+ alternate that contains the MTOM assertion is being obeyed (Good Practice
+ [<b><a href="#bp-indicate-optional-assertion-use">???</a></b>).
+ </p><p>
+ Note that if a MTOM assertion were only bound to an inbound message endpoint,
+ then it would not be clear whether the outbound message from the provider would
+ also utilize the behavior. Thus this assertion should be associated at the granularity
+ of an entire message exchange. The semantics of the assertion should specify this
+ to avoid inappropriate assumptions by implementations. This is important for an
+ optional assertion where it may not be clear whether it is to apply in a message
+ exchange when optionally used in part of that exchange
+ (Good Practice
+ [<b><a href="#bp-entire-mep-for-optional">???</a></b>).
+ </p></div></div></div><div class="div2">
<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.6 Levels of Abstraction in WSDL </h3><p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
within WSDL, Assertion Authors must specify a WSDL
@@ -945,7 +953,7 @@
[<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>]. These equivalent behaviors
are mutually exclusive for an interaction. Such equivalent
behaviors can be modeled as independent assertions. </p><div class="boxedtext"><p><a name="bp-independent-assertions" id="bp-independent-assertions"></a><span class="practicelab">Good
-practice 11: Independent Assertions</span></p><p class="practice">Use independent assertions for modeling multiple equivalent
+practice 13: Independent Assertions</span></p><p class="practice">Use independent assertions for modeling multiple equivalent
behaviors.</p></div><p>The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p><div class="exampleOuter">
@@ -974,7 +982,7 @@
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
</p><div class="boxedtext"><p><a name="bp-policy-subject-change" id="bp-policy-subject-change"></a><span class="practicelab">Good
-practice 12: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
+practice 14: Change of the Policy Subject Over Time</span></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><div class="div1">
<h2><a name="best-practices-attachment" id="best-practices-attachment"></a>7. Applying Best Practices for Policy Attachment</h2><div class="div2">
@@ -1231,7 +1239,12 @@
Mendelsohn, M. Nottingham and H. Ruellan, Editors. World Wide Web Consortium, 25 January
2005. This version of the SOAP Message Transmission Optimization Mechanism Recommendation
is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/. The <a href="http://www.w3.org/TR/soap12-mtom/">latest version of SOAP Message Transmission
- Optimization Mechanism</a> is available at http://www.w3.org/TR/soap12-mtom/. </dd><dt class="label"><a name="SOAP11"></a>[SOAP 1.1] </dt><dd>
+ Optimization Mechanism</a> is available at http://www.w3.org/TR/soap12-mtom/. </dd><dt class="label"><a name="MTOMPolicy"></a>[MTOMPolicy] </dt><dd>
+ <cite><a href="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization/optimizedmimeserialization-policy.pdf">MTOM Serialization Policy Assertion (WS-MTOMPolicy)</a></cite>,
+ C Ferris, K Gavrylyuk, J Marsh , J Schlimmer, Authors. September 2006. Version 1.0 at
+ http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization/optimizedmimeserialization-policy.pdf.
+
+ </dd><dt class="label"><a name="SOAP11"></a>[SOAP 1.1] </dt><dd>
<cite><a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">Simple Object Access Protocol (SOAP) 1.1</a></cite>, D. Box, et al, Editors.
World Wide Web Consortium, 8 May 2000. Available at
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/. </dd><dt class="label"><a name="SOAP12"></a>[SOAP 1.2 Messaging Framework] </dt><dd>
@@ -1446,4 +1459,6 @@
Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/207">207</a>.
</td></tr><tr><td rowspan="1" colspan="1">20070321</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated section <a href="#change-description"><b>E. Changes in this Version of
- the Document</b></a>. </td></tr><tr><td rowspan="1" colspan="1">20070329</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Changed all <p>Best Practice: to <p role="practice"></td></tr><tr><td rowspan="1" colspan="1">20070416</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Updated 6.2 and 6.3 for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.. Note, removed one best practice that was a dup.</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
+ the Document</b></a>. </td></tr><tr><td rowspan="1" colspan="1">20070329</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Changed all <p>Best Practice: to <p role="practice"></td></tr><tr><td rowspan="1" colspan="1">20070416</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Updated 6.2 and 6.3 for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>. Note, removed one best practice that was a dup.</td></tr><tr><td rowspan="1" colspan="1">20070423</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Updated 5.5 Designating Optional Behaviors for
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>. Added informative reference for MTOMPolicy.
+ Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there.</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.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- ws-policy-guidelines.xml 16 Apr 2007 19:27:47 -0000 1.55
+++ ws-policy-guidelines.xml 24 Apr 2007 01:14:36 -0000 1.56
@@ -912,128 +912,127 @@
</p>
</div3>
</div2>
- <div2 id="optional-policy-assertion">
- <head>Designating Optional Behaviors</head>
- <div3>
+ <div2 id="optional-policy-assertion">
+ <head>Designating Optional Behaviors</head>
+ <div3>
<head>Optional behavior in Compact authoring</head>
- <p>Optional behaviors represent behaviors which may be engaged by a consumer. When using the
- compact authoring form for assertions, behaviors are marked by
- using <code>wsp:Optional</code> attribute that has a value,
- "true". During the process of normalization, the runtime
- behavior is indicated by two policy alternatives, one with and
- one without the assertion. In a consumer/provider
- scenario, the choice of engaging the runtime behavior is upon
- the consumer although the provider is capable of engaging the
- runtime behavior. In order to simplify reference to such
- assertions, we just use the term optional assertions in this section.
- </p>
- </div3>
- <div3>
- <head>Optional behavior at runtime</head>
- <p>The <bibref ref="WS-Policy-Primer"/> document contains an
- example that proposes the use of <bibref ref="MTOM"/> as an
- optional behavior that can be engaged by a consumer. The
- primer proposes that an assertion that identifies the use of
- MIME Multipart/Related serialization (see <bibref ref="MTOM"/>,
- <bibref ref="XOP"/> for messages to enable a Policy-aware
- clients to recognize the policy assertion and if they select
- an alternative with this assertion, they engage Optimized MIME
- Serialization for messages. </p>
-
- <p>The semantics of this assertion declare that the behavior
- is reflected in messages: they use an optimized wire format
- (MIME Multipart/Related serialization). Note that in order for
- an optional behavior to be engaged, the wire message that
- would utilize the specific assertion must be self
- describing. For example, an inbound message to a web service
- that asserts MTOM, must evaluate, the protocol format of the
- message to determine whether the incoming message adheres to
- the Optimized MIME Serialization. By examining the message,
- the provider can determine whether the policy alternate that
- contains the MTOM assertion is being selected.</p>
-
- <p>Assertion Authors should be aware that optional behaviors,
- like utilizing optional support for Optimized MIME
- Serialization require some care considering the scoping of the assertion that is applicable. </p>
- <ulist>
- <item>
- <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 presence of two
- alternatives due to normalization enables a consumer to
- choose the alternative that does not contain the assertion,
- and thus making the behavior not being engaged in an interaction.
- </p>
- </item>
- <item>
- <p>As demonstrated in the MIME optimization behavior, behaviors must be engaged
- with respect to messages that are targeted to the provider
- so that the provider can determine that the optional
- behavior is engaged. In other words, the requirement of self
- describing nature of messages [<specref ref="self-describing"/>] in order to engage behaviors must
- not be forgotten with regard to the client's ability to
- detect and select the alternative if it is to participate in the exchange.
- </p>
- </item>
- <item>
- <p> The target scope of an optional assertion is an important factor for
- Assertion Authors to consider as it determines the
- <emph>granularity</emph> where the behavior is optionally
- engaged. For example, if the assertion is targeted for an
- endpoint policy subject, it is expected to govern all the
- messages that are indicated by the specific endpoint when
- optional behavior is <emph> engaged </emph>. Since the
- behavior would be applicable to policy subject that is
- designated, it is important for the Assertion Authors
- to choose the appropriate level of granularity for optional
- behaviors, to consider whether a specific message or all messages, etc. are targeted.
- </p>
- </item>
- <item>
- <p> Attaching optional assertions to outbound-messages using message policy subject
- require some care. An explicit, out of band mechanism may be necessary to enable a client to indicate that
- the optional behavior is engaged. Currently such a mechanism is outside the scope of WS-Policy Framework.
- </p>
- </item>
- <item>
- <p>When optional behaviors are indicated by attaching assertions with only
- one side of an interaction, such as an inbound message of
- a request-response, the engagement of the rest of the
- interaction will be <emph>undefined</emph>. For example,
- if a request-response interaction only specified MTOM
- optimization for an inbound message, it would not be clear
- whether the outbound message from the provider could also
- utilize the behavior. Therefore, the Assertion Authors are
- encouraged to consider how the attachment on a message
- policy subject on a response message should be treated
- when optional behaviors are specified for message
- exchanges within a request response for response messages,
- using message policy subject. Leaving the semantics
- not specified or incompletely specified may result in providers making assumptions
- (i.e. if the incoming message utilized the optimization,
- the response will be returned utilizing the MTOM
- serialization). Similarly, if engagement of a behavior is
- only specified for an outbound message, the
- Assertion Authors should consider describing the
- semantics if the incoming messages also utilized the
- behavior. This is especially important if the assertion is
- applicable to more than one specific policy subject. One
- approach that is currently taken by WS-RM Policy [<bibref
- ref="WS-RM-Policy"/>] 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>
- </item>
- </ulist>
- <p role="practice" id="bp-optional-assertions"><quote>Optional Assertions</quote><quote>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"/>.</quote>
- </p>
- </div3>
- </div2>
-
+ <p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
+ compact authoring form for assertions, such behaviors are marked by
+ using <code>wsp:Optional</code> attribute with a value of
+ "true". (In order to simplify reference to such assertions,
+ we just use the phrase “optional assertions” in this section.)
+ During the process of normalization the runtime
+ behavior is indicated by two policy alternatives, one with and
+ one without the assertion. In a consumer/provider
+ scenario, the choice of engaging the runtime behavior is upon
+ the consumer by selecting the appropriate policy alternative.
+ The provider may influence what is possible by choosing whether or not to
+ include policy alternatives in a policy expression, by using
+ the wsp:Optional attribute.
+ </p>
+ </div3>
+ <div3>
+ <head>Optional behavior at runtime</head>
+ <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
+ consumer to select the policy alternative that does not contain the assertion,
+ and thus not engaging the behavior.
+ </p>
+ <p role="practice" id="bp-limit-optional-assertions">
+ <quote>Limit use of Optional Assertions</quote>
+ <quote>Assertion Authors should not use optional assertions for behaviors that must be present
+ in compatible policy expressions.</quote>
+ </p>
+ <p> The target scope of an optional assertion is an important factor for
+ Assertion Authors to consider as it determines the
+ <emph>granularity</emph> where the behavior is optionally
+ engaged. For example, if the assertion is targeted for an
+ endpoint policy subject, it is expected to govern all the
+ messages that are indicated by the specific endpoint when
+ optional behavior is <emph> engaged </emph>. Since the
+ behavior would be applicable to policy subject that is
+ designated, it is important for the Assertion Authors
+ to choose the appropriate level of granularity for optional
+ behaviors, to consider whether a specific message or all messages, etc. are targeted.
+ </p>
+ <p>
+ When optional behaviors are indicated by attaching assertions with
+ only one side of an interaction, such as an inbound message of a
+ request-response, the engagement of the rest of the interaction will
+ be undefined. Therefore, the Assertion Authors are encouraged to
+ consider how the attachment on a message policy subject on a response
+ message should be treated when optional behaviors are specified for
+ message exchanges within a request response for response messages,
+ using message policy subject. Leaving the semantics not specified or
+ incompletely specified may result in providers making assumptions.
+ Similarly, if engagement of a behavior is only specified for an
+ outbound message, the Assertion Authors should consider describing
+ the semantics if the incoming messages also utilized the behavior.
+ This is especially important if the assertion is applicable to more
+ than one specific policy subject. One approach that is currently taken
+ by WS-RM Policy [<bibref ref="WS-RM-Policy"/>] 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>
+ <p role="practice" id="bp-entire-mep-for-optional">
+ <quote>Consider entire message exchange pattern when specifying Assertions that may be optional</quote>
+ <quote>Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest
+ possible granularity to limit the degree to which optionality applies.</quote>
+ </p>
+ <p>
+ Behaviors must be engaged
+ with respect to messages that are targeted to the provider
+ so that the provider can determine that the optional
+ behavior is engaged. In other words, the need for self
+ describing messages [<specref ref="self-describing"/>] should
+ not be forgotten.
+ An explicit, out of band mechanism might be necessary to enable a
+ client to indicate that
+ the optional behavior is engaged.
+ (Such an out of band mechanism is outside the scope of WS-Policy
+ Framework).
+ </p>
+ <p role="practice" id="bp-indicate-optional-assertion-use">
+ <quote>Indicate use of an Optional Assertion</quote>
+ <quote>When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
+ either out of band or as reflected by the message content.</quote>
+ </p>
+ <div4>
+ <head>Example</head>
+ <p>
+ The <bibref ref="WS-Policy-Primer"/> document contains an example that outlines the
+ use of
+ <bibref ref="MTOM"/> as an optional behavior that can be engaged by a consumer.
+ Related to this
+ behavior is an assertion that identifies the use of MIME Multipart/Related
+ serialization [<bibref ref="MTOMPolicy"/>]. Policy-aware clients that recognize and engage this policy
+ assertion will use Optimized MIME Serialization for messages.
+ </p><p>
+ The semantics of the MTOM assertion declare that the behavior must be reflected in
+ messages by requiring that they use an obvious wire format (MIME Multipart/Related
+ serialization). Thus, this optional behavior is self describing. For example, an
+ inbound message to a web service that requires MTOM must adhere to Optimized MIME
+ Serialization. By examining the message, the provider can determine whether the policy
+ alternate that contains the MTOM assertion is being obeyed (Good Practice
+ [<specref ref="bp-indicate-optional-assertion-use" />).
+ </p><p>
+ Note that if a MTOM assertion were only bound to an inbound message endpoint,
+ then it would not be clear whether the outbound message from the provider would
+ also utilize the behavior. Thus this assertion should be associated at the granularity
+ of an entire message exchange. The semantics of the assertion should specify this
+ to avoid inappropriate assumptions by implementations. This is important for an
+ optional assertion where it may not be clear whether it is to apply in a message
+ exchange when optionally used in part of that exchange
+ (Good Practice
+ [<specref ref="bp-entire-mep-for-optional" />).
+ </p>
+ </div4>
+ </div3>
+ </div2>
+
<div2 id="levels-of-abstraction">
<head>Levels of Abstraction in WSDL </head>
@@ -1646,6 +1645,13 @@
2005. This version of the SOAP Message Transmission Optimization Mechanism Recommendation
is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/. The <loc href="http://www.w3.org/TR/soap12-mtom/">latest version of SOAP Message Transmission
Optimization Mechanism</loc> is available at http://www.w3.org/TR/soap12-mtom/. </bibl>
+ <bibl key="MTOMPolicy" id="MTOMPolicy"
+ href="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization/optimizedmimeserialization-policy.pdf">
+ <titleref>MTOM Serialization Policy Assertion (WS-MTOMPolicy)</titleref>,
+ C Ferris, K Gavrylyuk, J Marsh , J Schlimmer, Authors. September 2006. Version 1.0 at
+ http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization/optimizedmimeserialization-policy.pdf.
+
+ </bibl>
<bibl id="SOAP11" key="SOAP 1.1" href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">
<titleref>Simple Object Access Protocol (SOAP) 1.1</titleref>, D. Box, et al, Editors.
World Wide Web Consortium, 8 May 2000. Available at
@@ -2112,7 +2118,14 @@
<tr>
<td>20070416</td>
<td>DBO</td>
- <td>Updated 6.2 and 6.3 for <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>.. Note, removed one best practice that was a dup.</td>
+ <td>Updated 6.2 and 6.3 for <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>. Note, removed one best practice that was a dup.</td>
+ </tr>
+ <tr>
+ <td>20070423</td>
+ <td>FJH</td>
+ <td>Updated 5.5 Designating Optional Behaviors for
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>. Added informative reference for MTOMPolicy.
+ Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there.</td>
</tr>
</tbody>
</table>
Received on Tuesday, 24 April 2007 01:14:46 UTC