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

Text File | 1992-05-20 | 5.0 KB | 166 lines

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

#import <objc/Object.h>
#import <dbkit/protocols.h>
#import <dbkit/enums.h>

@class List;
@class DBDatabase;
@class DBQualifier;
@class DBValue;

@interface DBRecordStream : Object
{
@public
  id delegate;
  id source;
  id properties;
  id database;

@private
  id _keys;
  id _sorts;
  int _qualifierMark;

@protected
  id _selectBinder;
  id _modifyBinder;
  id _private;
  short    _status;
  struct {
    BOOL isModified:1;
    BOOL newRecord:1;
    BOOL freeSource:1;
    BOOL freeQualifier:1;
    int _RESERVED:12;
  } _flags;
}


/*
** clear causes the entire RecordStream to be reset.  Empty will leave the
**  orderings, keys, and properties intact.
*/
- init;
- empty;
- clear;
- free;

/*
** Any binders used by the recordStream will have the binderDelegate as
**  their delegate.
*/
- delegate;
- binderDelegate;
- setDelegate:newDelegate;
- setBinderDelegate:newDelegate;

/*
** setProperties: will reset the keys list to contain any properties that
**  respond YES to isKey -- the keys can be read and modified after this
**  by calling getKeys and/or setKeys:
**
** The entity for every property in the list submitted must match the entity
**  of the RecordList, otherwise the entire operation fails.
*/

- (List*)getProperties:(List*)returnList;
- (List*)setProperties:(List*)aPropertyList ofSource:aSource;
- (List*)getKeyProperties:(List*)returnList;
- (List*)setKeyProperties:(List*)aPropertyL$    Q

- addRetrieveOrder:(DBRetrieveOrder)anOrder for:(id<DBProperties>)aProperty;

- fetchUsingQualifier:(DBQualifier*)aQualifier;
- cancelFetch;

- (BOOL)isModified;
- (BOOL)isNewRecord;
- (BOOL)isReadOnly;
- (DBRecordRetrieveStatus)currentRetrieveStatus;

/*
** saveModifications returns the number of records successfully modified and
**  sent to the database.  For the RecordStream, this will always be either
**  0, 1, or -1 on failure.
*/
- (unsigned)saveModifications;

/*
** These methods are the only way to access the contents of the record
*/
- getValue:(DBValue*)aValue forProperty:aProperty;
- setValue:(DBValue*)aValue forProperty:aProperty;

- getRecordKeyValue:(DBValue*)aValue;

/*
** Record management --
**  Both newRecord and deleteRecord will return nil if they failed (and that
**  failure was not condoned or caught by the delegate).  If they return
**  nil, then the cursor has NOT been advanced; it still points at the
**  same record!!!  In the same way, setNext will return nil
**  if the cursor has not advanced due to a failure.
**
** The delegate has the option of "approving" a failure, by returning
**  YES from recordStream:willFailForReason:  If YES is returned, the cursor
**  will advance and the failure will be ignored.  In this event, if there
**  is an active transaction context, its up to the application to deal with
**  commit/abort.  Otherwise, the failed record will NOT have been committed
**  to the database.
**
** If there is no delegate, or the delegate returns NO from
**  recordStream:willFailForReason:, then the cursor will not advance and
**  whatever action is underway will not occur.
**
** setNext returns self if there are more records, and nil if at end.
*/
- newRecord;
- deleteRecord;
- setNext;

@end

@interface Object (DBRecordStreamDelegate)

/*
** The delegate of the RecordStream is given the opportunity to continue
**  the transaction or abort.  If the delegate returns YES from its
**  recordList:willFailAt:reason: method, the list will attempt to abort
**  a local transaction.  If the transaction is not "owned" by the recordList,
**  it is the responsibility of the app to either rollback or commit.
**  If YES is returned, the list will attempt the rest of its modifications.
**
** If the database being accessed supports transactions, they
**  should always be enabled befo$    Raving modifications.  It is, in general,
**  both safer for the integrity of the data involved and much more
**  efficient to do this.
*/
- (BOOL)recordStream:aRecordStream willFailForReason:(DBFailureCode)aCode;

/*
** The recordStream normally verifies that a record still exists and is
**  unique before modifying or deleting it.  The default mechanism is to
**  do a "confirming select" on the DBDatabase using the key value, and
**  then to compare all properties to see that they haven't changed.  (The
**  select is usually a locking select.)
**
** This entire mechanism can be replaced by implementing the following
**  delegate method.  In this case, verification and locking are up to the
**  delegate object -- if YES is returned, the record is considered to
**  be verified, and modification will proceed.  If NO is returned, the
**  record will not be modified.  This may also cause the entire containing
**  saveModifications: to fail, depending on the transaction model being
**  used.
**
** The only recordStream/recordList method that should be called during this
**  delegate method is getValue:forProperty:
*/
- (BOOL)recordStreamPrepareCurrentRecordForModification:aRecordStream;

@end