зеркало из https://github.com/mozilla/gecko-dev.git
315 строки
16 KiB
Java
315 строки
16 KiB
Java
/* -*- Mode: java; indent-tabs-mode: nil; c-basic-offset: 2 -*-
|
|
*
|
|
* The contents of this file are subject to the Mozilla Public License
|
|
* Version 1.0 (the "License"); you may not use this file except in
|
|
* compliance with the License. You may obtain a copy of the License at
|
|
* http://www.mozilla.org/MPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS IS"
|
|
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
|
|
* the License for the specific language governing rights and limitations
|
|
* under the License.
|
|
*
|
|
* The Original Code is the Grendel mail/news client.
|
|
*
|
|
* The Initial Developer of the Original Code is Netscape Communications
|
|
* Corporation. Portions created by Netscape are Copyright (C) 1997
|
|
* Netscape Communications Corporation. All Rights Reserved.
|
|
*
|
|
* Created: Mauro Botelho <mabotelh@email.com>, 20 Mar 1999.
|
|
*/
|
|
|
|
package grendel.storage.mdb;
|
|
|
|
/*| nsIMdbTable: an ordered collection of rows
|
|
**|
|
|
**|| row scope: an integer token for an atomized string in this database
|
|
**| that names a space for row IDs. This attribute of a table is intended
|
|
**| as guidance metainformation that helps with searching a database for
|
|
**| tables that operate on collections of rows of the specific type. By
|
|
**| convention, a table with a specific row scope is expected to focus on
|
|
**| containing rows that belong to that scope, however exceptions are easily
|
|
**| allowed because all rows in a table are known by both row ID and scope.
|
|
**| (A table with zero row scope is never allowed because this would make it
|
|
**| ambiguous to use a zero row scope when iterating over tables in a port to
|
|
**| indicate that all row scopes should be seen by a cursor.)
|
|
**|
|
|
**|| table kind: an integer token for an atomized string in this database
|
|
**| that names a kind of table as a subset of the associated row scope. This
|
|
**| attribute is intended as guidance metainformation to clarify the role of
|
|
**| this table with respect to other tables in the same row scope, and this
|
|
**| also helps search for such tables in a database. By convention, a table
|
|
**| with a specific table kind has a consistent role for containing rows with
|
|
**| respect to other collections of such rows in the same row scope. Also by
|
|
**| convention, at least one table in a row scope has a table kind purporting
|
|
**| to contain ALL the rows that belong in that row scope, so that at least
|
|
**| one table exists that allows all rows in a scope to be interated over.
|
|
**| (A table with zero table kind is never allowed because this would make it
|
|
**| ambiguous to use a zero table kind when iterating over tables in a port to
|
|
**| indicate that all table kinds in a row scope should be seen by a cursor.)
|
|
**|
|
|
**|| port: every table is considered part of some port that contains the
|
|
**| table, so that closing the containing port will cause the table to be
|
|
**| indirectly closed as well. We make it easy to get the containing port for
|
|
**| a table, because the port supports important semantic interfaces that will
|
|
**| affect how content in table is presented; the most important port context
|
|
**| that affects a table is specified by the set of token to string mappings
|
|
**| that affect all tokens used throughout the database, and which drive the
|
|
**| meanings of row scope, table kind, cell columns, etc.
|
|
**|
|
|
**|| cursor: a cursor that iterates over the rows in this table, where rows
|
|
**| have zero-based index positions from zero to count-1. Making a cursor
|
|
**| with negative position will next iterate over the first row in the table.
|
|
**|
|
|
**|| position: given any position from zero to count-1, a table will return
|
|
**| the row ID and row scope for the row at that position. (One can use the
|
|
**| GetRowAllCells() method to read that row, or else use a row cursor to both
|
|
**| get the row at some position and read its content at the same time.) The
|
|
**| position depends on whether a table is sorted, and upon the actual sort.
|
|
**| Note that moving a row's position is only possible in unsorted tables.
|
|
**|
|
|
**|| row set: every table contains a collection of rows, where a member row is
|
|
**| referenced by the table using the row ID and row scope for the row. No
|
|
**| single table owns a given row instance, because rows are effectively ref-
|
|
**| counted and destroyed only when the last table removes a reference to that
|
|
**| particular row. (But a row can be emptied of all content no matter how
|
|
**| many refs exist, and this might be the next best thing to destruction.)
|
|
**| Once a row exists in a least one table (after NewRow() is called), then it
|
|
**| can be added to any other table by calling AddRow(), or removed from any
|
|
**| table by calling CutRow(), or queried as a member by calling HasRow(). A
|
|
**| row can only be added to a table once, and further additions do nothing and
|
|
**| complain not at all. Cutting a row from a table only does something when
|
|
**| the row was actually a member, and otherwise does nothing silently.
|
|
**|
|
|
**|| row ref count: one can query the number of tables (and or cells)
|
|
**| containing a row as a member or a child.
|
|
**|
|
|
**|| row content: one can access or modify the cell content in a table's row
|
|
**| by moving content to or from an instance of nsIMdbRow. Note that nsIMdbRow
|
|
**| never represents the actual row inside a table, and this is the reason
|
|
**| why nsIMdbRow instances do not have row IDs or row scopes. So an instance
|
|
**| of nsIMdbRow always and only contains a snapshot of some or all content in
|
|
**| past, present, or future persistent row inside a table. This means that
|
|
**| reading and writing rows in tables has strictly copy semantics, and we
|
|
**| currently do not plan any exceptions for specific performance reasons.
|
|
**|
|
|
**|| sorting: note all rows are assumed sorted by row ID as a secondary
|
|
**| sort following the primary column sort, when table rows are sorted.
|
|
**|
|
|
**|| indexes:
|
|
|*/
|
|
public interface nsIMdbTable extends nsIMdbCollection { // a collection of rows
|
|
|
|
// { ===== begin nsIMdbTable methods =====
|
|
|
|
// { ----- begin attribute methods -----
|
|
public int GetTableKind(nsIMdbEnv ev);
|
|
public int GetRowScope(nsIMdbEnv ev);
|
|
|
|
// } ----- end attribute methods -----
|
|
|
|
// { ----- begin cursor methods -----
|
|
public nsIMdbTableRowCursor GetTableRowCursor( // make a cursor, starting iteration at inRowPos
|
|
nsIMdbEnv ev, // context
|
|
int inRowPos); // zero-based ordinal position of row in table
|
|
// acquire new cursor instance
|
|
// } ----- end row position methods -----
|
|
|
|
// { ----- begin row position methods -----
|
|
public mdbOid RowPosToOid( // get row member for a table position
|
|
nsIMdbEnv ev, // context
|
|
int inRowPos); // zero-based ordinal position of row in table
|
|
// row oid at the specified position
|
|
|
|
// Note that HasRow() performs the inverse oid->pos mapping
|
|
// } ----- end row position methods -----
|
|
|
|
// { ----- begin oid set methods -----
|
|
public void AddOid( // make sure the row with inOid is a table member
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // row to ensure membership in table
|
|
|
|
public int HasOid( // test for the table position of a row member
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // row to find in table
|
|
// zero-based ordinal position of row in table
|
|
|
|
public void CutOid( // make sure the row with inOid is not a member
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // row to remove from table
|
|
// } ----- end oid set methods -----
|
|
|
|
// { ----- begin row set methods -----
|
|
public nsIMdbRow NewRow( // create a new row instance in table
|
|
nsIMdbEnv ev, // context
|
|
mdbOid ioOid); // please use zero (unbound) rowId for db-assigned IDs
|
|
// create new row
|
|
|
|
public void AddRow( // make sure the row with inOid is a table member
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbRow ioRow); // row to ensure membership in table
|
|
|
|
public int HasRow( // test for the table position of a row member
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbRow ioRow); // row to find in table
|
|
// zero-based ordinal position of row in table
|
|
|
|
public void CutRow( // make sure the row with inOid is not a member
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbRow ioRow); // row to remove from table
|
|
// } ----- end row set methods -----
|
|
|
|
// { ----- begin searching methods -----
|
|
public mdbRange SearchOneSortedColumn( // search only currently sorted col
|
|
nsIMdbEnv ev, // context
|
|
final String inPrefix); // content to find as prefix in row's column cell
|
|
// range of matching rows
|
|
|
|
public nsIMdbThumb SearchManyColumns( // search variable number of sorted cols
|
|
nsIMdbEnv ev, // context
|
|
final String inPrefix, // content to find as prefix in row's column cell
|
|
mdbSearch ioSearch); // columns to search and resulting ranges
|
|
// acquire thumb for incremental search
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the search will be finished. Until that time, the ioSearch argument
|
|
// is assumed referenced and used by the thumb; one should not inspect any
|
|
// output results in ioSearch until after the thumb is finished with it.
|
|
// } ----- end searching methods -----
|
|
|
|
// { ----- begin hinting methods -----
|
|
public void SearchColumnsHint( // advise re future expected search cols
|
|
nsIMdbEnv ev, // context
|
|
final mdbColumnSet inColumnSet); // columns likely to be searched
|
|
|
|
public void SortColumnsHint( // advise re future expected sort columns
|
|
nsIMdbEnv ev, // context
|
|
final mdbColumnSet inColumnSet); // columns for likely sort requests
|
|
|
|
public void StartBatchChangeHint( // advise before many adds and cuts
|
|
nsIMdbEnv ev, // context
|
|
final String inLabel); // intend unique address to match end call
|
|
// If batch starts nest by virtue of nesting calls in the stack, then
|
|
// the address of a local variable makes a good batch start label that
|
|
// can be used at batch end time, and such addresses remain unique.
|
|
public void EndBatchChangeHint( // advise before many adds and cuts
|
|
nsIMdbEnv ev, // context
|
|
final String inLabel); // label matching start label
|
|
// Suppose a table is maintaining one or many sort orders for a table,
|
|
// so that every row added to the table must be inserted in each sort,
|
|
// and every row cut must be removed from each sort. If a db client
|
|
// intends to make many such changes before needing any information
|
|
// about the order or positions of rows inside a table, then a client
|
|
// might tell the table to start batch changes in order to disable
|
|
// sorting of rows for the interim. Presumably a table will then do
|
|
// a full sort of all rows at need when the batch changes end, or when
|
|
// a surprise request occurs for row position during batch changes.
|
|
// } ----- end hinting methods -----
|
|
|
|
// { ----- begin sorting methods -----
|
|
// sorting: note all rows are assumed sorted by row ID as a secondary
|
|
// sort following the primary column sort, when table rows are sorted.
|
|
|
|
public boolean
|
|
CanSortColumn( // query which column is currently used for sorting
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // column to query sorting potential
|
|
// whether the column can be sorted
|
|
|
|
public nsIMdbThumb
|
|
NewSortColumn( // change the column used for sorting in the table
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // requested new column for sorting table
|
|
//mdb_column* outActualColumn, // column actually used for sorting
|
|
// acquire thumb for incremental table resort
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the sort will be finished.
|
|
|
|
public nsIMdbThumb
|
|
NewSortColumnWithCompare( // change sort column with explicit compare
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbCompare ioCompare, // explicit interface for yarn comparison
|
|
int inColumn); // requested new column for sorting table
|
|
// mdb_column* outActualColumn, // column actually used for sorting
|
|
// acquire thumb for incremental table resort
|
|
// Note the table will hold a reference to inCompare if this object is used
|
|
// to sort the table. Until the table closes, callers can only force release
|
|
// of the compare object by changing the sort (by say, changing to unsorted).
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the sort will be finished.
|
|
|
|
public int GetSortColumn( // query which col is currently sorted
|
|
nsIMdbEnv ev); // context
|
|
// col the table uses for sorting (or zero)
|
|
|
|
|
|
public nsIMdbThumb CloneSortColumn( // view same table with a different sort
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // requested new column for sorting table
|
|
// acquire thumb for incremental table clone
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then call nsIMdbTable::ThumbToCloneSortTable() to get the table instance.
|
|
|
|
public nsIMdbTable
|
|
ThumbToCloneSortTable( // redeem complete CloneSortColumn() thumb
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbThumb ioThumb); // thumb from CloneSortColumn() with done status
|
|
// new table instance (or old if sort unchanged)
|
|
// } ----- end sorting methods -----
|
|
|
|
// { ----- begin moving methods -----
|
|
// moving a row does nothing unless a table is currently unsorted
|
|
|
|
public int MoveOid( // change position of row in unsorted table
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid, // row oid to find in table
|
|
int inHintFromPos, // suggested hint regarding start position
|
|
int inToPos); // desired new position for row inRowId
|
|
// actual new position of row in table
|
|
|
|
public int MoveRow( // change position of row in unsorted table
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbRow ioRow, // row oid to find in table
|
|
int inHintFromPos, // suggested hint regarding start position
|
|
int inToPos); // desired new position for row inRowId
|
|
// actual new position of row in table
|
|
// } ----- end moving methods -----
|
|
|
|
// { ----- begin index methods -----
|
|
public nsIMdbThumb AddIndex( // create a sorting index for column if possible
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column to sort by index
|
|
// acquire thumb for incremental index building
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the index addition will be finished.
|
|
|
|
public nsIMdbThumb CutIndex( // stop supporting a specific column index
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column with index to be removed
|
|
// acquire thumb for incremental index destroy
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the index removal will be finished.
|
|
|
|
public boolean HasIndex( // query for current presence of a column index
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column to investigate
|
|
// whether column has index for this column
|
|
|
|
|
|
public void EnableIndexOnSort( // create an index for col on first sort
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column to index if ever sorted
|
|
|
|
public boolean QueryIndexOnSort( // check whether index on sort is enabled
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column to investigate
|
|
// whether column has index-on-sort enabled
|
|
|
|
public void DisableIndexOnSort( // prevent future index creation on sort
|
|
nsIMdbEnv ev, // context
|
|
int inColumn); // the column to index if ever sorted
|
|
// } ----- end index methods -----
|
|
|
|
// } ===== end nsIMdbTable methods =====
|
|
};
|
|
|