This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 4253 - [Primer] Basic Concepts section on Policy does not explain usage reasonably
Summary: [Primer] Basic Concepts section on Policy does not explain usage reasonably
Status: RESOLVED FIXED
Alias: None
Product: WS-Policy
Classification: Unclassified
Component: Primer (show other bugs)
Version: FPWD
Hardware: Macintosh All
: P2 normal
Target Milestone: ---
Assignee: Felix Sasaki
QA Contact: Web Services Policy WG QA List
URL: http://dev.w3.org/cvsweb/~checkout~/2...
Whiteboard:
Keywords:
Depends on:
Blocks: 4142
  Show dependency treegraph
 
Reported: 2007-01-17 23:20 UTC by William Henry
Modified: 2007-03-13 21:40 UTC (History)
0 users

See Also:


Attachments

Description William Henry 2007-01-17 23:20:20 UTC
Title: Basic Concepts section to Policy in primer does not explain attachment

Description: Section 2.2. is basically an introduction to to why someone might use policy and explains this from the point of view of a simple SOAP message that wants to use WS-Addressing.  The section then shows a simple policy to cover this case. However the example just mentions that the policy can be attached to the WSDL binding. It doesn't show how this is done. Surely this is fundamental for a new user of Policy. I think that this first example should demonstrate how the policy might be simply attached to a binding in a WSDL. 

Justification: For a new user of WS-Policy thePrimer should be explaining why you might use policy (this section does that), and how you would use a policy - two parts a) how to express it (section does that) and b) how to use the expression (section just mentions this but does not show an example - a simple one would suffice).

Proposal: Change this section to add an example that shows the policy defined in the example attached to a binding in the WSDL. 

<wsdl:binding name="AddressingBinding" type="tns:RealTimeDataInterface" >
  <Policy>
  	<wsap:UsingAddressing />
  </Policy>
  <wsdl:operation name="GetRealQuote"></wsdl:operation>
  
</wsdl:binding>

Notice that this example does not use any references but shows the most basic way of attaching to a binding.

The section can then point to the section on How to attach Policy to WSDL.

Note: Referencing the attachment section will not suffice as the attachment section only shows how to attach using a reference. (separate issue to be raised)
Comment 1 William Henry 2007-02-14 16:48:49 UTC
Proposal - add the following text to section 2-2 - Replace the paragraph under example 2-2 with the following and modify the subsequent example numbers by incrementing.

The policy expression in the above example consists of a Policy main element and a child element wsap:UsingAddressing. Child elements of the Policy element are policy assertions. Contoso attaches the above policy expression to a WSDL binding description.

Example 2-3. Policy Expression Attached to Binding
<wsdl:binding name="AddressingBinding" type="tns:RealTimeDataInterface" >
  <Policy>
    <wsap:UsingAddressing />
  </Policy>
  ...
</wsdl:binding>

Policies can also be attached to WSDL using references (See 2.10 Attaching Policy Expressions to WSDL.)

<----END OF TEXT ---->
HTML for the editors to add:

The policy expression in the above example consists of a <code>Policy</code> main element and a child element <code>wsap:UsingAddressing.</code> Child elements of the <code>Policy</code> element are policy assertions. Contoso attaches the above policy expression to a WSDL binding description.</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 2-3. </span>Policy Expression Attached to Binding</i></p><div class="exampleInner"><pre>&lt;wsdl:binding name="AddressingBinding" type="tns:RealTimeDataInterface" &gt;
  &lt;Policy&gt;
    &lt;wsap:UsingAddressing /&gt;
  &lt;/Policy&gt;
  ...
&lt;/wsdl:binding&gt;</pre></div></div>

Policies can also be attached to WSDL using references (See <a href="#attaching-policy-expressions-to-wsdl"><b>2.10 Attaching Policy Expressions to WSDL</b></a> ).
Comment 2 Christopher Ferris 2007-03-13 21:40:17 UTC
[17:38] cferris: RESOLUTION: 4253 and 5255 closed with proposals from William in http://lists.w3.org/Archives/Public/public-ws-policy/2007Feb/0078.html and http://lists.w3.org/Archives/Public/public-ws-policy/2007Feb/0076.html
[17:39] cferris: rrsagent, where am i?
[17:39] RRSAgent: See http://www.w3.org/2007/03/13-ws-policy-irc#T21-39-50