diff options
author | James Ahlborn <jtahlborn@yahoo.com> | 2014-05-01 03:18:37 +0000 |
---|---|---|
committer | James Ahlborn <jtahlborn@yahoo.com> | 2014-05-01 03:18:37 +0000 |
commit | e24827b6e8e5f500501245e65349823445d20ddb (patch) | |
tree | 3dffddefc134a4e7067331f5556a33bbbf56b40e /src/site/xdoc | |
parent | 6058071abded03b6b33615d619c50c527245795d (diff) | |
download | jackcess-e24827b6e8e5f500501245e65349823445d20ddb.tar.gz jackcess-e24827b6e8e5f500501245e65349823445d20ddb.zip |
add some more cookbook content
git-svn-id: https://svn.code.sf.net/p/jackcess/code/jackcess/trunk@857 f203690c-595d-4dc9-a70b-905162fa7fd2
Diffstat (limited to 'src/site/xdoc')
-rw-r--r-- | src/site/xdoc/cookbook.xml | 79 |
1 files changed, 79 insertions, 0 deletions
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> |