Mailing-List: contact oak-dev-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Received-SPF: pass (nike.apache.org: domain of jukka.zitting@gmail.com
 designates 74.125.82.170 as permitted sender)
MIME-Version: 1.0
From: Jukka Zitting <jukka.zitting@gmail.com>
Date: Mon, 25 Jun 2012 14:26:05 +0200
Message-ID: 
 <CAOFYJNbEEBsdmFi2OptKwWhtjuxUgcPYSXQ+-ddBcsXZOUSYtw@mail.gmail.com>
Subject: Native HTTP bindings for Oak
To: Oak devs <oak-dev@jackrabbit.apache.org>
Content-Type: text/plain; charset=ISO-8859-1

Hi,

As suggested in OAK-104 [1] and discussed briefly before, I think it
would be useful for Oak to have a native HTTP binding that allows
remote clients to talk directly with oak-core without having to go
through the JCR layer.

The main benefit of such a lower-level HTTP binding is that it can
better leverage the "everything is (JSON) content" nature of Oak
internals than a higher-level layer like our existing WebDAV(ex)
components that only assume a generic JCR content repository. This
makes the binding much more straightforward and probably helps avoid
performance or scalability bottlenecks down the line. It also makes it
easier to support a wider range of functionality without having to add
custom integration code for all features. For example, instead of
accessing separate namespace registration code, a client could
register a new namespace simply by posting it as a normal content
modification to the appropriate place in the content tree, like this:

    $ curl -d foo=http://foo.example.com/ns
http://localhost:8080/content/jcr:system/jcr:namespaces

Unlike a MicroKernel remoting layer, the Oak HTTP binding would still
have all the commit validation and access control logic in place, so
one couldn't use it to bypass the rules that govern more traditional
JCR-based access.

I'm not yet sure about what the binding should look like in detail,
but my general idea is to follow JSOP protocol ideas [2] and try to
keep things as simple and easy as possible for clients like JavaScript
libraries [3] and command line tools like curl. The initial draft code
I committed just recently to the new oak-http component uses a basic
URL to Node mapping and a simple JSON / binary JSON rendering based on
the contents of the HTTP Accept header. It would be nice to support
different kinds of content renderings and also to allow similar
content renderings to be POSTed or PUT to the server. The binding
should also accept basic HTML form POSTs with the
application/x-www-form-urlencoded media type.

By default the HTTP binding could simply use a fresh new session for
each HTTP request, but it should be possible for a client to request a
longer-lived session for more complex content modifications (import,
batch jobs, etc.) or for getting a stable snapshot for larger reads
(export, query, etc.) that shouldn't change while reading. I was
thinking of handling such cases by allowing the client to generate
such a session with a specific POST request that responds with a
redirect to a temporary session URL that exposes the normal content
tree as seen through that session. We'd use a lease mechanism to
control the lifetime of such server-side sessions.

As an example, something like the following interaction could be used
to acquire a new session (with a initial lifetime of one hour,
lease=3600), make some changes to the content tree within that
session, and finally commit those changes and release the session
(lease=0).

    $ curl -d lease=3600 http://localhost:8080/session
    http://localhost:8080/session/a9c49810bebf11e1afa70800200c9a66
    $ curl -d bar=baz
http://localhost:8080/session/a9c49810bebf11e1afa70800200c9a66/foo
    {"bar":"baz"}
    $ curl -d save=true -d lease=0
http://localhost:8080/session/a9c49810bebf11e1afa70800200c9a66

[1] https://issues.apache.org/jira/browse/OAK-104
[2] http://wiki.apache.org/jackrabbit/Jsop
[3] https://issues.apache.org/jira/browse/OAK-103

BR,

Jukka Zitting