From e24827b6e8e5f500501245e65349823445d20ddb Mon Sep 17 00:00:00 2001 From: James Ahlborn Date: Thu, 1 May 2014 03:18:37 +0000 Subject: add some more cookbook content git-svn-id: https://svn.code.sf.net/p/jackcess/code/jackcess/trunk@857 f203690c-595d-4dc9-a70b-905162fa7fd2 --- src/site/xdoc/cookbook.xml | 79 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) (limited to 'src/site/xdoc') 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.

+

+ 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... +

+ + 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."); + } + +

+ ...will search for the row where "ID" == 1. Since the + cursor does not use an index it will perform the equivalent of a + "table scan" while searching. +

+

+ 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... +

+ + Table table = db.getTable("Test"); + IndexCursor cursor = CursorBuilder.createCursor(table.getPrimaryKeyIndex()); + boolean found = cursor.findFirstRow(Collections.singletonMap("ID", 1)); + // ... proceed as in previous example ... + +

+ ...or by using the CursorBuilder.findRowByPrimaryKey + "convenience method" like this: +

+ + 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."); + } + +

+ Either of the two previous approaches will use the Primary Key index + to locate the row where "ID" == 1, potentially making + it much faster to execute. +

+

+ 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 "Name" we could use the + "NameIndex" index to create a cursor and then iterate through the + rows like this: +

+ + 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"))); + } + +

+ Or, if you wanted to iterate through all of the rows where + "Name" == 'bob' you could do: +

+ + 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"))); + } +

-- cgit v1.2.3