mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-07 12:15:51 +00:00
186 lines
10 KiB
Java
186 lines
10 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;
|
|
|
|
/*| nsIMdbStore: a mutable interface to a specific database file.
|
|
**|
|
|
**|| tables: one can force a new table to exist in a store with NewTable()
|
|
**| and nonzero values for both row scope and table kind. (If one wishes only
|
|
**| one table of a certain kind, then one might look for it first using the
|
|
**| GetTableKind() method). One can pass inMustBeUnique to force future
|
|
**| users of this store to be unable to create other tables with the same pair
|
|
**| of scope and kind attributes. When inMustBeUnique is true, and the table
|
|
**| with the given scope and kind pair already exists, then the existing one
|
|
**| is returned instead of making a new table. Similarly, if one passes false
|
|
**| for inMustBeUnique, but the table kind has already been marked unique by a
|
|
**| previous user of the store, then the existing unique table is returned.
|
|
**|
|
|
**|| import: all or some of another port's content can be imported by calling
|
|
**| AddPortContent() with a row scope identifying the extent of content to
|
|
**| be imported. A zero row scope will import everything. A nonzero row
|
|
**| scope will only import tables with a matching row scope. Note that one
|
|
**| must somehow find a way to negotiate possible conflicts between existing
|
|
**| row content and imported row content, and this involves a specific kind of
|
|
**| definition for row identity involving either row IDs or unique attributes,
|
|
**| or some combination of these two. At the moment I am just going to wave
|
|
**| my hands, and say the default behavior is to assign all new row identities
|
|
**| to all imported content, which will result in no merging of content; this
|
|
**| must change later because it is unacceptable in some contexts.
|
|
**|
|
|
**|| commits: to manage modifications in a mutable store, very few methods are
|
|
**| really needed to indicate global policy choices that are independent of
|
|
**| the actual modifications that happen in objects at the level of tables,
|
|
**| rows, and cells, etc. The most important policy to specify is which sets
|
|
**| of changes are considered associated in a manner such that they should be
|
|
**| applied together atomically to a given store. We call each such group of
|
|
**| changes a transaction. We handle three different grades of transaction,
|
|
**| but they differ only in semantic significance to the application, and are
|
|
**| not intended to nest. (If small transactions were nested inside large
|
|
**| transactions, that would imply that a single large transaction must be
|
|
**| atomic over all the contained small transactions; but actually we intend
|
|
**| smalls transaction never be undone once commited due to, say, aborting a
|
|
**| transaction of greater significance.) The small, large, and session level
|
|
**| commits have equal granularity, and differ only in risk of loss from the
|
|
**| perspective of an application. Small commits characterize changes that
|
|
**| can be lost with relatively small risk, so small transactions can delay
|
|
**| until later if they are expensive or impractical to commit. Large commits
|
|
**| involve changes that would probably inconvenience users if lost, so the
|
|
**| need to pay costs of writing is rather greater than with small commits.
|
|
**| Session commits are last ditch attempts to save outstanding changes before
|
|
**| stopping the use of a particular database, so there will be no later point
|
|
**| in time to save changes that have been delayed due to possible high cost.
|
|
**| If large commits are never delayed, then a session commit has about the
|
|
**| same performance effect as another large commit; but if small and large
|
|
**| commits are always delayed, then a session commit is likely to be rather
|
|
**| expensive as a runtime cost compared to any earlier database usage.
|
|
**|
|
|
**|| aborts: the only way to abort changes to a store is by closing the store.
|
|
**| So there is no specific method for causing any abort. Stores must discard
|
|
**| all changes made that are uncommited when a store is closed. This design
|
|
**| choice makes the implementations of tables, rows, and cells much less
|
|
**| complex because they need not maintain a record of undobable changes. When
|
|
**| a store is closed, presumably this precipitates the closure of all tables,
|
|
**| rows, and cells in the store as well. So an application can revert the
|
|
**| state of a store in the user interface by quietly closing and reopening a
|
|
**| store, because this will discard uncommited changes and show old content.
|
|
**| This implies an app that closes a store will need to send a "scramble"
|
|
**| event notification to any views that depend on old discarded content.
|
|
|*/
|
|
public interface nsIMdbStore extends nsIMdbPort {
|
|
|
|
// { ===== begin nsIMdbStore methods =====
|
|
|
|
// { ----- begin table methods -----
|
|
public nsIMdbTable NewTable( // make one new table of specific type
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // row scope for row ids
|
|
int inTableKind, // the type of table to access
|
|
boolean inMustBeUnique); // whether store can hold only one of these
|
|
// acquire scoped collection of rows
|
|
// } ----- end table methods -----
|
|
|
|
// { ----- begin row scope methods -----
|
|
public boolean RowScopeHasAssignedIds(nsIMdbEnv ev,
|
|
int inRowScope); // row scope for row ids
|
|
//mdb_bool* outCallerAssigned, // nonzero if caller assigned specified
|
|
//mdb_bool* outStoreAssigned); // nonzero if store db assigned specified
|
|
|
|
public boolean SetCallerAssignedIds(nsIMdbEnv ev,
|
|
int inRowScope); // row scope for row ids
|
|
//mdb_bool* outCallerAssigned, // nonzero if caller assigned specified
|
|
//mdb_bool* outStoreAssigned); // nonzero if store db assigned specified
|
|
|
|
public boolean SetStoreAssignedIds(nsIMdbEnv ev,
|
|
int inRowScope); // row scope for row ids
|
|
// mdb_bool* outCallerAssigned, // nonzero if caller assigned specified
|
|
// mdb_bool* outStoreAssigned); // nonzero if store db assigned specified
|
|
// } ----- end row scope methods -----
|
|
|
|
// { ----- begin row methods -----
|
|
public nsIMdbRow NewRowWithOid(nsIMdbEnv ev, // new row w/ caller assigned oid
|
|
final mdbOid inOid); // caller assigned oid
|
|
// create new row
|
|
|
|
public nsIMdbRow NewRow(nsIMdbEnv ev, // new row with db assigned oid
|
|
int inRowScope); // row scope for row ids
|
|
// create new row
|
|
// Note this row must be added to some table or cell child before the
|
|
// store is closed in order to make this row persist across sesssions.
|
|
// } ----- end row methods -----
|
|
|
|
// { ----- begin inport/export methods -----
|
|
public nsIMdbThumb ImportContent( // import content from port
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // scope for rows (or zero for all?)
|
|
nsIMdbPort ioPort); // the port with content to add to store
|
|
// acquire thumb for incremental import
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the import will be finished.
|
|
// } ----- end inport/export methods -----
|
|
|
|
// { ----- begin hinting methods -----
|
|
public void
|
|
ShareAtomColumnsHint( // advise re shared column content atomizing
|
|
nsIMdbEnv ev, // context
|
|
int inScopeHint, // zero, or suggested shared namespace
|
|
final mdbColumnSet inColumnSet); // cols desired tokenized together
|
|
|
|
public void
|
|
AvoidAtomColumnsHint( // advise column with poor atomizing prospects
|
|
nsIMdbEnv ev, // context
|
|
final mdbColumnSet inColumnSet); // cols with poor atomizing prospects
|
|
// } ----- end hinting methods -----
|
|
|
|
// { ----- begin commit methods -----
|
|
public void SmallCommit( // save minor changes if convenient and uncostly
|
|
nsIMdbEnv ev); // context
|
|
|
|
public nsIMdbThumb LargeCommit( // save important changes if at all possible
|
|
nsIMdbEnv ev); // context
|
|
// acquire thumb for incremental commit
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the commit will be finished. Note the store is effectively write
|
|
// locked until commit is finished or canceled through the thumb instance.
|
|
// Until the commit is done, the store will report it has readonly status.
|
|
|
|
public nsIMdbThumb SessionCommit( // save all changes if large commits delayed
|
|
nsIMdbEnv ev); // context
|
|
// acquire thumb for incremental commit
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the commit will be finished. Note the store is effectively write
|
|
// locked until commit is finished or canceled through the thumb instance.
|
|
// Until the commit is done, the store will report it has readonly status.
|
|
|
|
public nsIMdbThumb
|
|
CompressCommit( // commit and make db physically smaller if possible
|
|
nsIMdbEnv ev); // context
|
|
// acquire thumb for incremental commit
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the commit will be finished. Note the store is effectively write
|
|
// locked until commit is finished or canceled through the thumb instance.
|
|
// Until the commit is done, the store will report it has readonly status.
|
|
// } ----- end commit methods -----
|
|
|
|
// } ===== end nsIMdbStore methods =====
|
|
};
|
|
|