Author: davide
Date: Wed Jan 20 12:01:03 2016
New Revision: 1725705
URL: http://svn.apache.org/viewvc?rev=1725705&view=rev
Log:
OAK-3894 - Atomic counter documentation
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/
jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/atomic-counter.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/site.xml
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/atomic-counter.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/atomic-counter.md?rev=1725705&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/atomic-counter.md
(added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/features/atomic-counter.md
Wed Jan 20 12:01:03 2016
@@ -0,0 +1,138 @@
+## Atomic Counter
+`@since 1.3.0 (stand-alone) , 1.3.14 (full cluster support)`
+
+### Overview
+
+The atomic counter functionality aims to address the need of use cases
+like _votes_, _likes_, _+1s_ and so on. It will make sure you'll
+eventually have a consistent and correct account of the
+sums/subtractions of all the increments.
+
+When you set a specific node type (`mix:atomicCounter`) to any node,
+you'll have a protected property, `oak:counter` that will hold the
+count of your votes.
+
+To perform an increment or decrement you'll have to set a specific
+property of type `Long`: `oak:increment`. See later on in the
+[usage section](#Usage).
+
+#### Stand-alone, synchronous
+
+When running on stand-alone configurations, like Segment, the actual
+increase of the `oak:counter` property will happen synchronously, in
+the same space of the commit. Therefore it will always reflect an up
+to date value.
+
+#### Clustered, asynchronous
+
+When running on clustered solutions, or potential one, like on
+DocumentMK the actual increase of the `oak:counter` property will
+happen asynchronously. Therefore the value displayed by `oak:counter`
+could not be up to date and lagging behind of some time. This is for
+dealing with conflicts that could happen when updating the same
+properties across the cluster and for scaling without having to deal
+with any global locking system.
+
+##### Constraints
+
+For the clustered solution, in order to have the asynchronous
+behaviour enabled you **have to provide** a
+`org.apache.jackrabbit.oak.spi.state.Clusterable` and a
+`java.util.concurrent.ScheduledExecutorService`. If any of these are
+null it will fall back to a synchronous behaviour.
+
+It will fall back to synchronous as well if no
+`org.apache.jackrabbit.oak.spi.whiteboard.Whiteboard` is provided or
+the provided commit hooks during repository constructions are not
+registered with the whiteboard itself. These are done automatically by
+the default Oak repository constructions, so other that you customise
+further no actions should be needed.
+
+### Enabling the feature (Repository Construction)
+#### Plain Java
+
+##### Stand-alone
+
+ NodeStore store = ... //store instantiation
+ Jcr jcr = new Jcr(store).withAtomicCounter();
+ Repository repo = jcr.createContentRepository();
+
+##### Clustered
+
+ NodeStore store = ... //store instantiation
+
+ // DocumentNodeStore implements such aspect therefore it could be
+ // something like: `(Clusterable) store`. Casting the store into
+ // Clusterable.
+ Clusterable clusterable = ...
+
+ // you have to provide a ScheduledExecutorService which you'll
+ // have to take care of shutting it down properly during
+ // repository shutdown.
+ ScheduledExecutorService executor = ...
+
+ Jcr jcr = new Jcr(store)
+ .with(clusterable)
+ .with(executor)
+ .withAtomicCounter();
+
+ Repository repo = jcr.createContentRepository();
+
+#### OSGi
+
+##### Stand-alone and Clustered
+
+ @Reference(target = "(type=atomicCounter)")
+ private EditorProvider atomicCounter;
+
+ ...
+
+ NodeStore store = ...
+ Jcr jcr = new Jcr(store);
+ jcr.with(atomicCounter);
+
+ ...
+
+When running on clustered environment the `EditorProvider` expect to
+find a service of type
+`org.apache.jackrabbit.oak.spi.state.Clusterable` and
+`org.apache.jackrabbit.oak.spi.state.NodeStore`. `DocumentNodeStore`
+already register itself as `Clusterable`. If one of the two won't be
+available it will fall back to synchronous behaviour.
+
+### Usage
+
+ Session session = ...
+
+ // creating a counter node
+ Node counter = session.getRootNode().addNode("mycounter");
+ counter.addMixin("mix:atomicCounter"); // or use the NodeTypeConstants
+ session.save();
+
+ // Will output 0. the default value
+ System.out.println("counter now: " +
counter.getProperty("oak:counter").getLong());
+
+ // incrementing by 5 the counter
+ counter.setProperty("oak:increment", 5);
+ session.save();
+
+ // Will output 5
+ System.out.println("counter now: " +
counter.getProperty("oak:counter").getLong());
+
+ // decreasing by 1
+ counter.setProperty("oak:increment", -1);
+ session.save();
+
+ // Will output 4
+ System.out.println("counter now: " +
counter.getProperty("oak:counter").getLong());
+
+ session.logout();
+
+### Debug
+
+If you're experiencing any problems with the counter you can start
+analysing the situation by setting to `DEBUG` log appender
+`org.apache.jackrabbit.oak.plugins.atomic`.
+
+If set to `TRACE` even more information will be provided.
+
Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1725705&r1=1725704&r2=1725705&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Wed Jan 20 12:01:03 2016
@@ -38,14 +38,15 @@ under the License.
<item href="oak_api/overview.html" name="Oak API" />
</menu>
<menu name="Features and Plugins">
- <item href="nodestore/overview.html" name="Node Storage" />
+ <item href="features/atomic-counter.html" name="Atomic Counter" />
<item href="plugins/blobstore.html" name="Blob Storage" />
+ <item href="clustering.html" name="Clustering" />
<item href="nodestore/documentmk.html" name="DocumentNodeStore" />
- <item href="nodestore/segment/overview.html" name="Segment Node Store" />
+ <item href="nodestore/overview.html" name="Node Storage" />
+ <item href="nodestore/persistent-cache.html" name="Persistent Cache" />
<item href="query/query.html" name="Query" />
<item href="security/overview.html" name="Security" />
- <item href="clustering.html" name="Clustering" />
- <item href="nodestore/persistent-cache.html" name="Persistent Cache" />
+ <item href="nodestore/segment/overview.html" name="Segment Node Store" />
</menu>
<menu name="Using Oak">
<item href="use_getting_started.html" name="Getting Started" />
