Re: Misc editorial

Hi Tommy,

On Wed, Apr 13, 2005 at 10:32:13PM +0100, Tommy Lindberg wrote:
> 
> Sorry for late response.  Here are some comments.

Better late than never. Many thanks for all your comments
and suggestions. I modified the spec. accordingly. It sometimes 
makes it awkward to say polling or notification, but it is much more 
better than not saying anything.

I updated and commited the spec [1].

See my inline comments.

[snip]

> > we should add a <PendingNotification> element to 2.5.3.1.
> 
> Yes, that seems like a good idea. I'd say one example is enough. Using
> the SMTP variant
> may be easier to relate to, at least this is what was mostly used
> during interop, some
> people even provided working e-mail addresses :)
> 
>    <km:PendingNotification Mechanism="urn:ietf:rfc:822"
>              Identifier="mailto:alice@example.com"/>

I added this one in 2.5.4.1 (the section number changed). I'm not
sure if we should expand the text in 2.5.4.3 which now reads:

<quote>
The XKMS service notifies the client about the completion of the request
processing using the notification mechanism specified in the
<PendingNotification> element.
</quote>

By adding this sentence after the period: "In this case, the service 
sends a mail to alice@example.com to notify that the request has 
been processed".

I hesitate... I think it looks good as it is now :)

[snip]
> 
> I took the liberty of identifying potential additional 
> adjustments to the text::

Please feel free to continue taking such liberties. As long as we
have the opportunity to improve the text, let's do it  :)

> [55] Asynchronous processing consists of a sequence of
> request/response pairs; an initial
> request which specifies the request values, zero or more status
> requests and a pending
> request which obtains the result of the operation.  The client may
> issue status requests in
> order to poll the status of an asynchronous operation independant of
> the use of the
> notification mechanism indicated [by the client] in the initial request.
>

Change added. I changed "independant" to "independently".
 
> Somewhere below [56]:
> Register request as pending completion, poll processing status and/or
> wait for notification.

Done.
 
> [57] The client determines, through notification or polling, that the
> requested operation has
> completed and requests the return of the result values by issuing a
> PendingRequest
> message as follows:

Done.

> 2.5.1b Status Request
> The client may poll the status of the asynchronous operation as follows:
> 
> Requestor generation of the Status Request Message
>     The request element is StatusRequest
>     OriginalRequestId is set to the value of Id in the initial request message
>     ResponseId is set to value of Id in the initial response message
> Service processing of the Status Request Message
>     Identify pending request using OriginalRequestId and ResponseId.
> Service generation of the Status Response Message
>     RequestId is set to the value of Id in the Status Request message
>     Nonce is not present    
> Requestor processing of the Status Response Message
>     For non-compound messages, the ResultMajor attribute indicates the
> status of the
>     operation.
>     For compound messages, the Success/Failed/Pending attributes
> further indicate the
>     number of inner requests that have the respective status.

Added it as 2.5.2, added p. [56a]  and scrolled down the subsequent
subsection numbers by one (very restricted change... didn't need
a Toc Update).

> As a result of searching the rest of spec for occurences of "notif"
> you may also consider
> the following adjustment
> From: [81] After the appropriate notification has taken place, the
> client issues ...
> To: [81] When the service has completed the processing, as determined
> through polling or
> notification, the client issues ...

Done.
 
> In 2.5.3.5, the ResultMajor seems to be missing the XKMS namespace.

I checked again and it is there. Did I miss something?

> Reasonably close to [54] there is a statement "ResponseMechanism
> values Represent
> and/or Pending MAY be specified" that I think should not be there as
> this advises the
> service that the client is prepared to support either two-phase or
> asynchronous processing
> which is not what that paragragh is trying to describe and would therefore
> only potentially confuse the reader.  It is true that those response
> mechanisms may be
> specified but then the documented processing steps rely on the service
> not supporting
> either of them or that it for some other reason elects to respond 
> synchronously.

It took me some time to decide what to do here. I removed the
Represent and changed that line of text to say:

"ResponseMechanism value Pending MAY be specified but the service 
 will ignore it"

If you think that it's still confusing, I'll remove it. This is described
a couple of paragraphs above in [51].

> In 2.5.2
> 
> Under "Service generation of the Pending Response Message" the
> statement "ResponseId
> is set to a randomly generated unique value" does not belong there. 
> Maybe what is meant
> is "The Id of the response ..." in which case it would be valid.

I just erased the ResponseId line as we didn't give so much detail about
Id in the other lines. I had also caught this when checking the changes.

The only remaining reference to notification without polling is in
[43]. We would need to add a Result.Pending -> Status.Request->Pending
Request or something similar. I'm not familiar with the CSP formalism.
I can read it, but am not sure if I can write it correctly and still
have other things to do to finish preparing the spec. Unless someone 
raises an objection (or proposes the changes), I propose
we just let it be.


-jose

[1] http://www.w3.org/2001/XKMS/Drafts/XKMS-PR-PUB/PR-PUB-xkms-part-1.html