Where an application uses a custom subclass of DB Association to record the link between a data source (such as a DBRecordList or the contents of a DBBinder), the object in the user interface that displays the associated data should implement methods from this informal protocol. They correspond to instance methods in DBAssociation.
Method Types
Access to the associated value - association:setValue:
- association:getValue:
Notifications to the associated display
- associationContentsDidChange:
- associationSelectionDidChange:
- associationCurrentRecordDidDelete:
Instance Methods
association:getValue:
- association:association getValue:(DBValue *)value
Gets the value of the associated destination, and copies it to value. Returns self.
See also: - getValue: (DBAssociation class)
association:setValue:
- association:association setValue:(DBValue *)value Causes the destination to display value. Returns self.
See also: - setValue: (DBAssociation class)
associationContentsDidChange:
- associationContentsDidChange:association
Notification that there has been a change to the data values in a portion of the DBFetchGroup's DBRecordList, necessitating a corresponding change in the user interface object.
associationCurrentRecordDidDelete:
- associationCurrentRecordDidDelete:association
Notification that the current record has been deleted from the DBFetchGroup's DBRecordList, necessitating a corresponding change in the user interface object.
associationSelectionDidChange:
- associationSelectionDidChange:association
Notification that there has been some sort of change in the current record of the
DBFetchGroup. The change could be to change the selection to a different row, or to add a selection, or to deselect an existing section so that no row is selected. Usually the change is produced by something the user did.
4-182 Chapter 4: Database Kit
DBEntities
Adopted By: no N eXTSTEP classes Incorporates: DBTypes
Declared In: dbkitlentities.h
Protocol Description
The DBEntities protocol lets an object represent a database entity. An entity comprises a list of data categories, or properties. As data is read from a database for a particular entity, an "instance" of the entity (a record) is created and filled with data, one datum per property.
It's tempting to speak of an entity as a database table. They're similar. You can think of a table as the corporealization of an entity. Put another way, an entity describes how a table organizes its data into columns (properties). However, you should keep in mind that an entity doesn't contain data (nor do the properties within the entity). Furthermore, neither entities nor properties are "placeholders" for data. Entities and properties neither store nor make room for data, they simply provide a description of the type and location of data so some other object (a record) can be created to adequately store this data.
Typically, an application doesn't create entity objects directly, but, instead, reads them from a database model file. This is performed by creating a DBDatabase object and connecting it to the file (through methods described in the DBDatabase class specification). You can retrieve, in a List, the entity objects that the DBDatabase read from the model file by sending the DBDatabase a getEntities: message. Alternatively, you can retrieve a single entity object by name through entityNamed:. Both of these methods return private DB Entities-conforming objects that are created and owned by the Database Kit.
Entity object are used as arguments in a handful of important methods. Most notable of these, you typically use an entity as the source in an invocation of DBRecordList's setProperties:ofSource:. In addition, an entity is required by the DB Qualifier and DBExpression initialization methods.
The DBEntities protocol incorporates the DBTypes protocol. It does this for one reason:
the type of Objective C data described by a property that represents a relationship is a DBEntities object. Thus, if the isEntity message returns YES when sent to the value returned by sending propertyType to a property, then that property is a relationship. This is demonstrated in the following example:
/* Get the properties from an entity. Check for relationships. */
int counter;
List *propList = [[List alloc] init];
id prop;
[anEntity getProperties:propList];
for (counter = 0; counter < [aList count]; counter++) prop=[aList objectAt:counter];
if ([[prop propertyType] isEntity])
printf("Property named %s is a relationship.\n", [prop name]);
Warning: You should never send the DB Types messages objcClassName or databaseType to the private entity objects that are returned by the aforementioned DBDatabase methods. The private entity class implements these DBTypes methods to raise
DB _UNIMPLEMENTED_ERROR exceptions.
It isn't anticipated that you should need to create your own class that adopts the DB Entities protocol. The entity objects returned by getEntities: and entityNamed: should be adequate for most applications.
Method Types
Querying the object -name - database - getProperties:
- property Named:
Comparing the object - matchesEntity:
4-184 Chapter 4: Database Kit
Instance Methods
database
- (DBDatabase *)database
Returns the DBDatabase object that created the entity.
getProperties:
- getProperties:(List *)aList
Returns, in aList, a list of the entity's properties. Each object in the list conforms to the DB Properties protocol.
matchesEntity:
- (BOOL)matchesEntity:(id <DB Entities> )anEntity
Returns YES or NO if the receiving entity and anEntity were created from the same model file entity.
name
- (const char *)name
Returns the entity's name. This is the same name as given to the entity in the model file from which it was read.
propertyNamed:
- propertyNamed:(const char *)aName
Returns the property named aName. If the entity has no such property, nil is returned.
DBExpressionValues
Adopted By:
Declared In:
DB Expression DB Qualifier DB Value
dbkitlexpression Values.h
Protocol Description
The DBExpressionValues protocol allows an object to be used in a query-language statement. Its principal method, expression Value, returns a string that gives an object's representation as it should appear in such a statement.
A second method, isDeferredExpression, returns a boolean that indicates whether the invocation of expressionValue should be deferred until the "last possible moment." This is useful for classes, such as DBExpression, that concatenate values stored in separate objects. As the larger expression is being built, the DB Expression asks each of the value-holding objects whether it is deferred. If the values aren't deferred, it can send an expression Value message as soon as the value-holding object is added. But if any is deferred, it should delay until all the objects are in place, and then send an expression Value message to each of them.
Instance Methods
expressionValue
- (const char *)expression Value
Returns the value of an expression object as a string that represents the expression in the query language.
isDeferredExpression
- (BOOL)isDeferredExpression
Returns YES if evaluation of the expression should be deferred (for example, until related expressions are ready).
4-186 Chapter 4: Database Kit
DBForl11atConversion
(informal protocol)
Category Of:
Declared In:
Object
dbkiticustomType.h
Category Description
This category is the companion of the category DBFormatInitialization. The two provide part of the mechanism the Database Kit uses to transfer Objective C objects between the database and the application. DBFormatConversion provides a method that specifies the format of the data contained in a buffer that the adaptor will use while transferring data from the application to the database. You'll need explicit use of these methods only if your application uses formats other than those already supported in the Database Kit. (The kit supports any object in the archive format appropriate to its class, as well as NXData using RTF format, or NXImage using TIFF or BPS format.)
Instance Methods
writeBuffer:ofLength:usingFormat:
- writeBuffer:(void **)bufferPtr ofLength:(unsigned *)lengthPtr
usingFormat:(const char *)aFormatName;
If your application creates a custom class that's associated with a property and your class implements this method, this method will be invoked automatically when the Database Kit tries to store the object into the database.
The pointer *bufferPtr may point either to an existing buffer or to NULL. If it points to an existing buffer, *lengthPtr points to the buffer's length. But if *bufferPtr points to NULL, the method should allocate space for a new buffer as needed, and should write the length it allocates into the location that *lengthPtr points to.
The argument aFormatName is a string containing the name of the format in which the data is written. The Database Kit defines the following names for formats:
• "EPS"
• "RTF"
• "TIFF"
Alternatively, the string may be the name of any type your application recognizes, as declared in DBModeler's Attribute Inspector for data of type Object.
4-188 Chapter 4: Database Kit
DBForl11atlnitialization
(informal protocol)
Category Of: Object Declared In: dbkitltypes .h
Category Description
This category is the companion of the category DBFormatConversion. The two provide part of the mechanism the Database Kit uses to transfer Objective C objects between the database and the application. DBFormatInitialization provides a method that specifies the format of the data contained in a buffer that the adaptor uses while reading data from the database. You'll need explicit use of these methods only if your application uses formats other than those already supported in the Database Kit. (The kit supports any object in the archive format appropriate to its class, as well as NXData using RTF format, or NXImage using TIFF or EPS format.)
Instance Methods
initFromBuffer:ofLength:withFormat:
- initFromBuffer:(void *)buffer oiLength: (unsigned)length
withFormat:(const char *)aFormatName
If your application creates a custom class that's associated with a property and your class implements this method, this method will be invoked automatically when the Database Kit tries to read data from the database for delivery as an instance of your class.
The argument buffer is an already allocated buffer, and length describes the buffer's length.
The argument aFormatName is a string containing the name of the format in which the data is written. The Database Kit defines the following names for formats:
• "EPS"
• "RTF"
• "TIFF"
Alternatively, the string may be the name of any type your application recognizes, as declared in DBModeler's Attribute Inspector for data of type Object.
DBForl11atterValidation
(informal protocol)
Category Of:
Declared In:
Object
dbkititableProtocols.h
Category Description
This informal protocol is one of the mechanisms the Database Kit uses to place objects into the database. If a class is associated with a property and it implements this method, this method will be called when the kit tries to store the object into the database.
Method Types
Notifications by identifiers - formatterDidChange ValueFor: :to:sender:
- formatterWillChange ValueFor: : sender:
- formatterWillChange ValueFor: :to:sender:
Notification by position - formatterDidChange ValueFor: atto: sender:
- formatterWillChange ValueFor:atsender:
- formatterWillChange ValueFor:at:to:sender:
Instance Methods
formatterDidChangeValueFor::sender:
- formatterDidChange ValueFor:rowldentifier :columnldentifer
sender:sender
Notification that may be sent when the formatter has changed the value in a field. The field that changed is identified by its rowldentifier and its columnldentifier (for the situation in which both rows and columns are static).
The argument sender is the sender of the message (usually a formatter). Returns self.
4-190 Chapter 4: Database Kit
formatterDidChangeValueFor::to:sender:
- formatterDidChangeValueFor:rowldentifier :columnldentifer
to:aValue sender: sender
Notification that may be sent when the formatter has changed the value in a field. The field that changed is identified by its rowldentifier and its columnldentifier (for the situation in which both rows and columns are static).
The argument a Value is the object that contains the new value. The argument sender is the sender of the message (usually a formatter). Returns self.
formatterDidChangeValueFor:at:sender:
- formatterDidChangeValueFor:identifier at: (unsigned int )position
sender:sender
Notification that may be sent when the formatter has changed the value in a field. The field that changed is identified by its identifier (usually associated with a column, but could be the identifier of a row if rows are static) and its position (usually a row number, but could be a column number if columns are dynamic).
The argument sender is the sender of the message (usually a formatter). Returns self.
formatterDidChangeValueFor:at:to:sender:
- formatterDidChange ValueFor: identifier at: (unsigned int )position
to:aValue sender:sender
Notification that may be sent when the formatter has changed the value in a field. The field that changed is identified by its identifier (usually associated with a column, but could be the identifier of a row if rows are static) and its position (usually a row number, but could be a column number if columns are dynamic).
The argument a Value is the object that contains the new value. The argument sender is the sender of the message (usually a formatter). Returns self.
formatterWiIIChangeValueFor::to:sender:
- (BOOL)formatterWilIChangeValueFor:rowldentifier :columnldentifier
to:aValue sender:sender
Notification that may be sent when the formatter is about to change the value in a field. The field in which the proposed chaI}ge will take place is identified by its rowldentifier and its columnldentifier (for the situation in which both rows and columns are static).
The argument aValue is the object that contains the proposed new value. The argument sender is the sender of the message (usually a formatter). Returning YES permits the change to be recorded in the record list (and thus ultimately in the database).
formatterWiIIChangeValueFor:at:to:sender:
- (BOOL)formatterWiIlChangeValueFor:identifier at: (unsigned int )position
to:aValue sender:sender
Notification that may be sent when the formatter is about to change the value in a field. The field in which the proposed change will take place is identified by its identifier (usually associated with a column, but could be the identifier of a row if rows are static) and its position (usually a row number, but could be a column number if columns are dynamic).
The argument a Value is the object that contains the proposed new value. The argument sender is the sender of the message (usually a formatter). Returning YES permits the change to be recorded in the record list (and thus ultimately in the database).
4-192 Chapter 4: Database Kit
DBForl11atterVievvEditing
Adopted By: no NeXTSTEP classes Declared In: dbkitIDBEditableFormatter.h
Protocol Description
The method in this protocol provides a means by which a view containing a field that is being edited can receive a message from the object doing the editing (for example, an instance of DBEditableFormatter).
Instance Methods
formatterDidEndEditing:endChar:
- (BOOL)formatterDidEndEditing:sender endthar:(unsigned short)whyEnd Invoked by an editor when the user completes editing of an editable field by pressing one of the keys that moves to another field (Return, Tab, or Shift-Tab). The field that was being edited is redrawn, and the cursor is moved to the next field, depending on which character was whyEnd: NX_RETURN, NX_TAB, or NX_BACKTAB. Returns YES, unless invoked while no field was being edited.