DBQualifier

DBQualifier

Inherits From: Object

Conforms To: DBExpressionValues

Declared In: dbkit/DBQualifier.h

Class Description

A DBQualifier object creates a predicate statement, expressed in the database's query language, that's applied as records are fetched from the database. Records that don't pass the predicate, or description, aren't selected for the fetch. The predicate that's created by a description is usually one or more expressions in which the value for a property is compared to that of another property or to a constant value.

Creating a Description
A DBQualifier's description is created through the initForEntity:fromDescription: or, after initialization, setEntity:andDescription: methods. You can add to an existing description through the addDescription: method. Each of these methods takes a printf() style format-and-values list as its final argument: The first element (the format) is a quoted string that establishes the format of the description, the following elements supply the description with values. Neighboring elements are separated by a comma.
Strings, numbers, and objects can be represented in the format string through the following substitution symbols:

Format symbol Expected value

%s A constant string (const char *).

%p A (const char *) that names a property of the object's entity.

%d An int.

%f A double or float.

%@ An object that conforms to the DBExpressionValues protocol, or a property object created by the Database Kit. (The former includes DBQualifier, allowing you to created a nested qualification.)

%% No value--this passes a single `%' literally.

The rest of the format string should comprise valid query-language operators and symbols, the names of properties, and whitespace. The description is automatically applied as a predicate, so you needn't include the query language's predicate operator yourself. For example, if you're using SQL, a "WHERE" is automatically prepended to your description.
By using the substitution symbols, the same description can be created in a number of different ways. As an example, let's say you want to retrieve records from the "Grocers" table, but you only want those grocers that have a hat size greater than 12.5 and an IQ less than 95. You could create a DBQualifier thus:

/* The DBDatabase object db is assumed to exist. */
id grocers = [db entityNamed:"Grocers"];
id hatProp = [grocers propertyNamed:"hatsize"];
id iqProp = [grocers propertyNamed:"iq"];
float minHat = 12.5;
int maxIQ = 95;

/* Create the qualifier. */
DBQualifier *bigButEmpty =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"%@ > %f AND %@ < %d",
hatProp, minHat, iqProp, maxIQ];

/* Apply it to a fetch (assume that the DBRecordList exists). */
[aRecList fetchUsingQualfier:bigButEmpty];

Using the convenience of the "%p" substitution, the same description could have been created without the use of property objects:

DBQualifier *bigButEmpty =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"%p > %f AND %p < %d",
"hatsize", minHat, "iq", maxIQ];

Simpler yet, the property names (and comparison values) can appear directly in the description string:

DBQualifier *bigButEmpty =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"hatsize > 12.5 AND iq < 95"];

Property names, whether specified as arguments (to the %p symbol) or placed directly in the description string, are resolved against the DBQualifier's entity. For example, the two properties used above are resolved as "Grocers.hatsize" and "Grocers.iq".

Traversing a Relationship
You can specify a related property in a DBQualifier's description string. To do this, you simply name the property as it's known to the DBQualifier's entity--in other words, you have to include the name of the relationship (which must be to-one). In the following example, each grocer's hat size is compared to that of his janitor:

DBQualifier *biggerThanMrBroom =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"hatsize > toJanitor.hatsize"];

This description can also be constructed using the substitution symbols:

DBQualifier *biggerThanMrBroom =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"%p > %p",
"hatSize", "toJanitor.hatsize"];

Or:

id janitorRel = [grocers propertyNamed:"toJanitor"];
id janHatProp = [[janitorRel propertyValue]
propertyNamed:"hatsize"];

DBQualifier *biggerThanMrBroom =
[[DBQualifier alloc] initForEntity:grocers
fromDescription:"%@ > %@.%@",
hatSize, janitorRel, janHatProp];

Applying a DBQualifier
Once you've created a DBQualifier, there are two ways to apply it:

If you're using a DBRecordStream or DBRecordList, you can qualify a fetch by passing a DBQualifier object as the argument to the fetchUsingQualifier: method. The DBQualifier's entity must match that of the DBRecordStream/List to which it's applied.

If you're using a DBBinder, you can set the qualifier that's used in subsequent selects through setQualifier: or initForDatabase:withProperties:andQualifier:. (DBBinder separates the select and fetch operations; the qualification is actually placed on the select.)

Instance Variables

None declared in this class.

Adopted Protocols

DBExpressionValues expressionValue

isDeferredExpression

Method Types

Initializing and freeing + initialize

initForEntity:
initForEntity:fromDescription:
copyFromZone:
free

Modifying addDescription:

setEntity:andDescription:
setName:
empty

Querying name

entity
isEmpty

Archiving read:

write:

Instance Methods

addDescription:

addDescription:(const unsigned char *)descriptionFormat, ...

Appends the string that's created by the arguments to the DBQualifier's current description. The arguments are in the style of a printf() statement; see the class description above for the rules governing the format of the description string. Returns self.
See also: initForEntity:fromDescription:, setEntity:andDescription:

copyFromZone:

copyFromZone:(NXZone*)z

Creates a copy of the DBQualifier, allocating space for it from zone z. Returns the copy.

empty

(BOOL)empty

Deletes the DBQualifier's description. Returns YES.
See also: isEmpty

entity

(id <DBEntities>)entity

Returns the DBQualifier's entity, as set through setEntity:andDescription: or one of the initForEntity: methods.
See also: initForEntity:fromDescription:, setEntity:andDescription:

free

free

Frees the DBQualifier.

initForEntity:

initForEntity:(id <DBEntities>)anEntity

The designated initializer for the DBQualifier class, this initializes a freshly allocated DBQualifier by setting its entity to the argument, but leaves its description empty. Returns self.
See also: initForEntity:fromDescription:, setEntity:andDescription:

initForEntity:fromDescription:

initForEntity:(id <DBEntities>)anEntity

fromDescription:(const unsigned char *)descriptionFormat, ...

Initializes a freshly allocated DBQualifier by setting its entity to anEntity and setting its description as specified by the other arguments. See the class description above for the rules governing the format of the description string.
See also: initForEntity:, setEntity:andDescription:

isEmpty

(BOOL)isEmpty

Returns YES if the DBQualifier's description is empty (if it hasn't been set or if the object has received an empty message). If the DBQualifier has a description, this returns NO.
See also: empty

name

(const char *)name

Returns the name of the DBQualifier, as set through setName:. The ability to name a DBQualifier is provided as a convenience; it isn't used by the Database Kit.
See also: setName:

read:

read:(NXTypedStream *)stream

Reads the DBQualifier from the typed stream stream. Returns self.

setEntity:andDescription:

setEntity:(id <DBEntities>)anEntity

andDescription:(const unsigned char *)descriptionFormat, ...

Sets the DBQualifier's entity and description as given by the arguments. See the class description, above, for information on the description format. Returns self.
See also: addDescription:, initForEntity:fromDescription:

setName:

(BOOL)setName:(const char *)aName

Sets the name of the DBQualifier to aName. The name isn't essential, as discussed in the name method description. Returns YES.
See also: name

write:

write:(NXTypedStream *)stream

Writes the DBQualifier to the typed stream stream. Returns self.

	Inherits From:	Object

	Conforms To:	DBExpressionValues

	Declared In:	dbkit/DBQualifier.h

	Format symbol	Expected value

	%s	A constant string (const char *).

	%p	A (const char *) that names a property of the object's entity.

	%d	An int.

	%f	A double or float.

	%@	An object that conforms to the DBExpressionValues protocol, or a property object created by the Database Kit. (The former includes DBQualifier, allowing you to created a nested qualification.)

	%%	No value--this passes a single `%' literally.

		If you're using a DBRecordStream or DBRecordList, you can qualify a fetch by passing a DBQualifier object as the argument to the fetchUsingQualifier: method. The DBQualifier's entity must match that of the DBRecordStream/List to which it's applied.

		If you're using a DBBinder, you can set the qualifier that's used in subsequent selects through setQualifier: or initForDatabase:withProperties:andQualifier:. (DBBinder separates the select and fetch operations; the qualification is actually placed on the select.)