From e24827b6e8e5f500501245e65349823445d20ddb Mon Sep 17 00:00:00 2001
From: James Ahlborn <jtahlborn@yahoo.com>
Date: Thu, 1 May 2014 03:18:37 +0000
Subject: [PATCH] add some more cookbook content

git-svn-id: https://svn.code.sf.net/p/jackcess/code/jackcess/trunk@857 f203690c-595d-4dc9-a70b-905162fa7fd2
---
 pom.xml                    |  6 +++
 src/site/xdoc/cookbook.xml | 79 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/pom.xml b/pom.xml
index 47076af..3b4ef79 100644
--- a/pom.xml
+++ b/pom.xml
@@ -88,6 +88,12 @@
         <role>Reverse engineered the attachment data encoding.</role>
       </roles>
     </contributor>
+    <contributor>
+      <name>Gordon Thompson</name>
+      <roles>
+        <role>Contributed to cookbook.</role>
+      </roles>
+    </contributor>
   </contributors>
   <issueManagement>
     <system>SourceForge2</system>
diff --git a/src/site/xdoc/cookbook.xml b/src/site/xdoc/cookbook.xml
index 8752425..6f13d27 100644
--- a/src/site/xdoc/cookbook.xml
+++ b/src/site/xdoc/cookbook.xml
@@ -283,6 +283,85 @@
           speed and memory, they are "lightweight" enough to be used in an
           on-demand capacity.
         </p>
+        <p>
+          The simplest case involves a normal, un-indexed cursor for a given
+          table. The cursor will traverse the table in no particular row order
+          but it can still be used to find rows where column(s) match
+          specified values. For example...
+        </p>
+<source>
+  Table table = db.getTable("Test");
+  Cursor cursor = CursorBuilder.createCursor(table);
+  boolean found = cursor.findFirstRow(Collections.singletonMap("ID", 1));
+  if (found) {
+      System.out.println(String.format("Row found: Name = '%s'.",
+                                     cursor.getCurrentRowValue(table.getColumn("Name"))));
+  } else {
+      System.out.println("No matching row was found.");
+  }
+</source>
+        <p>
+          ...will search for the row where <code>"ID" == 1</code>. Since the
+          cursor does not use an index it will perform the equivalent of a
+          "table scan" while searching.
+        </p>
+        <p>
+          Cursors can also use an existing index on the table to (1) control
+          the order in which they traverse the table, and (2) find rows
+          faster. Since we defined the "ID" column as our Primary Key we can
+          also perform the above search like this...
+        </p>
+<source>     
+  Table table = db.getTable("Test");
+  IndexCursor cursor = CursorBuilder.createCursor(table.getPrimaryKeyIndex());
+  boolean found = cursor.findFirstRow(Collections.singletonMap("ID", 1));
+  // ... proceed as in previous example ...
+</source>
+        <p>
+            ...or by using the <code>CursorBuilder.findRowByPrimaryKey</code>
+            "convenience method" like this:
+        </p>
+<source>     
+  Table table = db.getTable("Test");
+  Row row = CursorBuilder.findRowByPrimaryKey(table, 1);
+  if (row != null) {
+      System.out.println(String.format("Row found: Name = '%s'.",
+                                     row.get("Name")));
+  } else {
+      System.out.println("No matching row was found.");
+  }
+</source>
+        <p>
+          Either of the two previous approaches will use the Primary Key index
+          to locate the row where <code>"ID" == 1</code>, potentially making
+          it much faster to execute.
+        </p>
+        <p>  
+          As mentioned above, an index-backed cursor will also retrieve rows
+          in index order, so if we wanted to retrieve all of the rows in
+          alphabetical order by <code>"Name"</code> we could use the
+          "NameIndex" index to create a cursor and then iterate through the
+          rows like this:
+        </p>
+<source>     
+  Table table = db.getTable("Test");
+  IndexCursor cursor = CursorBuilder.createCursor(table.getIndex("NameIndex"));
+  for(Row row : cursor) {
+    System.out.println(String.format("ID=%d, Name='%s'.",
+                                     row.get("ID"), row.get("Name")));
+  }
+</source>
+        <p>     
+          Or, if you wanted to iterate through all of the rows where
+          <code>"Name" == 'bob'</code> you could do:
+        </p>
+<source>     
+  Table table = db.getTable("Test");                                                                        
+  IndexCursor cursor = CursorBuilder.createCursor(table.getIndex("NameIndex"));                             
+  for(Row row : cursor.newEntryIterable("bob")) {
+    System.out.println(String.format("ID=%d, Name='%s'.", row.get("ID"), row.get("Name")));
+  }
+</source>
       </subsection>
 
       <p>
-- 
2.39.5