jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r1531387 - in /jackrabbit/oak/trunk: oak-http/README.md oak-run/README.md
Date Fri, 11 Oct 2013 18:43:33 GMT
Author: jukka
Date: Fri Oct 11 18:43:32 2013
New Revision: 1531387

URL: http://svn.apache.org/r1531387
Log:
OAK-104: HTTP bindings for Oak

Initial documentation of the Oak HTTP bindings

Added:
    jackrabbit/oak/trunk/oak-http/README.md
Modified:
    jackrabbit/oak/trunk/oak-run/README.md

Added: jackrabbit/oak/trunk/oak-http/README.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-http/README.md?rev=1531387&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-http/README.md (added)
+++ jackrabbit/oak/trunk/oak-http/README.md Fri Oct 11 18:43:32 2013
@@ -0,0 +1,86 @@
+Oak HTTP binding
+================
+
+This is a simple JavaScript- and browser-friendly HTTP binding for Oak.
+It makes it possible to access and modify content in an Oak repository
+remotely via the HTTP protocol.
+
+The easiest way to try out this binding is to start an in-memory repository
+using the `oak-run` jar:
+
+    $ java -jar oak-run/target/oak-run-*.jar
+
+The resulting reposistory is made available at http://localhost:8080/.
+The following examples use the httpie client to perform simple CRUD operations.
+The username and password (by default `admin` and `admin`) have been specified
+in the `~/.netrc` file so they are not included on the command lines.
+
+    $ http -j -b localhost:8080
+    {
+        "jcr:primaryType": "rep:root",
+        "jcr:system": {},
+        "oak:index": {},
+        "rep:security": {}
+    }
+
+You can add or modify content by posting JSON:
+
+    $ http -j -b localhost:8080/test \
+          jcr\\:primaryType=oak:unstructured foo=abc bar:=123
+    {
+        "bar": "123",
+        "foo": "abc",
+        "jcr:primaryType": "oak:unstructured"
+    }
+
+The `jcr:primaryType` property needs to currently be included to avoid
+JCR constraint violations. The intention is to automatically infer the
+value if not explicitly included. Note also how the first colon needs to
+be escaped on the command line to prevent httpie from interpreting te
+argument as an extra HTTP header.
+
+The posted content is stored in the repository and is now accessible:
+
+    $ http -j -b localhost:8080
+    {
+        "jcr:primaryType": "rep:root",
+        "jcr:system": {},
+        "oak:index": {},
+        "rep:security": {},
+        "test": {}
+    }
+
+    $ http -j -b localhost:8080/test
+    {
+        "bar": "123",
+        "foo": "abc",
+        "jcr:primaryType": "oak:unstructured"
+    }
+
+You can modify the content by posting more data to the same URL:
+
+    $ http -j -b localhost:8080/test \
+          foo=xyz child:='{"jcr:primaryType": "oak:unstructured"}'
+    {
+        "bar": "123",
+        "child": {},
+        "foo": "xyz",
+        "jcr:primaryType": "nt:unstructured"
+    }
+
+    $ http -j -b localhost:8080/test/child
+    {
+        "jcr:primaryType": "oak:unstructured"
+    }
+
+Finally, content can be removed either by posting a null value to it
+or by using DELETE:
+
+    $ http -j -b localhost:8080/test bar:=null child:=null
+    {
+        "foo": "xyz",
+        "jcr:primaryType": "nt:unstructured"
+    }
+
+    $ http -j -h DELETE localhost:8080/test
+    HTTP/1.1 200 OK

Modified: jackrabbit/oak/trunk/oak-run/README.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-run/README.md?rev=1531387&r1=1531386&r2=1531387&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-run/README.md (original)
+++ jackrabbit/oak/trunk/oak-run/README.md Fri Oct 11 18:43:32 2013
@@ -1,16 +1,55 @@
 Oak Runnable Jar
 ================
 
-Standalone server mode
-----------------------
+This jar contains everything you need for a simple Oak installation.
+The following three runmodes are available:
 
-TODO
+    * Oak server
+    * MicroKernel server
+    * benchmark
+
+See the subsections below for more details on how to use these modes.
+
+Oak server mode
+---------------
+
+The Oak server mode starts a full Oak instance with the standard JCR plugins
+and makes it available over a simple HTTP mapping defined in the `oak-http`
+component. To start this mode, use:
+
+    $ java -jar oak-run-*.jar [/path/to/mk...]
+
+If no arguments are specified, the command starts an in-memory repository
+and makes it available at http://localhost:8080/. Possible path arguments
+specify the locations of on-disk MicroKernel backends that are each opened
+and mapped to URLs under http://localhost:8080/.
+
+See the documentation in the `oak-http` component for details about the
+available functionality.
+
+MicroKernel server mode
+-----------------------
+
+The MicroKernel server mode starts a MicroKernel instance and makes it
+available over HTTP mapping defined in the `oak-mk-remote` component.
+To start this mode, use:
+
+    $ java -jar oak-run-*.jar mk /path/to/mk [port] [bindaddr]
+
+The given path specific the directory that contains the MicroKernel backend.
+The optional `port` and `bindaddr` arguments can be used to control the
+address of the HTTP mapping.
+
+The resulting web interface at http://localhost:8080/ (with default
+`bindaddr` and `port` values) maps simple HTTP forms to the respective
+MicroKernel methods. See the javadocs of the MicroKernel interface for
+more details.
 
 Benchmark mode
 --------------
 
-The oak-run jar has a "benchmark" mode for executing various micro-benchmarks.
-It can be invoked like this:
+The benchmark mode is used for executing various micro-benchmarks. It can
+be invoked like this:
 
     $ java -jar oak-run-*.jar benchmark [options] [testcases] [fixtures]
 



Mime
View raw message