- implement page buffering in PageChannel
* need to implement logical flushing in update code (startUpdate/finishUpdate)
* limit size of IndexPageCache?
-- make non-thread-safeness more explicit
+* make non-thread-safeness more explicit
- refactor free-space handlers Table/Column?
-- update index/cookbook for new api
-- add basic walk-through in class javadocs to guide users to correct classes
+* update index/cookbook for new api
+* add basic walk-through in class javadocs to guide users to correct classes
and basic getting started stuff.
* public api final cleanup:
import com.healthmarketscience.jackcess.complex.ComplexValue;
/**
- * Access database column definition
+ * Access database column definition. A {@link Table} has a list of Column
+ * instances describing the table schema.
+ * <p>
+ * A Column instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
*
* @author James Ahlborn
*/
import com.healthmarketscience.jackcess.impl.DatabaseImpl;
/**
- * Builder style class for constructing a Column.
+ * Builder style class for constructing a {@link Column}. See {@link
+ * TableBuilder} for example usage.
*
* @author James Ahlborn
*/
import com.healthmarketscience.jackcess.util.IterableBuilder;
/**
- * Manages iteration for a Table. Different cursors provide different methods
- * of traversing a table. Cursors should be fairly robust in the face of
- * table modification during traversal (although depending on how the table is
- * traversed, row updates may or may not be seen). Multiple cursors may
+ * Manages iteration for a {@link Table}. Different cursors provide different
+ * methods of traversing a table. Cursors should be fairly robust in the face
+ * of table modification during traversal (although depending on how the table
+ * is traversed, row updates may or may not be seen). Multiple cursors may
* traverse the same table simultaneously.
+ * <p/>
+ * Basic cursors will generally iterate table data in the order it appears in
+ * the database and searches will require scanning the entire table.
+ * Additional features are available when utilizing an {@link Index} backed
+ * {@link IndexCursor}.
* <p>
* The {@link CursorBuilder} provides a variety of static utility methods to
* construct cursors with given characteristics or easily search for specific
* values as well as friendly and flexible construction options.
* <p>
- * Is not thread-safe.
+ * A Cursor instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
*
* @author James Ahlborn
*/
/**
- * Builder style class for constructing a Cursor. By default, a cursor is
- * created at the beginning of the table, and any start/end rows are
+ * Builder style class for constructing a {@link Cursor}. By default, a
+ * cursor is created at the beginning of the table, and any start/end rows are
* inclusive.
+ * <p/>
+ * Simple example traversal:
+ * <pre>
+ * for(Row row : table.newCursor().toCursor()) {
+ * // ... process each row ...
+ * }
+ * </pre>
+ * <p/>
+ * Simple example search:
+ * <pre>
+ * Row row = CursorBuilder.findRow(table, Collections.singletonMap(col, "foo"));
+ * </pre>
*
* @author James Ahlborn
*/
* types of indexes do not include all entries (namely, some indexes ignore
* null entries, see {@link Index#shouldIgnoreNulls}).
*
- * @param table the table over which this cursor will traverse
* @param index index for the table which will define traversal order as
* well as enhance certain lookups
*/
- public static IndexCursor createCursor(Table table, Index index)
+ public static IndexCursor createCursor(Index index)
throws IOException
{
- return table.newCursor().setIndex(index).toIndexCursor();
+ return index.getTable().newCursor().setIndex(index).toIndexCursor();
}
/**
* types of indexes do not include all entries (namely, some indexes ignore
* null entries, see {@link Index#shouldIgnoreNulls}).
*
- * @param table the table over which this cursor will traverse
* @param index index for the table which will define traversal order as
* well as enhance certain lookups
* @param startRow the first row of data for the cursor (inclusive), or
* @param endRow the last row of data for the cursor (inclusive), or
* {@code null} for the last entry
*/
- public static IndexCursor createCursor(Table table, Index index,
+ public static IndexCursor createCursor(Index index,
Object[] startRow, Object[] endRow)
throws IOException
{
- return table.newCursor().setIndex(index)
+ return index.getTable().newCursor().setIndex(index)
.setStartRow(startRow)
.setEndRow(endRow)
.toIndexCursor();
* types of indexes do not include all entries (namely, some indexes ignore
* null entries, see {@link Index#shouldIgnoreNulls}).
*
- * @param table the table over which this cursor will traverse
* @param index index for the table which will define traversal order as
* well as enhance certain lookups
* @param startRow the first row of data for the cursor, or {@code null} for
* the last entry
* @param endInclusive whether or not endRow is inclusive or exclusive
*/
- public static IndexCursor createCursor(Table table, Index index,
+ public static IndexCursor createCursor(Index index,
Object[] startRow,
boolean startInclusive,
Object[] endRow,
boolean endInclusive)
throws IOException
{
- return table.newCursor().setIndex(index)
+ return index.getTable().newCursor().setIndex(index)
.setStartRow(startRow)
.setStartRowInclusive(startInclusive)
.setEndRow(endRow)
* Warning, this method <i>always</i> starts searching from the beginning of
* the Table (you cannot use it to find successive matches).
*
- * @param table the table to search
* @param index index to assist the search
* @param rowPattern pattern to be used to find the row
* @return the matching row or {@code null} if a match could not be found.
*/
- public static Row findRow(Table table, Index index, Map<String,?> rowPattern)
+ public static Row findRow(Index index, Map<String,?> rowPattern)
throws IOException
{
- Cursor cursor = createCursor(table, index);
+ Cursor cursor = createCursor(index);
if(cursor.findFirstRow(rowPattern)) {
return cursor.getCurrentRow();
}
* distinguishing this situation is important, you will need to use a Cursor
* directly instead of this convenience method.
*
- * @param table the table to search
* @param index index to assist the search
* @param column column whose value should be returned
* @param columnPattern column being matched by the valuePattern
* desired row
* @return the matching row or {@code null} if a match could not be found.
*/
- public static Object findValue(Table table, Index index, Column column,
+ public static Object findValue(Index index, Column column,
Column columnPattern, Object valuePattern)
throws IOException
{
- Cursor cursor = createCursor(table, index);
+ Cursor cursor = createCursor(index);
if(cursor.findFirstRow(columnPattern, valuePattern)) {
return cursor.getCurrentRowValue(column);
}
import com.healthmarketscience.jackcess.impl.JetFormat;
/**
- * Access data type
+ * Supported access data types.
+ *
* @author Tim McCune
*/
public enum DataType {
* Database has been opened, you can interact with the data via the relevant
* {@link Table}. When a Database instance is no longer useful, it should
* <b>always</b> be closed ({@link #close}) to avoid corruption.
- * <p>
- * Note, Database instances (and all the related objects) are <i>not</i>
+ * <p/>
+ * Database instances (and all the related objects) are <i>not</i>
* thread-safe. However, separate Database instances (and their respective
* objects) can be used by separate threads without a problem.
+ * <p/>
+ * Database instances do not implement any "transactional" support, and
+ * therefore concurrent editing of the same database file by multiple Database
+ * instances (or with outside programs such as MS Access) <i>will generally
+ * result in database file corruption</i>.
*
* @author James Ahlborn
* @usage _general_class_
import com.healthmarketscience.jackcess.util.MemFileChannel;
/**
- * Builder style class for opening/creating a Database.
+ * Builder style class for opening/creating a {@link Database}.
+ * <p/>
+ * Simple example usage:
+ * <pre>
+ * Database db = DatabaseBuilder.open(new File("test.mdb"));
+ * </pre>
+ * <p/>
+ * Advanced example usage:
+ * <pre>
+ * Database db = new DatabaseBuilder(new File("test.mdb"))
+ * .setReadOnly(true)
+ * .open();
+ * </pre>
*
* @author James Ahlborn
*/
*/
public boolean isUnique();
+ /**
+ * Convenience method for constructing a new CursorBuilder for this Index.
+ */
+ public CursorBuilder newCursor();
+
/**
* Information about a Column in an Index
*/
import com.healthmarketscience.jackcess.impl.IndexImpl;
/**
- * Builder style class for constructing an Index.
+ * Builder style class for constructing an {@link Index}. See {@link
+ * TableBuilder} for example usage.
*
* @author James Ahlborn
*/
import com.healthmarketscience.jackcess.util.EntryIterableBuilder;
/**
- * Cursor backed by an index with extended traversal options.
+ * Cursor backed by an {@link Index} with extended traversal options. Table
+ * traversal will be in the order defined by the backing index. Lookups which
+ * utilize the columns of the index will be fast.
*
* @author James Ahlborn
*/
import java.util.List;
/**
- * Information about a relationship between two tables in the database.
+ * Information about a relationship between two tables in the {@link
+ * Database}.
*
* @author James Ahlborn
*/
import java.util.Map;
/**
- * A row of data as column->value pairs.
+ * A row of data as column name->value pairs. Values are strongly typed, and
+ * column names are case sensitive.
*
* @author James Ahlborn
*/
import com.healthmarketscience.jackcess.util.ErrorHandler;
/**
- * A single database table. A Table instance is retrieved from a Database
- * instance. The Table instance provides access to the table metadata as well
- * as the table data. There are basic data operations on the Table interface,
- * but for advanced search and data manipulation a {@link Cursor} instance
- * should be used.
- * <p>
- * Is not thread-safe.
+ * A single database table. A Table instance is retrieved from a {@link
+ * Database} instance. The Table instance provides access to the table
+ * metadata as well as the table data. There are basic data operations on the
+ * Table interface (i.e. {@link #iterator} {@link #addRow}, {@link #updateRow}
+ * and {@link #deleteRow}), but for advanced search and data manipulation a
+ * {@link Cursor} instance should be used. New Tables can be created using a
+ * {@link TableBuilder}.
+ * <p/>
+ * A Table instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
*
* @author James Ahlborn
* @usage _general_class_
import com.healthmarketscience.jackcess.impl.DatabaseImpl;
/**
- * Builder style class for constructing a Column.
+ * Builder style class for constructing a {@link Table}.
+ * <p/>
+ * Example:
+ * <pre>
+ * Table table = new TableBuilder("Test")
+ * .addColumn(new ColumnBuilder("ID", DataType.LONG)
+ * .setAutoNumber(true))
+ * .addColumn(new ColumnBuilder("Name", DataType.TEXT))
+ * .addIndex(new IndexBuilder(IndexBuilder.PRIMARY_KEY_NAME)
+ * .addColumns("ID").setPrimaryKey())
+ * .toTable(db);
+ * </pre>
*
* @author James Ahlborn
*/
DatabaseImpl db = column.getDatabase();
TableImpl complexColumns = db.getSystemComplexColumns();
IndexCursor cursor = CursorBuilder.createCursor(
- complexColumns, complexColumns.getPrimaryKeyIndex());
+ complexColumns.getPrimaryKeyIndex());
if(!cursor.findFirstRowByEntry(complexTypeId)) {
throw new IOException(
"Could not find complex column info for complex column with id " +
@Override
protected Cursor getTableNamesCursor() throws IOException {
- return _systemCatalog.newCursor()
- .setIndex(_systemCatalogCursor.getIndex())
+ return _systemCatalogCursor.getIndex().newCursor()
.setStartEntry(_tableParentId, IndexData.MIN_VALUE)
.setEndEntry(_tableParentId, IndexData.MAX_VALUE)
.toIndexCursor();
import java.util.List;
import java.util.Map;
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
+import com.healthmarketscience.jackcess.CursorBuilder;
import com.healthmarketscience.jackcess.Index;
-import com.healthmarketscience.jackcess.RowId;
import com.healthmarketscience.jackcess.IndexBuilder;
+import com.healthmarketscience.jackcess.RowId;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
/**
* Access table (logical) index. Logical indexes are backed for IndexData,
return getIndexData().getColumns();
}
+ public CursorBuilder newCursor() {
+ return getTable().newCursor().setIndex(this);
+ }
+
/**
* Whether or not the complete index state has been read.
*/
throws IOException
{
Index toIndex = fromIndex.getReferencedIndex();
- IndexCursor toCursor = CursorBuilder.createCursor(
- toIndex.getTable(), toIndex);
+ IndexCursor toCursor = CursorBuilder.createCursor(toIndex);
// text lookups are always case-insensitive
toCursor.setColumnMatcher(CaseInsensitiveColumnMatcher.INSTANCE);
return new Joiner(fromIndex, toCursor);
String prevValue = firstValue;
int rowCount = 0;
List<String> firstTwo = new ArrayList<String>();
- for(Map<String,Object> row : CursorBuilder.createCursor(t, index)) {
+ for(Map<String,Object> row : CursorBuilder.createCursor(index)) {
String origVal = (String)row.get("col1");
String val = origVal;
if(val == null) {
index.getIndexData().validate();
// delete an entry in the middle
- Cursor cursor = CursorBuilder.createCursor(t, index);
+ Cursor cursor = CursorBuilder.createCursor(index);
for(int i = 0; i < (rowCount / 2); ++i) {
assertTrue(cursor.moveToNextRow());
}
index.getIndexData().validate();
List<String> found = new ArrayList<String>();
- for(Map<String,Object> row : CursorBuilder.createCursor(t, index)) {
+ for(Map<String,Object> row : CursorBuilder.createCursor(index)) {
found.add((String)row.get("col1"));
}
index.getIndexData().validate();
- cursor = CursorBuilder.createCursor(t, index);
+ cursor = CursorBuilder.createCursor(index);
while(cursor.moveToNextRow()) {
cursor.deleteCurrentRow();
}
Cursor found = new CursorBuilder(table).toCursor();
assertCursor(expected, found);
- expected = CursorBuilder.createCursor(table, idx);
+ expected = CursorBuilder.createCursor(idx);
found = new CursorBuilder(table)
.setIndex(idx)
.toCursor();
assertCursor(expected, found);
- expected = CursorBuilder.createCursor(table, idx);
+ expected = CursorBuilder.createCursor(idx);
found = new CursorBuilder(table)
.setIndexByName("id")
.toCursor();
// success
}
- expected = CursorBuilder.createCursor(table, idx);
+ expected = CursorBuilder.createCursor(idx);
found = new CursorBuilder(table)
.setIndexByColumns(table.getColumn("id"))
.toCursor();
.toCursor();
assertCursor(expected, found);
- expected = CursorBuilder.createCursor(table, idx);
+ expected = CursorBuilder.createCursor(idx);
expected.moveNextRows(2);
sp = expected.getSavepoint();
found = new CursorBuilder(table)
.toCursor();
assertCursor(expected, found);
- expected = CursorBuilder.createCursor(table, idx,
+ expected = CursorBuilder.createCursor(idx,
idx.constructIndexRowFromEntry(3),
null);
found = new CursorBuilder(table)
.toCursor();
assertCursor(expected, found);
- expected = CursorBuilder.createCursor(table, idx,
+ expected = CursorBuilder.createCursor(idx,
idx.constructIndexRowFromEntry(3),
false,
idx.constructIndexRowFromEntry(7),
createExpectedRow("id", 5)));
if(index != null) {
assertEquals("data" + 5,
- CursorBuilder.findValue(table, index,
+ CursorBuilder.findValue(index,
table.getColumn("value"),
table.getColumn("id"), 5));
assertEquals(createExpectedRow("id", 5,
"value", "data" + 5),
- CursorBuilder.findRow(table, index,
+ CursorBuilder.findRow(index,
createExpectedRow("id", 5)));
- assertNull(CursorBuilder.findValue(table, index,
+ assertNull(CursorBuilder.findValue(index,
table.getColumn("value"),
table.getColumn("id"),
-17));
- assertNull(CursorBuilder.findRow(table, index,
+ assertNull(CursorBuilder.findRow(index,
createExpectedRow("id", 13)));
}
}
assertTable(createUnorderedTestTableData(), table);
- Cursor cursor = CursorBuilder.createCursor(table, idx);
+ Cursor cursor = CursorBuilder.createCursor(idx);
doTestSimple(cursor, null);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor = CursorBuilder.createCursor(table, idx);
+ Cursor cursor = CursorBuilder.createCursor(idx);
doTestMove(cursor, null);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor = CursorBuilder.createCursor(table, idx);
+ Cursor cursor = CursorBuilder.createCursor(idx);
doTestReverse(cursor, null);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor = CursorBuilder.createCursor(table, idx);
+ Cursor cursor = CursorBuilder.createCursor(idx);
doTestSearch(table, cursor, idx, 42, -13);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor1 = CursorBuilder.createCursor(table, idx);
- Cursor cursor2 = CursorBuilder.createCursor(table, idx);
+ Cursor cursor1 = CursorBuilder.createCursor(idx);
+ Cursor cursor2 = CursorBuilder.createCursor(idx);
doTestLiveAddition(table, cursor1, cursor2, 11);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor1 = CursorBuilder.createCursor(table, idx);
- Cursor cursor2 = CursorBuilder.createCursor(table, idx);
- Cursor cursor3 = CursorBuilder.createCursor(table, idx);
- Cursor cursor4 = CursorBuilder.createCursor(table, idx);
+ Cursor cursor1 = CursorBuilder.createCursor(idx);
+ Cursor cursor2 = CursorBuilder.createCursor(idx);
+ Cursor cursor3 = CursorBuilder.createCursor(idx);
+ Cursor cursor4 = CursorBuilder.createCursor(idx);
doTestLiveDeletion(cursor1, cursor2, cursor3, cursor4, 1);
db.close();
Table table = db.getTable("test");
Index idx = table.getIndexes().get(0);
- Cursor cursor = CursorBuilder.createCursor(table, idx);
+ Cursor cursor = CursorBuilder.createCursor(idx);
doTestFindAll(table, cursor, idx);
Index idx = table.getIndexes().get(0);
Cursor tCursor = CursorBuilder.createCursor(table);
- Cursor iCursor = CursorBuilder.createCursor(table, idx);
+ Cursor iCursor = CursorBuilder.createCursor(idx);
Cursor.Savepoint tSave = tCursor.getSavepoint();
Cursor.Savepoint iSave = iCursor.getSavepoint();
}
Cursor tCursor2 = CursorBuilder.createCursor(table);
- Cursor iCursor2 = CursorBuilder.createCursor(table, idx);
+ Cursor iCursor2 = CursorBuilder.createCursor(idx);
tCursor2.restoreSavepoint(tSave);
iCursor2.restoreSavepoint(iSave);
Database db = open(testDB);
Table t1 = db.getTable("Table1");
Index idx = t1.getIndex(IndexBuilder.PRIMARY_KEY_NAME);
- IndexCursor cursor = CursorBuilder.createCursor(t1, idx);
+ IndexCursor cursor = CursorBuilder.createCursor(idx);
assertFalse(cursor.findFirstRowByEntry(-1));
cursor.findClosestRowByEntry(-1);
Database db = openCopy(testDB);
Table t1 = db.getTable("Table1");
Index idx = t1.getIndex("Table2Table1");
- IndexCursor cursor = CursorBuilder.createCursor(t1, idx);
+ IndexCursor cursor = CursorBuilder.createCursor(idx);
List<String> expectedData = new ArrayList<String>();
for(Map<String,Object> row : cursor.newEntryIterable(1)
assertEquals(origI.getIndexData().getEntryCount(),
tempI.getIndexData().getEntryCount());
- Cursor origC = CursorBuilder.createCursor(orig, origI);
- Cursor tempC = CursorBuilder.createCursor(temp, tempI);
+ Cursor origC = origI.newCursor().toCursor();
+ Cursor tempC = tempI.newCursor().toCursor();
while(true) {
boolean origHasNext = origC.moveToNextRow();
// index.initialize();
// System.out.println("Ind " + index);
- Cursor cursor = CursorBuilder.createCursor(t, index);
+ Cursor cursor = CursorBuilder.createCursor(index);
while(cursor.moveToNextRow()) {
Map<String,Object> row = cursor.getCurrentRow();
throws Exception
{
Object[] idxRow = ((IndexImpl)index).constructIndexRow(expectedRow);
- Cursor cursor = CursorBuilder.createCursor(t, index, idxRow, idxRow);
+ Cursor cursor = CursorBuilder.createCursor(index, idxRow, idxRow);
Cursor.Position startPos = cursor.getSavepoint().getCurrentPosition();
System.out.println("Ind " + ind);
- Cursor cursor = CursorBuilder.createCursor(t, ind);
+ Cursor cursor = CursorBuilder.createCursor(ind);
while(cursor.moveToNextRow()) {
System.out.println("=======");
String entryStr =
((IndexImpl)index).initialize();
System.out.println("Ind " + index);
- Cursor cursor = CursorBuilder.createCursor(t, index);
+ Cursor cursor = CursorBuilder.createCursor(index);
while(cursor.moveToNextRow()) {
System.out.println("=======");
System.out.println("Savepoint: " + cursor.getSavepoint());
Map<Character,String[]> inat2CrazyCodes = new TreeMap<Character,String[]>();
- Cursor cursor = CursorBuilder.createCursor(t, index);
+ Cursor cursor = CursorBuilder.createCursor(index);
while(cursor.moveToNextRow()) {
// System.out.println("=======");
// System.out.println("Savepoint: " + cursor.getSavepoint());
Map<Character,String[]> inat2CrazyCodes = new TreeMap<Character,String[]>();
- Cursor cursor = CursorBuilder.createCursor(t, index);
+ Cursor cursor = CursorBuilder.createCursor(index);
while(cursor.moveToNextRow()) {
// System.out.println("=======");
// System.out.println("Savepoint: " + cursor.getSavepoint());
projects / jackcess.git / commitdiff