OpenStep 4.2J (Developer)/os42jdev.iso/NextDeveloper/OpenStepConversion/3.3Headers/eoaccess/EODatabaseContext.h

Text File | 1994-09-08 | 8.8 KB | 220 lines

// EODatabaseContext.h
// Copyright (c) 1994, NeXT Computer, Inc.  All rights reserved.

#import <foundation/NSArray.h>
#import <foundation/NSData.h>
#import <foundation/NSDictionary.h>
#import <foundation/NSObject.h>
#import <foundation/NSString.h>

@class EODatabase;
@class EOQualifier;
@class EOAdaptorContext;
@class EOEntity;

// An EODatabaseContext represents a single transaction scope on the database
// server, and determines the updating and locking stragegy used by the
// database layer.  It's managed by an EODatabase object, which represents the
// main connection to the server.  If the server supports multiple concurrent
// transaction sessions, the EODatabase may have several EODatabaseContexts.
// An EODatabaseContext may in turn have several EODatabaseChannels, which
// handle actual access to the data on the server.  An EODatabaseContext by
// default has no EODatabaseChannels; to create a new EODatabaseChannel,
// allocate and initialize one with -initWithDatabaseContext:.  See
// EODatabase.h and EODatabase Channel.h for more information.
//
// Not all adaptors support multiple contexts per database object.
//
// An EODatabaseContext creates an EOAdaptorContext when initialized, and uses
// this object to actually communicate with the database server.
//
// UPDATING AND LOCKING STRATEGIES
//
// EODatabaseContext supports four updating stategies, one of which is
// actually a read-only or "no update" strategy.  EODatabaseContext's updating
// behavior is closely tied to the snapshot strategy of its associated
// EODatabase.  As long as snapshotting is enabled for the EODatabaseContext's
// parent database (the default behavior), snapshots are retained for the
// duration of an Enterprise Object's existence.  Snapshot information is used
// for optimistic locking and for updating only the properties of an
// Enterprise Object that have changed.  The channel also uses a snapshot to
// find the row in the database the needs to be updated.  This allows you to
// change even the primary key of an object.
//
// When you disable snapshotting for the parent database, the context produces
// snapshots within a given transaction to allow you to update objects fetched
// within that transaction.
//
// The following sections describe each of the update modes in detail.
// Remember, all three of the modes that support updating have the same
// behavior when snapshotting is NOT set for the parent database: they only
// permit updates within the current transaction.
//
// EOUpdateWithPessimisticLocking:
//
// Under pessimistic locking, objects are locked when they're selected.  This
// ensures that no one else can modify the objects until your transaction ends.
// However, this doesn't necessarily mean that YOUR update will succeed.
// Other settings at the adaptor or physical database level can cause your
// update to fail.
//
// If the parent database keeps snapshots, you can also update objects that
// you haven't fetched during the current transaction.  Since the objects
// haven't been locked, however, the optimistic strategy is used.
//
// EOUpdateWithOptimisticLocking:
//
// Under optimistic locking, objects aren't locked on the server: When you
// attempt to update an object in the database, the object's snapshot is used
// to ensure that the values in the corresponding database row have not
// changed since the object was fetched.  As long as the snapshot matches the
// database, the update is allowed to proceed.  When snapshotting is set in
// the parent database, you can update objects even if they weren't fetched
// in the current transaction.  EOUpdateWithOptimisticLocking is the default
// update strategy.
//
// EOUpdateWithNoLocking:
//
// Under the no-locking strategy, objects are never locked.  No comparisons
// are made between the snapshot and the row to ensure that the values in the
// row haven't changed; they are simply overwritten with the new values.  When
// snapshotting is set in the parent database, you can update objects even if
// they weren't fetched in the current transaction.
//
// EONoUpdate:
//
// EONoUpdate is useful when you want to retrieve data with as little overhead
// as possible and don't need to perform updates.  To reap the benefits of
// this mode, snapshotting in the parent database should be turned off.  When
// the context is in no update mode and the parent database is not keeping
// snapshots, the least amount of overhead is used to get data into enterprise
// objects and back to the client program.


typedef enum {
    EOUpdateWithOptimisticLocking,
    EOUpdateWithPessimisticLocking,
    EOUpdateWithNoLocking,
    EONoUpdate,
} EOUpdateStrategy;


@interface EODatabaseContext:NSObject
{
    EODatabase *_database;
    EOAdaptorContext *_adaptorContext;
    EOUpdateStrategy _updateStrategy;
    NSMutableArray *_uniqueStack;
    NSMutableArray *_deleteStack;
    NSMutableArray *_modifiedObjects;
    void *_lockedObjects;
    struct {
    unsigned int keepsLocalSnapshots:1;
    unsigned int _RESERVED:31;
    } _flags;
}

- initWithDatabase:(EODatabase *)database;
    // Initializes a newly allocated EODatabaseChannel with database as the
    // EODatabase object it works with.  Returns self, or nil if no more
    // contexts can be associated with database.

- (BOOL)hasBusyChannels;
    // Returns YES if the receiver has channels that have outstanding
    // operations (that is, have a fetch in progress), NO otherwise.

- (EODatabase *)database;
    // Returns the EODatabase that the context works with.

- (EOAdaptorContext *)adaptorContext;
    // Returns the EOAdaptorContext used by the EODatabaseContext for
    // communication with the database server.

- (void)setUpdateStrategy:(EOUpdateStrategy)strategy;
- (EOUpdateStrategy)updateStrategy;
    // These methods set/return the update strategy used by the context.  The
    // default is EOUpdateWithOptimisticLocking.

- (BOOL)keepsSnapshots;
    // Returns NO if the context's locking strategy is EONoUpdate and the
    // parent database object keeps snapshots, YES otherwise.

@end


// This category defines an interface for a basic transaction model
// that incorporates begin, commit and rollback operations.

@interface EODatabaseContext (EOTransactions)

- (BOOL)beginTransaction;
    // Attempts to begin a new transaction, nested within the current one if
    // nested transaction are supported, returning YES if successful and NO
    // if not.

- (BOOL)commitTransaction;
    // Attempts to commit the last transaction begun, returning YES if
    // successful and NO if not. This method will raise an exception if any
    // of the context's channels have a fetch in progress or if the
    // transactionNestingLevel of the databaseContext is out of sync with
    // the adaptorContext.

- (BOOL)rollbackTransaction;
    // Attempts to roll back the last transaction begun, returning YES if
    // successful and NO if not. This method will raise an exception if any
    // of the context's channels have a fetch in progress or if the
    // transactionNestingLevel of the databaseContext is out of sync with
    // the adaptorContext.

- (BOOL)canNestTransactions;
    // Returns YES if the database server can nest transactions, NO
    // otherwise.

- (unsigned)transactionNestingLevel;
    // Returns the number of transactions in progress. If transactions
    // can nest, this number may be greater than one.

// Since databases vary widely in their ability to report transactions
// generated automatically--for example through stored procedures--the
// following notification methods help the caller keep the transaction objects
// synchronized with the database.  These methods are also invoked by the
// -beginTransaction, -commitTransaction, and -rollbackTransaction methods.

- (void)transactionDidBegin;
    // Informs the receiver that the server has begun a transaction.

- (void)transactionDidCommit;
    // Informs the receiver that the server has committed a transaction.

- (void)transactionDidRollback;
    // Informs the receiver that the server has rolled back a transaction.

@end


// The uniquing methods on the context are for maintaining unique objects
// during a transaction.

@interface EODatabaseContext (EOUniquing)

- (void)recordObject:eo primaryKey:(NSDictionary *)key
    snapshot:(NSDictionary *)snapshot;
    // If uniquing is turned on, records eo under the primary key.  Also,
    // if snapshotting is turned on this method records the eo's snapshot.

- (void)forgetObject:eo;
    // If uniquing is turned on, removes the eo associated with the
    // primary key from the uniquing table, and if snapshotting is turned on
    // the eo's snapshot is also destroyed.

- (NSDictionary *)snapshotForObject:eo;
    // Returns the snapshot assocated with eo, if there is one; else
    // returns nil.

- objectForPrimaryKey:(NSDictionary *)key entity:(EOEntity *)entity;
    // Returns the unique eo for the given primary key and entity, or nil
    // if one can't be found.

@end