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]
