git commit: ACCUMULO-1957 add a durability section to the user manual

[ec...@apache.org]

Repository: accumulo
Updated Branches:
  refs/heads/master ac270044a -> 3296dab1b


ACCUMULO-1957 add a durability section to the user manual


Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/3296dab1
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/3296dab1
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/3296dab1

Branch: refs/heads/master
Commit: 3296dab1b3cbbe0d486e43fdccfe9c5d55a15e78
Parents: ac27004
Author: Eric C. Newton <er...@gmail.com>
Authored: Tue Sep 9 13:20:17 2014 -0400
Committer: Eric C. Newton <er...@gmail.com>
Committed: Tue Sep 9 13:20:17 2014 -0400

----------------------------------------------------------------------
 docs/src/main/asciidoc/chapters/clients.txt | 33 ++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/accumulo/blob/3296dab1/docs/src/main/asciidoc/chapters/clients.txt
----------------------------------------------------------------------
diff --git a/docs/src/main/asciidoc/chapters/clients.txt b/docs/src/main/asciidoc/chapters/clients.txt
index 48123a3..a0c74a5 100644
--- a/docs/src/main/asciidoc/chapters/clients.txt
+++ b/docs/src/main/asciidoc/chapters/clients.txt
@@ -140,6 +140,39 @@ information within a row.
 An example of using the batch writer can be found at
 +accumulo/docs/examples/README.reservations+.
 
+==== Durability
+
+By default, Accumulo writes out any updates to the Write-Ahead Log (WAL). Every change
+goes into a file in HDFS and is sync'd to disk for maximum durability. In
+the event of a failure, writes held in memory are replayed from the WAL. Like
+all files in HDFS, this file is also replicated. Sending updates to the
+replicas, and waiting for a permanent sync to disk can significantly write speeds.
+
+Accumulo allows users to use less tolerant forms of durability when writing.
+These levels are:
+
+* none: no durability guarantees are made, the WAL is not used
+* log: the WAL is used, but not flushed; loss of the server probably means recent writes are lost
+* flush: updates are written to the WAL, and flushed out to replicas; loss of a single server is unlikely to result in data loss.
+* sync: updates are written to the WAL, and synced to disk on all replicas before the write is acknowledge. Data will not be lost even if the entire cluster suddenly loses power.
+
+The user can set the default durability of a table in the shell.  When
+writing, the user can configure the BatchWriter or ConditionalWriter to use
+a different level of durability for the session. This will override the
+default durability setting.
+
+[source,java]
+----
+BatchWriterConfig cfg = new BatchWriterConfig();
+// We don't care about data loss with these writes:
+// This is DANGEROUS:
+cfg.setDurability(Durability.NONE);
+
+Connection conn = ... ;
+BatchWriter bw = conn.createBatchWriter(table, cfg);
+
+----
+
 === Reading Data
 
 Accumulo is optimized to quickly retrieve the value associated with a given key, and