ace-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Přemek Brada <br...@kiv.zcu.cz>
Subject Re: Versioned OBR proposal
Date Wed, 14 Dec 2011 10:07:20 GMT
Hello Marcel and all,

thanks for the detailed reply to Jan's email.  My few notes on the
REST API are below; I would also point out
https://issues.apache.org/jira/browse/ACE-151 which I forgot to
mention to him before.

On 4 December 2011 23:37, Marcel Offermans <marcel.offermans@luminis.nl> wrote:
<snip>

>> 1. PUT
>> Our vision is that by putting a new resource to the OBR, there
>> would be a decision, whether it is or it isn't a bundle. If it is another file,
>> store it only in the OBR. If it is a bundle, perform the versioning according
>> the last version of the bundle in the OBR first, then store it. This should
>> happen all the time and thus, we could have the consistent list of all the
>> versions of the bundle, that were uploaded in time. Naturally, if there is no
>> another version, no versioning is performed.
>
> If you look at the definition of a REST API then the semantics for PUT are to always
store (and replace) the exact resource that you specified, so I would not want to deviate
from that unless we have a really good reason. We are however free to add a POST command that
uses semantic versioning.

I agree, we should use POST for that.

>> The problem is, that only the method put(String fileName, InputStream
>> data) is present so far, the client decides the filename. If there is a file with
>> this name in the OBR (which is the case by different bundle versions) it would
>> be overwritten.
>
> We are free to extend our API.

Would a VersionedBundleStore extends BundleStore interface be a
reasonable solution?  I guess we should not modify the BundleStore
since it is standardized.


>> To let the OBR API backward compatible and still take advance
>> from the versioning, the client have to manually add the the version suffix to the
>> filename, but it doesn't know, whether the version in the manifest is really
>> correct, since no semantic versioning was performed yet.
>
> Right now we assume the client has correctly done semantic versioning. Most of the time,
he will have to do that by hand, but there are other tools surfacing that help (BndTools now
allows this).

This however is at odds with our intention, which is to integrate
semantic versioning seamlessly into ACE to ensure the bundles are
versioned correctly in its repository, regardless of whether client
does use semantic versioning.

What Jan points at is that the integration brings however the need for
the client to obtain the generated version and possibly the final
filename of the stored bundle.


>> We propose to add another method to the OBR servlet like
>> dryRun(InputStream data), that perform the versioning on the uploaded bundle
>> but doesn't store it to the OBR, only returns in the HTTP header the info, whether
>> there is another version and if so, also the corrected version of the uploaded
>> bundle. Then the client constructs the filename and calls the common put
>> method.
>
> Let me make a counter-proposal here to add a POST method that will do the upload, then
modify the bundle (if there are existing versions in the OBR of this same bundle) and finally
either redirect or return the proper URL of the versioned bundle.

Redirect looks like a reasonable solution; my question (maybe due to
lack of experience) is: will the client interpret it as we want it, ie
"this is the URI -> filename under which my bundle is stored, I need
to remember it"?


>> 2. GET
>> Typically I like to get the latest version of the bundle, that is in the repository.
>> We can use the present get(filename) method, but we have to know the filename.
>> listBundles(String symbolicName) would do the work, possibly by inspecting
>> the repository.xml.
>
> The current OBR spec indeed assumes that you first GET the repository.xml, parse that
and based on the information inside that file, make up your mind about what exact bundle (or
artifact) you want.
>
> On top of that, I could live with an optional query mechanism that allows you to do things
like:
>
> GET /obr/?bsn=org.apache.felix.cm - to return the highest version of a bundle with the
specified symbolic name
> GET /obr/?vsn=org.apache.felix.cm&v=[1.0,2.0) - same, but highest version within
the given range
> GET /obr/?vsn=org.apache.felix.cm&v=[1.0,2.0)&lowest - same, but lowest version
within the given range
>
> or even, some kind of query that will return a list or subset (in which case it might
actually make sense to either return just URLs or a filtered repository.xml)


Shouldn't we rather have
GET /obr/artefact/org.apache.felix.cm
GET /obr/artefact/org.apache.felix.cm&v=[1.0,2.0)
etc?


Premek



-- 
Premek Brada (Ing et MSc, PhD)
  Head of Software Engineering and Information Systems Section
  Department of Computer Science and Engineering
  University of West Bohemia in Pilsen, CZ
  << brada at kiv.zcu.cz | www.kiv.zcu.cz/~brada/ | +420-377-63-2435 >>

Mime
View raw message