[Osr-101] Neutron specs

[Thomas Comiotto]

Hi Michi


>>  * Let's add identifiers to resources. Currently we have an edit 
>> directive containing a bunch of methods operating on a remote 
>> resource identified by nill. However, resource identifiers are 
>> crucial for view templating for instance. They are also crucial for 
>> resource sets (see below). I propose to kick out the open command
>
>
> How do you want to differentiate between open and checkout (acquire 
> lock and open)?
>

You open and then maybe you lock.

But on the other hand yes, I think that in terms of keeping the API 
consistent (it ain't now but hopfully will be at some point) the open 
command makes sense. It also makes sense if one is constraint to a 
single service endpoint.

So +1 for keeping it.

>
> it makes clear what can be done and allows to differentiate between 
> operations. I am not sure if I understand what you mean, but
> maybe you actually mean something like this:
>

What can be done is already covered by the method names: save, lock, 
unlock, authorize.

> <introspection>
>  <resource name="Hello World">
>    <edit mime-type="application/xhtml+xml">
>      <checkout url="helloworld.xhtml?foobar=checkout" method="GET"/>
>      <checkin url="helloworld.xhtml?foobar=checkin" method="POST"/>
>    </edit>
>
>    <workflow>
>     ...
>    </workflow>
>  </resource>
>
> ....
> </introspection>

How to refer to the resource in the above example - by name?

One could use the open commandURL but then that would have to be 
mandatory. On the other hand, if we add an url attribute to the 
resource the information held by that attribute will be redundant to 
the open url in 95% of the cases I guess.

Therefore I voted for geting rid of open in the first place.

What about something like this:

<introspection>
   <resource name="Hello World" url="helloworld.xhtml" 
mime-type="application/xhtml+xml">
     <edit>
        <checkout url="helloworld.xhtml?foobar=checkout" method="GET"/>
        <checkin url="helloworld.xhtml?foobar=checkin" method="POST"/>
     </edit>
   </resource>
</introspection>

I might not have been clear about why resource identifiers (URI, URN) 
are needed, so I will give it another try. Consider a view template 
referring to some resources:

<page>
   <sidebar>
     <xi:include href="??"/><!-- refers to resource #1 -->
   <sidebar>
   <content>
     <xi:include href="??"/><!-- refers to resource #2 -->
   </content>
</page>

The client needs a way to map the included resources to the resources 
listed in the introspection file (to allow for editing them). 
Considering your example and with what we have in the specs so far, the 
only way to do this would be to write:

<page>
   <sidebar>
     <xi:inclde href="helloworld.xhtml?foobar=checkout"/>
   </sidebar>
   <content>
     <xi:include href="helloworld2.xhtml?foobar=checkout"/>
   </content>
</page>

Doesn't make sense, does it?

>>
>> * Let's replace the "method" attribute of all methods that use it 
>> (save, checkin) by attributes that account for the url scheme used 
>> (file, http, ftp, whatever). So in case of http, method="PUT" should 
>> read httpMethod="PUT" as in the above snippet.
>
>
>
> you mean that Neutron could also be placed on top of other protocols 
> than just HTTP?
>

yes.


>> * I have added view templating to the specs. Please review and 
>> comment.
>
>
> ok, will review
>
>> * I have added resource sets to the specs. Please review and comment.
>
>
> will review
>
>>
>>
>> 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 ;-)
>

I don't mind my changes being reverted. I also can hold on a bit of 
course. Fact is that the specs in their current state are, .. well, 
..not really convincing for outsiders. I want to have that fixed.

Besides that I it's better to get into a comit war than to end up with 
nothing decent in time - if that leads to an ever lasting peace in the 
end.....

--
Bests
Thomas