NeXTSTEP 3.0/NeXTSTEP3.0.iso/NextDeveloper/Headers/dbkit/DBDatabase.h

Text File | 1992-05-06 | 5.4 KB | 194 lines

/*
**      DBDatabase.h
**      Database Kit, Release 3.0
**      Copyright (c) 1992, NeXT Computer, Inc.  All rights reserved.
*/

#import <objc/Object.h>
#import <dbkit/protocols.h>
#import <mach/cthreads.h>

@class List;
@class DBBinder;

/*
** A Database represents a (potential) connection to an external source of
**  data.  It also represents structural information about that source of
**  data.  This structural information is represented as a list of properties.
**  (See the protocols header for a description of a property.)
**
** Properties can either be built from scratch by a tool or by a program, or
**  they can be provided by the DBDatabase.  In the latter case, the complexity
**  and completeness of the data dictionary is totally dependant upon the
**  database; most will produce a very simple model which reflects their
**  structure.
**
** Given an expressive enough query language, properties can also be built
**  by using DBExpressions -- aggregate and compound properties can be built
**  this way.
*/

@interface DBDatabase : Object
{
@public
  id delegate;

@private
  id _adaptor;
  mutex_t _adaptorLock;

  id _entityList;
  id _bundle;
  id _strings;

  id _databaseNameString;
  char *_namebuf;
  id _identityProperty;

  id _private;
  struct {
    BOOL connected:1;
    BOOL panelsEnabled:1;
    BOOL delegateDoesTrace:1;
    BOOL delegateChecksQuery:1;
    BOOL transactionInProgress:1;
    BOOL useOuterJoins:1;
    int _RESERV$    D0;
  } _flags;
  NXZone *_garbageZone;
}

+ initialize;

/*
** If there is an open db with this name, it is returned.  If there is a
**  database file in the search path with this name, it is opened and a
**  connection is attempted.  If the connection attempt fails, the
**  database is freed, so subsequent calls will attempt to connect again,
**  possibly using new information...
**
** Databases found using this method should not be freed!
*/
+ findDatabaseNamed:(const char*)aName connect:(BOOL)yn;

/*
** Databases can use database "bundles" that reside in the filesystem to
**  initialize themselves with user and schema information.  The documents are
**  directories (with a file extension of .db) that contain at least two
**  files: db.strings and db.archive.
**
** Within the bundle, db.strings is a stringTable that can contain a string
**  with the key "AdaptorName".  It can also contain multiple initStrings,
**  indexed by username.  A key of "LoginString" will be used as a default
**  loginString.
*/
+ (const char**)databaseNamesForAdaptor:(const char*)anAdaptorName;
+ (const char**)adaptorNames;

- initFromFile:(const char*)aPath;
- (const char*)directory;

- (const char*)name;
- (BOOL)setName:(const char*)aName;

- (BOOL)connect;
- (BOOL)disconnect;
- (BOOL)connectUsingString:(const unsigned char*)aString;
- (BOOL)disconnectUsingString:(const unsigned char*)aString;

- (BOOL)isConnected;
- (const unsigned char*)connectionName;

- (BOOL)beginTransaction;
- (BOOL)commitTransaction;
- (BOOL)rollbackTransaction;

- (BOOL)isTransactionInProgress;
- (BOOL)enableTransactions:(BOOL)yn;
- (BOOL)areTransactionsEnabled;

- (BOOL)evaluateString:(const unsigned char*)aString;

- (List*)getEntities:(List*)aList;
- (id<DBEntities>)entityNamed:(const char*)aName;

/*
** These can be used to find information specific to the current db bundle.
*/
- (const char*)currentAdaptorName;
- (const char*)defaultAdaptorName;
- (const unsigned char*)currentLoginString;
- (const unsigned char*)defaultLoginString;
- (const unsigned char*)loginStringForUser:(const char*)aUser;

/*
** This can be used to launch a login panel, or to use a specific adaptor
**  in the context of a database.  The init string can be NULL.
*/
- (BOOL)connectUsingAdaptor:(const char*)aClassname
    andString:(const unsigned char*)aLoginString;

/*
** -emp$    EtaDictionary will free up the currently loaded data dictionary
**  so that another can be opened for the db.  -loadDefaultDataDictionary
**  will attempt to load a data dictionary from the adaptor if one is
**  not already loaded.
*/
- emptyDataDictionary;
- loadDefaultDataDictionary;

/*
** Delegate can act as trace of execution, log all query expressions, or
**  verify query expressions. It can also override commits and aborts.
*/
- setDelegate:aDelegate;
- delegate;

@end

@interface Object (DatabaseDelegate)

/*
** Commit/abort verification -- no cancelling allowed!
*/
- dbWillCommitTransaction:aDatabase;
- dbDidCommitTransaction:aDatabase;
- dbWillRollbackTransaction:aDatabase;
- dbDidRollbackTransaction:aDatabase;

/*
** Query interposition -- before evaluating an expression, the delegate can
**  be given the chance to override a query expression, to examine it, or
**  to replace it.
*/
- (BOOL)db:aDb willEvaluateString:(const unsigned char*)aString
     usingBinder:aBinder;

/*
** Logging -- the delegate receives a printf style format string and
**  arguments, to be used with vsprintf().
*/
- db:aDatabase log:(const char*)fmt, ...;

/*
** Notification -- an object being used by the database has encountered
**  an exceptional situation.
**
** By providing a delegate that responds to this method, the default alert
**  panels can be squelched.
*/
- (BOOL)db:aDb notificationFrom:anObject
     message:(const unsigned char*)msg code:(int)n;

/*
** setPanelsEnabled:NO must be called if you plan to use the DBDatabase
**  without panels or windows, or in a program without an Application object.
*/
- (BOOL)arePanelsEnabled;
- setPanelsEnabled:(BOOL)yn;

- read:(NXTypedStream*)ts;
- write:(NXTypedStream*)ts;

@end