зеркало из https://github.com/mozilla/gecko-dev.git
255 строки
12 KiB
Java
255 строки
12 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;
|
|
/*| nsIMdbPort: a readonly interface to a specific database file. The mutable
|
|
**| nsIMdbStore interface is a subclass that includes writing behavior, but
|
|
**| most of the needed db methods appear in the readonly nsIMdbPort interface.
|
|
**|
|
|
**|| mdbYarn: note all nsIMdbPort and nsIMdbStore subclasses must guarantee null
|
|
**| termination of all strings written into mdbYarn instances, as long as
|
|
**| mYarn_Size and mYarn_Buf are nonzero. Even truncated string values must
|
|
**| be null terminated. This is more strict behavior than mdbYarn requires,
|
|
**| but it is part of the nsIMdbPort and nsIMdbStore interface.
|
|
**|
|
|
**|| attributes: methods are provided to distinguish a readonly port from a
|
|
**| mutable store, and whether a mutable store actually has any dirty content.
|
|
**|
|
|
**|| filepath: the file path used to open the port from the nsIMdbFactory can be
|
|
**| queried and discovered by GetPortFilePath(), which includes format info.
|
|
**|
|
|
**|| export: a port can write itself in other formats, with perhaps a typical
|
|
**| emphasis on text interchange formats used by other systems. A port can be
|
|
**| queried to determine its preferred export interchange format, and a port
|
|
**| can be queried to see whether a specific export format is supported. And
|
|
**| actually exporting a port requires a new destination file name and format.
|
|
**|
|
|
**|| tokens: a port supports queries about atomized strings to map tokens to
|
|
**| strings or strings to token integers. (All atomized strings must be in
|
|
**| US-ASCII iso-8859-1 Latin1 charset encoding.) When a port is actually a
|
|
**| mutable store and a string has not yet been atomized, then StringToToken()
|
|
**| will actually do so and modify the store. The QueryToken() method will not
|
|
**| atomize a string if it has not already been atomized yet, even in stores.
|
|
**|
|
|
**|| tables: other than string tokens, all port content is presented through
|
|
**| tables, which are ordered collections of rows. Tables are identified by
|
|
**| row scope and table kind, which might or might not be unique in a port,
|
|
**| depending on app convention. When tables are effectively unique, then
|
|
**| queries for specific scope and kind pairs will find those tables. To see
|
|
**| all tables that match specific row scope and table kind patterns, even in
|
|
**| the presence of duplicates, every port supports a GetPortTableCursor()
|
|
**| method that returns an iterator over all matching tables. Table kind is
|
|
**| considered scoped inside row scope, so passing a zero for table kind will
|
|
**| find all table kinds for some nonzero row scope. Passing a zero for row
|
|
**| scope will iterate over all tables in the port, in some undefined order.
|
|
**| (A new table can be added to a port using nsIMdbStore::NewTable(), even when
|
|
**| the requested scope and kind combination is already used by other tables.)
|
|
**|
|
|
**|| memory: callers can request that a database use less memory footprint in
|
|
**| several flavors, from an inconsequential idle flavor to a rather drastic
|
|
**| panic flavor. Callers might perform an idle purge very frequently if desired
|
|
**| with very little cost, since only normally scheduled memory management will
|
|
**| be conducted, such as freeing resources for objects scheduled to be dropped.
|
|
**| Callers should perform session memory purges infrequently because they might
|
|
**| involve costly scanning of data structures to removed cached content, and
|
|
**| session purges are recommended only when a caller experiences memory crunch.
|
|
**| Callers should only rarely perform a panic purge, in response to dire memory
|
|
**| straits, since this is likely to make db operations much more expensive
|
|
**| than they would be otherwise. A panic purge asks a database to free as much
|
|
**| memory as possible while staying effective and operational, because a caller
|
|
**| thinks application failure might otherwise occur. (Apps might better close
|
|
**| an open db, so panic purges only make sense when a db is urgently needed.)
|
|
|*/
|
|
public interface nsIMdbPort extends nsIMdbObject {
|
|
|
|
// { ===== begin nsIMdbPort methods =====
|
|
|
|
// { ----- begin attribute methods -----
|
|
public boolean GetIsPortReadonly(nsIMdbEnv ev);
|
|
public boolean GetIsStore(nsIMdbEnv ev);
|
|
public boolean GetIsStoreAndDirty(nsIMdbEnv ev);
|
|
|
|
public mdbUsagePolicy GetUsagePolicy(nsIMdbEnv ev);
|
|
|
|
public void SetUsagePolicy(nsIMdbEnv ev, final mdbUsagePolicy inUsagePolicy);
|
|
// } ----- end attribute methods -----
|
|
|
|
// { ----- begin memory policy methods -----
|
|
public int IdleMemoryPurge( // do memory management already scheduled
|
|
nsIMdbEnv ev); // context
|
|
// approximate bytes actually freed
|
|
|
|
public int SessionMemoryPurge( // request specific footprint decrease
|
|
nsIMdbEnv ev, // context
|
|
int inDesiredBytesFreed); // approximate number of bytes wanted
|
|
// approximate bytes actually freed
|
|
|
|
public int PanicMemoryPurge( // desperately free all possible memory
|
|
nsIMdbEnv ev); // context
|
|
// approximate bytes actually freed
|
|
// } ----- end memory policy methods -----
|
|
|
|
// { ----- begin filepath methods -----
|
|
public String GetPortFilePath(
|
|
nsIMdbEnv ev); // context
|
|
// name of file holding port content
|
|
// file format description
|
|
public String GetFormatVersion(nsIMdbEnv ev);
|
|
// } ----- end filepath methods -----
|
|
|
|
// { ----- begin export methods -----
|
|
public String BestExportFormat( // determine preferred export format
|
|
nsIMdbEnv ev); // context
|
|
// file format description
|
|
|
|
// some tentative suggested import/export formats
|
|
// "ns:msg:db:port:format:ldif:ns4.0:passthrough" // necessary
|
|
// "ns:msg:db:port:format:ldif:ns4.5:utf8" // necessary
|
|
// "ns:msg:db:port:format:ldif:ns4.5:tabbed"
|
|
// "ns:msg:db:port:format:ldif:ns4.5:binary" // necessary
|
|
// "ns:msg:db:port:format:html:ns3.0:addressbook" // necessary
|
|
// "ns:msg:db:port:format:html:display:verbose"
|
|
// "ns:msg:db:port:format:html:display:concise"
|
|
// "ns:msg:db:port:format:mork:zany:verbose" // necessary
|
|
// "ns:msg:db:port:format:mork:zany:atomized" // necessary
|
|
// "ns:msg:db:port:format:rdf:xml"
|
|
// "ns:msg:db:port:format:xml:mork"
|
|
// "ns:msg:db:port:format:xml:display:verbose"
|
|
// "ns:msg:db:port:format:xml:display:concise"
|
|
// "ns:msg:db:port:format:xml:print:verbose" // recommended
|
|
// "ns:msg:db:port:format:xml:print:concise"
|
|
|
|
public boolean
|
|
CanExportToFormat( // can export content in given specific format?
|
|
nsIMdbEnv ev, // context
|
|
final String inFormatVersion); // file format description
|
|
// whether ExportSource() might succeed
|
|
|
|
public nsIMdbThumb ExportToFormat( // export content in given specific format
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath, // the file to receive exported content
|
|
final String inFormatVersion); // file format description
|
|
// acquire thumb for incremental export
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then the export will be finished.
|
|
|
|
// } ----- end export methods -----
|
|
|
|
// { ----- begin token methods -----
|
|
public String TokenToString( // return a string name for an integer token
|
|
nsIMdbEnv ev, // context
|
|
int inToken); // token for inTokenName inside this port
|
|
// the type of table to access
|
|
|
|
public int StringToToken( // return an integer token for scope name
|
|
nsIMdbEnv ev, // context
|
|
final String inTokenName); // Latin1 string to tokenize if possible
|
|
// token for inTokenName inside this port
|
|
|
|
// String token zero is never used and never supported. If the port
|
|
// is a mutable store, then StringToToken() to create a new
|
|
// association of inTokenName with a new integer token if possible.
|
|
// But a readonly port will return zero for an unknown scope name.
|
|
|
|
public int QueryToken( // like StringToToken(), but without adding
|
|
nsIMdbEnv ev, // context
|
|
final String inTokenName); // Latin1 string to tokenize if possible
|
|
// token for inTokenName inside this port
|
|
|
|
// QueryToken() will return a string token if one already exists,
|
|
// but unlike StringToToken(), will not assign a new token if not
|
|
// already in use.
|
|
|
|
// } ----- end token methods -----
|
|
|
|
// { ----- begin row methods -----
|
|
public boolean HasRow( // contains a row with the specified oid?
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // hypothetical row oid
|
|
// whether GetRow() might succeed
|
|
|
|
public nsIMdbRow GetRow( // access one row with specific oid
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // hypothetical row oid
|
|
// acquire specific row (or null)
|
|
|
|
public int GetRowRefCount( // get number of tables that contain a row
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // hypothetical row oid
|
|
// number of tables containing inRowKey
|
|
// } ----- end row methods -----
|
|
|
|
// { ----- begin table methods -----
|
|
public boolean HasTable( // supports a table with the specified oid?
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // hypothetical table oid
|
|
// whether GetTable() might succeed
|
|
|
|
public nsIMdbTable GetTable( // access one table with specific oid
|
|
nsIMdbEnv ev, // context
|
|
final mdbOid inOid); // hypothetical table oid
|
|
// acquire specific table (or null)
|
|
|
|
public boolean HasTableKind( // supports a table of the specified type?
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // rid scope for row ids
|
|
int inTableKind); // the type of table to access
|
|
// whether GetTableKind() might succeed
|
|
|
|
public int GetTableKindCount( // supports a table of the specified type?
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // rid scope for row ids
|
|
int inTableKind); // the type of table to access
|
|
|
|
// row scopes to be supported include the following suggestions:
|
|
// "ns:msg:db:row:scope:address:cards:all"
|
|
// "ns:msg:db:row:scope:mail:messages:all"
|
|
// "ns:msg:db:row:scope:news:articles:all"
|
|
|
|
// table kinds to be supported include the following suggestions:
|
|
// "ns:msg:db:table:kind:address:cards:main"
|
|
// "ns:msg:db:table:kind:address:lists:all"
|
|
// "ns:msg:db:table:kind:address:list"
|
|
// "ns:msg:db:table:kind:news:threads:all"
|
|
// "ns:msg:db:table:kind:news:thread"
|
|
// "ns:msg:db:table:kind:mail:threads:all"
|
|
// "ns:msg:db:table:kind:mail:thread"
|
|
|
|
public nsIMdbTable GetTableKind( // access one (random) table of specific type
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // row scope for row ids
|
|
int inTableKind); // the type of table to access
|
|
// current number of such tables
|
|
//mdb_bool* outMustBeUnique); // whether port can hold only one of these
|
|
// acquire scoped collection of rows
|
|
|
|
public nsIMdbPortTableCursor
|
|
GetPortTableCursor( // get cursor for all tables of specific type
|
|
nsIMdbEnv ev, // context
|
|
int inRowScope, // row scope for row ids
|
|
int inTableKind); // the type of table to access
|
|
// all such tables in the port
|
|
// } ----- end table methods -----
|
|
|
|
// } ===== end nsIMdbPort methods =====
|
|
};
|
|
|