page improvements

Author: RichardSmedley

modules/howtos/pages/kv-operations.adoc

@@ -1,18 +1,20 @@
 = Data Operations
 :description: Data service offers the simplest way to retrieve or mutate data where the key is known.
-:page-topic-type: howto
 :page-aliases: ROOT:document-operations.adoc,ROOT:documents-creating,ROOT:documents-updating,ROOT:documents-retrieving,ROOT:documents-deleting
-:example-source: 3.2@java-sdk:howtos:example$Queries.java
+// :example-source: 3.8@java-sdk:devguide:example$java/Queries.java
 :page-toclevels: 2
 :page-pagination: full
 
-include::project-docs:partial$attributes.adoc[]
+
 
 [abstract]
 {description}
-Here we cover CRUD operations, document expiration, and optimistic locking with CAS.
+Here we cover CRUD operations, document expiration, and optimistic locking with CAS -- 
+as well as KV Range scan, for querying without an index.
+
+
 
-The complete code sample used on this page can be downloaded from https://github.com/couchbase/docs-sdk-java/blob/release/3.2/modules/howtos/examples/KvOperations.java[here].
+The complete code sample used on this page can be downloaded from https://github.com/couchbase/docs-sdk-java/blob/release/3.8/modules/devguide/examples/java/KvOperations.java[here].
 
 At its heart Couchbase Server is a high-performance key-value store, and the key-value interface outlined below is the fastest and best method to perform operations involving single documents.
 
@@ -36,7 +38,9 @@ include::devguide:example$java/KvOperations.java[tag=imports]
 {sqlpp_url}[{sqlpp} (formerly N1QL)] can also be used to perform many single-document operations but we very strongly recommend using the key-value API for this instead, as it can be much more efficient. The request can go directly to the correct node, there's no query parsing overhead, and it's over the highly optimized memcached binary protocol.
 ====
 
+
 == JSON
+
 The Couchbase Server is a key-value store that's agnostic to what's stored, but it's very common to store JSON so most of the examples below will focus on that use-case.
 
 The Java SDK provides you with several options for working with JSON.
@@ -45,7 +49,8 @@ If you pass any object (like the provided `JsonObject` and `JsonArray`), includi
 the SDK will use its internal JSON codec (utilizing https://github.com/FasterXML/jackson[Jackson]) to encode/decode those objects transparently. 
 The SDK also supports custom transcoders and serializers which are covered separately.
 
-== Upsert
+
+== CRUD
 
 [TIP]
 .Sub-Document Operations
@@ -55,6 +60,7 @@ Where the number of operations or other circumstances make bandwidth a significa
 the SDK can work on just a specific _path_ of the document with xref:subdocument-operations.adoc[Sub-Document Operations].
 ====
 
+=== Upsert
 Here is a simple upsert operation, which will insert the document if it does not exist, or replace it if it does.
 
 We'll use the built-in JSON types for simplicity, but you can use different types if you want.
@@ -77,15 +83,16 @@ include::devguide:example$java/KvOperations.java[tag=apis,indent=0]
 ----
 =====
 
-== Insert
+=== Insert
+
 Insert works very similarly to upsert, but will fail if the document already exists with a `DocumentExistsException`:
 
 [source,java]
 ----
 include::devguide:example$java/KvOperations.java[tag=insert,indent=0]
 ----
 
-== Retrieving documents
+=== Retrieving documents
 
 We've tried upserting and inserting documents into Couchbase Server, let's get them back:
 
@@ -105,7 +112,8 @@ Once we have a `GetResult`, we can use `contentAsObject()` to turn the content b
 or use the more generic `contentAs(T.class)` equivalent to turn it back into other entity structures. 
 In fact, the `contentAsObject()` method is just a convenience method for `contentAs(JsonObject.class)`.
 
-== Replace
+=== Replace
+
 A very common sequence of operations is to `get` a document, modify its contents, and `replace` it.
 
 [source,java]
@@ -129,7 +137,7 @@ See xref:concurrent-document-mutations.adoc[this detailed description of CAS] fo
 
 In general, you'll want to provide a CAS value whenever you `replace` a document, to prevent overwriting another agent's mutations.
 
-== Retrying on CAS failures
+=== Retrying on CAS failures
 
 But if we get a CAS mismatch, we usually just want to retry the operation. 
 Let's see a more advanced `replace` example that shows one way to handle this:
@@ -147,7 +155,7 @@ In later chapters we cover more sophisticated approaches to this, including asyn
 All these should be in place for robust, production ready code.
 
 
-== Removing
+=== Removing
 
 Removing a document is straightforward:
 
@@ -181,14 +189,16 @@ If 6.5 or above is being used, you can take advantage of the xref:concept-docs:d
 in which Couchbase Server will only return success to the SDK after the requested replication level has been achieved. 
 The three replication levels are:
 
- * `Majority` - The server will ensure that the change is available in memory on the majority of configured replicas.
- * `MajorityAndPersistToActive` - Majority level, plus persisted to disk on the active node.
- * `PersistToMajority` - Majority level, plus persisted to disk on the majority of configured replicas.
+ * `Majority` -- The server will ensure that the change is available in memory on the majority of configured replicas.
+ * `MajorityAndPersistToActive` -- Majority level, plus persisted to disk on the active node.
+ * `PersistToMajority` -- Majority level, plus persisted to disk on the majority of configured replicas.
 
 The options are in increasing levels of safety. 
-Note that nothing comes for free - for a given node, waiting for writes to storage is considerably slower than waiting for it to be available in-memory.
+Note that nothing comes for free -- for a given node, waiting for writes to storage is considerably slower than waiting for it to be available in-memory.
 These tradeoffs, as well as which settings may be tuned, are discussed in the xref:concept-docs:durability-replication-failure-considerations.adoc#durable-writes[durability page].
 
+// remove 6.5 stuff once 8.0 is released?
+
 If a version of Couchbase Server lower than 6.5 is being used then the application can fall-back to xref:concept-docs:durability-replication-failure-considerations.adoc#older-server-versions['client verified' durability]. 
 Here the SDK will do a simple poll of the replicas and only return once the requested durability level is achieved. 
 This can be achieved like this:
@@ -285,6 +295,8 @@ include::example$KvOperations.cs[tag=binarydecrementwithoptions,indent=0]
 ////
 NOTE: Increment & Decrement are considered part of the ‘binary’ API and as such may still be subject to change
 
+See the https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/kv/Increment.html[API Reference] for full details.
+
 TIP: Setting the document expiry time only works when a document is created, and it is not possible to update the expiry time of an existing counter document with the Increment method -- to do this during an increment, use with the `Touch()` method.
 
 
@@ -387,4 +399,4 @@ Another way of increasing network performance is to _pipeline_ operations with x
 
 As well as various xref:concept-docs:data-model.adoc[Formats] of JSON, Couchbase can work directly with xref:concept-docs:nonjson.adoc[arbitrary bytes, or binary format].
 
-Our xref:n1ql-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of {sqlpp}.
+Our xref:sqlpp-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of {sqlpp}.