[Osr-101] Neutron specs

[Andreas Wuest]

Hi Thomas

On 22.8.2006 20:26 Uhr, Thomas Comiotto wrote:

> Hi Andi
> 
>> Actually, we could leave out <edit>, but only under the assumption 
>> that whenever you receive a document by way of the <checkout> or 
>> <open> address, this means that you can edit it. Or with other words: 
>> we cannot provide different views apart from edit, i.e. if you want to 
>> checkout a document for e.g. simple displaying instead of editing, 
>> this wouldn't work, because we always had to deliver a document ready 
>> for editing when someone accesses the checkout URI.
>>
> 
> I am not sure if I understand. First of all, I would keep Neutron to the 
> bare minimum in terms of what's needed to remote authoring. Leave alone 
> the idea of mapping client GUI elements to protocol commands. That's a 
> design desicion that no client side developper wants to be forced in and 
> will not pay off in the long run.
> 
> Instead let the client application decide on what to do with the 
> available methods/commands and *keep them simple*. If for instance 
> locking a resource is required and a write lock can be aquired a client 
> can provide for editing, otherwise just for viewing.
> 
> Opening/retrieving a doc should be considered being always possible, 
> whether in read-only or in read/write mode. The open method is 
> equivalent to simply accessing a resource by its URI in almost all cases 
> (except of servers want to provide a seperate service endpoint for 
> Neutron). The URI of the resource could also serve as a good identifier 
> to refer to the resource, as opposed to using the open command for that 
> because the open command suggest being, well, just the open command.
> 
> Also see http://wyona.com/pipermail/phoenix/2006-August/000367.html

Hmm, no, that's not what I meant. What I meant to say is the following: 
by providing an <edit> container, a client knows that whatever is stated 
in the edit block is regarding editing.

If you'd like to have different view configurations of the same document 
in question for different purposes, then we could simply add a 
<fancynewidea> element, and every <open> endpoint statet therein implies 
that if you want to open the document with a configuration tailored 
toward that fancynewidea, you should use the open URI provided in that 
block.

With your solution, there is only one single open URI. Which basically 
implies that it is not possible to request a different view 
configuration from the server.

Let me give an example:

<introspection>
   <edit name="Some Document">
     <open url="/document?open"/>
     <save url="/document?save"/>
   </edit>
   <print name="Some Document">
     <open url="/document?print"/>
   </print>
</introspection>

Imagine a printing client which understands the <print> usecase. It 
would then load the document from the url specified in the <open> 
element inside the <print> block. The server would then deliver a 
special configuration of that document tailord towards printing 
(whatever that means).

Now, with your solution, i.e.

<introspection>
   <resource url="/document" name="Some Document">
     <save url="/document?save"/>
   </resource>
</introspection>

where would that open link go which opens the document in a 
configuration for printing?

On the same token, regarding my first example above, it is really ugly 
to have the <edit> and the imaginary <print> element not inside a common 
block. After all, following the semantics, we are talking about them 
*same* resource, simply delivered by the server with different 
configurations. So I'd suggest the following:

<introspection>
   <resource name="Some Document">
     <edit>
       <open url="/document?open"/>
       <save url="/document?save"/>
     </edit>
     <print>
       <open url="/document?print"/>
     </print>
   </resource>
   <resource name="Some other Document">
     ...
   </resource>
</introspection>

This is all about scoping and extensibility. Instead of <print>ing, we 
could also think about <publish>ing, <annotate>ing, etc. For all these 
usecase, your client may require a different view configuration of the 
same resource. By declaring the URI to load the document as an attribute 
of the <ressource>, we are limiting ourselves to one and only one 
possible configuration.

(Note that my example above does not take into consideration the unique 
identification of resources, but could simply be added by e.g.

<resource name="Some Document" uid="/document"/>

or something like this.)

> Checkout is a shortcut of open + lock. I am still not convinced re this 
> shortcut when considering servers with exclusive/shared locks. I don't 
> think it makes sense but Michi does, well..

Let's simply supply all of them, but make it clear what checkout and 
checkin mean.

> To make two more points re considering content editable/read-only: 
> Ulysses for instance provides a "save to local filesystem" function - so 
> every retrieved document is considered editable. And, Neutron is a 
> content authoring protocol so the implied usecase is to edit.

Uhhm, I'd rather call it a content *management* protocol, which does not 
only imply editing, but also much more. Of course, this "much more" 
still has to be specified.

Selling the edit usecase as its main feature would IMHO be Wrong(tm).

>>> you mean that Neutron could also be placed on top of other protocols 
>>> than just HTTP?
>>
>> Of course. But this can also be acomplished using the format we are 
>> using now, because the scheme part of the URI basically defines the 
>> protocol. Using the format above, we had to introduce "*Method" 
>> attributes for every protocol a user could potentially be interested in.
>>
> 
> Agreed. But I wanted to make the point that not every protocol uses the 
> semantics of a "method", therfore "method" implies using a scheme that 
> supports it, HTTP for instance. Anyway that's minor issue:)

Ah, ok, I understand. Yeah, we should find a different name for the 
"method" attribute. E.g. something more neutral like "type".

>> Therefore, I basically vote -1 for such a format.
>>
>>>> Otherwise I hope you like the changes I forgot to mention here:)
>>> will check :-). I think we should introduce "Paces" as Atom does in 
>>> order to discuss changes, otherwise I am
>>> afraid that we get into a commit war at some point ;-)
>>
>> Heh. :) But to be honest, I would rather have the complete spec hosted 
>> in a Wiki, where we can add annotations, etc. And then, we could also 
>> add paces there. Just carrying them around in mails is cumbersome, so 
>> we should have a place where we can look up the original pace 
>> suggestion. (BTW, the APP WG does also have their paces in a Wiki.)
>>
> 
> Very much agreed. Still it ain't too hard to collect what has been 
> posted on this list luckily - and these points will have to be further 
> discussed on this list;)

Yeah, not too much traffic luckily!

-- 
Kind regards,
Andi