зеркало из https://github.com/mozilla/gecko-dev.git
144 строки
7.6 KiB
Java
144 строки
7.6 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;
|
|
|
|
/*| nsIMdbFactory: the main entry points to the abstract db interface. A DLL
|
|
**| that supports this mdb interface need only have a single exported method
|
|
**| that will return an instance of nsIMdbFactory, so that further methods in
|
|
**| the suite can be accessed from objects returned by nsIMdbFactory methods.
|
|
**|
|
|
**|| mdbYarn: note all nsIMdbFactory 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 nsIMdbFactory interface.
|
|
**|
|
|
**|| envs: an environment instance is required as per-thread context for
|
|
**| most of the db method calls, so nsIMdbFactory creates such instances.
|
|
**|
|
|
**|| rows: callers must be able to create row instances that are independent
|
|
**| of storage space that is part of the db content graph. Many interfaces
|
|
**| for data exchange have strictly copy semantics, so that a row instance
|
|
**| has no specific identity inside the db content model, and the text in
|
|
**| cells are an independenty copy of unexposed content inside the db model.
|
|
**| Callers are expected to maintain one or more row instances as a buffer
|
|
**| for staging cell content copied into or out of a table inside the db.
|
|
**| Callers are urged to use an instance of nsIMdbRow created by the nsIMdbFactory
|
|
**| code suite, because reading and writing might be much more efficient than
|
|
**| when using a hand-rolled nsIMdbRow subclass with no relation to the suite.
|
|
**|
|
|
**|| ports: a port is a readonly interface to a specific database file. Most
|
|
**| of the methods to access a db file are suitable for a readonly interface,
|
|
**| so a port is the basic minimum for accessing content. This makes it
|
|
**| possible to read other external formats for import purposes, without
|
|
**| needing the code or competence necessary to write every such format. So
|
|
**| we can write generic import code just once, as long as every format can
|
|
**| show a face based on nsIMdbPort. (However, same suite import can be faster.)
|
|
**| Given a file name and the first 512 bytes of a file, a factory can say if
|
|
**| a port can be opened by this factory. Presumably an app maintains chains
|
|
**| of factories for different suites, and asks each in turn about opening a
|
|
**| a prospective file for reading (as a port) or writing (as a store). I'm
|
|
**| not ready to tackle issues of format fidelity and factory chain ordering.
|
|
**|
|
|
**|| stores: a store is a mutable interface to a specific database file, and
|
|
**| includes the port interface plus any methods particular to writing, which
|
|
**| are few in number. Presumably the set of files that can be opened as
|
|
**| stores is a subset of the set of files that can be opened as ports. A
|
|
**| new store can be created with CreateNewFileStore() by supplying a new
|
|
**| file name which does not yet exist (callers are always responsible for
|
|
**| destroying any existing files before calling this method).
|
|
|*/
|
|
public interface nsIMdbFactory extends nsIMdbObject { // suite entry points
|
|
|
|
// { ===== begin nsIMdbFactory methods =====
|
|
|
|
// { ----- begin env methods -----
|
|
public nsIMdbEnv MakeEnv(); // acquire new env
|
|
// ioHeap can be nil, causing a MakeHeap() style heap instance to be used
|
|
// } ----- end env methods -----
|
|
|
|
// { ----- begin heap methods -----
|
|
// public int MakeHeap(nsIMdbEnv ev, nsIMdbHeap acqHeap); // acquire new heap
|
|
// } ----- end heap methods -----
|
|
|
|
// { ----- begin row methods -----
|
|
public nsIMdbRow MakeRow(nsIMdbEnv ev); // new row
|
|
// ioHeap can be nil, causing the heap associated with ev to be used
|
|
// } ----- end row methods -----
|
|
|
|
// { ----- begin port methods -----
|
|
public boolean CanOpenFilePort(
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath, // the file to investigate
|
|
// const mdbYarn* inFirst512Bytes,
|
|
String inFirst512Bytes);
|
|
|
|
public String getFormatVersion(
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath, // the file to investigate
|
|
// const mdbYarn* inFirst512Bytes,
|
|
String inFirst512Bytes);
|
|
|
|
public nsIMdbThumb OpenFilePort(
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath, // the file to open for readonly import
|
|
final mdbOpenPolicy inOpenPolicy); // runtime policies for using db
|
|
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then call nsIMdbFactory::ThumbToOpenPort() to get the port instance.
|
|
|
|
public nsIMdbPort ThumbToOpenPort( // redeeming a completed thumb from OpenFilePort()
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbThumb ioThumb); // thumb from OpenFilePort() with done status
|
|
// } ----- end port methods -----
|
|
|
|
// { ----- begin store methods -----
|
|
public boolean CanOpenFileStore(
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath); // the file to investigate
|
|
//const mdbYarn* inFirst512Bytes,
|
|
// mdb_bool* outCanOpenAsStore, // whether OpenFileStore() might succeed
|
|
// mdb_bool* outCanOpenAsPort, // whether OpenFilePort() might succeed
|
|
// mdbYarn* outFormatVersion); // informal file format description
|
|
|
|
public nsIMdbThumb OpenFileStore( // open an existing database
|
|
nsIMdbEnv ev, // context
|
|
final String inFilePath, // the file to open for general db usage
|
|
final mdbOpenPolicy inOpenPolicy); // runtime policies for using db
|
|
// Call nsIMdbThumb::DoMore() until done, or until the thumb is broken, and
|
|
// then call nsIMdbFactory::ThumbToOpenStore() to get the store instance.
|
|
|
|
public nsIMdbStore ThumbToOpenStore( // redeem completed thumb from OpenFileStore()
|
|
nsIMdbEnv ev, // context
|
|
nsIMdbThumb ioThumb); // thumb from OpenFileStore() with done status
|
|
|
|
public nsIMdbStore CreateNewFileStore( // create a new db with minimal content
|
|
nsIMdbEnv ev, // context
|
|
//nsIMdbHeap ioHeap, // can be nil to cause ev's heap attribute to be used
|
|
final String inFilePath, // name of file which should not yet exist
|
|
final mdbOpenPolicy inOpenPolicy); // runtime policies for using db
|
|
// } ----- end store methods -----
|
|
|
|
// } ===== end nsIMdbFactory methods =====
|
|
};
|
|
|