RE: Bug 6463: Attaching Policy to WS-Mex GetMetadata - Marked up proposal

The attached Word document carries all the known editorial suggestions [1][2].

[1] http://lists.w3.org/Archives/Public/public-ws-resource-access/2009Dec/0067.html
[2] http://lists.w3.org/Archives/Public/public-ws-resource-access/2009Dec/0076.html

Regards,

Asir S Vedamuthu
Microsoft Corporation

From: public-ws-resource-access-request@w3.org [mailto:public-ws-resource-access-request@w3.org] On Behalf Of Asir Vedamuthu
Sent: Tuesday, December 15, 2009 12:45 PM
To: Katy Warr
Cc: public-ws-resource-access@w3.org
Subject: RE: Bug 6463: Attaching Policy to WS-Mex GetMetadata - Marked up proposal

Thanks Katy for your response.

Reviewed. We suggest the following editorial amendments. We did not have sufficient time to prepare a marked up version. We will be happy to prepare one.


1.  Example 8-1

Katy> We can exploit the fact that the WS-Metadata Endpoint is the same as the application endpoint  (that the EPR represents) and therefore would share its protocol binding information.

Given that section 8 is about bootstrap binding, to help our readers, we think these assumptions should be called out explicitly.

Suggestion

s/Example 8-1, a [WS-Addressing] endpoint reference to a service endpoint contains the metadata to allow requesters to issue a GetMetadata request against it./Example 8-1, a [WS-Addressing] endpoint reference to a service endpoint contains the metadata to allow requesters to issue a GetMetadata request against it. Example 8-1 assumes that requestors are aware of binding information such as the version of SOAP and the underlying transport./


2.  Example 8-1 - replace necessary metadata with additional metadata

Example 8-1 illustrates how to embed additional metadata.

Suggestion

s/ The endpoint reference contains metadata associated with the service endpoint (lines 04-19) and a MetadataSection (lines 06-18) which contains the necessary metadata for interacting with the endpoint through [WS-MetadataExchange]./ The endpoint reference contains metadata associated with the service endpoint (lines 04-19) and a MetadataSection (lines 06-18) which contains additional metadata for interacting with the endpoint through [WS-MetadataExchange]./



3.  Drop the last sentence. We think this is a cut and paste error. The last sentence talks about an alternative that is already discussed as example 8-2.

Suggestion

s/ As an alternative to using MetadataLocation (lines 17-20), the WS-MetadataExchange WSDL containing the appropriately attached policy could have been embedded directly into the MetadataSection.//


4.  Example 8-2

Katy> I have made some minor changes (the Identifier and tns on line 10 - let me know if I got this wrong)

The embedded WSDL is a user-defined WSDL and constructs should not be in the MEX namespace name.

Suggestions

s/"targetNamespace='http://www.w3.org/2009/09/ws-mex'"/"targetNamespace='http://services.example.org/stockquote/metadata'"/ (or any other namespace name other than the MEX namespace name)

s/"Identifier='http://www.w3.org/2009/09/ws-mex'"/"Identifier='http://services.example.org/stockquote/metadata'"/

s/The metadata for the [WS-MetadataExchange] interaction is of wsdl dialect (line 11) and the identifier (line 08) identifies the WS-MetadataExchange feature as described in section 9"//


5.  Example 8-3

The same reasoning as item 4 applies to Example 8-3.

Suggestions

s/"Identifier='http://www.w3.org/2009/09/ws-tra'"/"Identifier='http://services.example.org/stockquote/ws-tra'"/ (or any other namespace name other than the Transfer namespace name)

s/The metadata for the [WS-MetadataExchange] interaction is of wsdl dialect (line 16) and the identifier (line 17) identifies the WS-Transfer feature as described in section 9./The metadata for the [WS-MetadataExchange] interaction is of wsdl dialect (line 16)./

Regards,

Asir S Vedamuthu
Microsoft Corporation

From: Katy Warr [mailto:katy_warr@uk.ibm.com]
Sent: Tuesday, December 15, 2009 3:07 AM
To: Asir Vedamuthu
Cc: public-ws-resource-access@w3.org
Subject: RE: Bug 6463: Attaching Policy to WS-Mex GetMetadata - Marked up proposal


Hi Asir

Thanks for your comments.

> We are afraid that the proposed Example 8-1 does not provide sufficient protocol binding information to allow requesters to issue a GetMetadata request against a service endpoint. For instance, how can a requester infer what is the version of SOAP? What is the underlying protocol transport?

We can exploit the fact that the WS-Metadata Endpoint is the same as the application endpoint  (that the EPR represents) and therefore would share its protocol binding information.  Hence, in this case, I don't think we require this information (it may be defaulted to).

> We think that the WS-MetadataExchange specification should provide an example that provides sufficient binding information, including policies (to address issue 6463), to bootstrap.

> The description of the alternative sounds right. But, example 7.1 describes how to embed service metadata within an EPR. These are two different use cases. It might help to show case an example that illustrates how to embed a bootstrap binding in an EPR and how to attach a policy expression (to address issue 6463) to the bootstrap binding.

How about the attached update?  I've taken your example (from a previous email) and included it as example 8.2.  I have made some minor changes (the Identifier and tns on line 10 - let me know if I got this wrong).  I've also added so explanation below the example for your review/comments and made some very minor tweaks to the other explanations to ensure that the explanations were consistent and that the text flows ok.

Regards,
Katy


From:

Asir Vedamuthu <asirveda@microsoft.com>

To:

Katy Warr/UK/IBM@IBMGB, "public-ws-resource-access@w3.org" <public-ws-resource-access@w3.org>

Date:

14/12/2009 17:13

Subject:

RE: Bug 6463: Attaching Policy to WS-Mex GetMetadata - Marked up proposal


________________________________



Thanks Katy.

Here are some initial comments on the proposal.

>In Example 8-1, a [WS-Addressing] endpoint reference to a service endpoint contains the metadata to allow requesters to issue a GetMetadata request against it

We are afraid that the proposed Example 8-1 does not provide sufficient protocol binding information to allow requesters to issue a GetMetadata request against a service endpoint. For instance, how can a requester infer what is the version of SOAP? What is the underlying protocol transport?

We think that the WS-MetadataExchange specification should provide an example that provides sufficient binding information, including policies (to address issue 6463), to bootstrap.

>As an alternative to using MetadataLocation (lines 08-17), the WS-MetadataExchange WSDL containing the appropriately attached policy could have been embedded directly into the MetadataSection.  The embedded WSDL approach was used in example Example 7.1 to pass metadata in the EPR.

The description of the alternative sounds right. But, example 7.1 describes how to embed service metadata within an EPR. These are two different use cases. It might help to show case an example that illustrates how to embed a bootstrap binding in an EPR and how to attach a policy expression (to address issue 6463) to the bootstrap binding.

We will be more than happy to work with Katy to prepare a revised proposal.

Regards,

Asir S Vedamuthu
Microsoft Corporation

From: public-ws-resource-access-request@w3.org [mailto:public-ws-resource-access-request@w3.org] On Behalf Of Katy Warr
Sent: Monday, December 07, 2009 10:42 AM
To: public-ws-resource-access@w3.org; Asir Vedamuthu
Subject: Bug 6463: Attaching Policy to WS-Mex GetMetadata - Marked up proposal


Following my action to create a markup version of the proposal for bug http://www.w3.org/Bugs/Public/show_bug.cgi?id=6463, please find the marked up document attached.  The changes are all in Section 8 (and an example is moved from section 7).



Asir,

The difference between your example and my previous one is primarily that you have embedded the WSDL metadata within the EPR, rather than using Policy Attachments.

Whilst both approaches work, I believe that we should have a wider variation of examples within the specification in order to illustrate different features and usage scenarios. From my experience, a wide range of examples is of great benefit to developers.  Embedded WSDL is already illustrated in example 7-1.

In this particular example (8.1), policy attachments also work very well as it provides a mechanism to associate policy with a single operation without having the whole WSDL included within the EPR.

As a suggested compromise, I've included the policy attachments example (8-1) in the proposal attached to this mail, but added a detailed explanation below it in order to aid understanding.  I have also added some text to say that the WSDL could be embedded, as an alternative approach.

Regards
Katy

________________________________



Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU





________________________________


Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU