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

Text File | 1994-12-06 | 5.7 KB | 142 lines

// EOQualifier.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 EOEntity;
@class EOExpressionArray;
@class EORelationship;
@class EOAdaptor;

// An EOQualifier holds qualifications expressed in the target query language
// and rooted in a single EOEntity.  You can build a qualifier with a
// printf()-style format string or directly from an existing Enterprise Object
// or row fetched from the database.
//
// CREATING A SQL QUALIFIER FROM A FORMAT STRING
//
// A qualifier string must contain only the internal names of properties
// belonging to the qualifiers entity and relational operators (=, >, <, >=,
// <=).  For example, if you have an Author entity with the properties
// author_id, first_name, last_name, royalty, and toPublisher, and a Publisher
// entity with properties pub_id, name, address, the following are valid
// qualifier strings:
//     last_name = "smith"
//     royalty > 2.5
//     toPublisher.name = "Eco Publishing House"
//
// An EOQualfier's format string can embed strings, numbers, and other objects
// using the conversion specifications in the table below.  This allows
// qualifiers to be built dynamically based on the return values of methods.
//
//    %s expects a (char *) argument, which is passed through
//         (and possibly quoted by the database)
//    %A expects an (NSString) argument, which is resolved as a property
//         name.
//    %d expects an integer argument
//    %f expects a float or double argument
//    %@ expects an id argument -- valid objects are EOAttribute,
//         NSString, or anything that responds reasonably to:
//       expressionValueForContext:(id <EOExpressionContext>)context
//    %% is a '%' passed through...
//    % followed by any other character is ignored
//

// The following code excerpts build qualifiers similar to the
// qualifier strings mentioned above, but can take the particular values
// to compare from an already-fetched Enterprise Object:
//
//     myQualifier = [[EOQualifier alloc] initWithEntity:authorEntity
//         description:"%A = '%@'", @"last_name", [anAuthorObject lastName]];
//     myQualifier = [[EOQualifier alloc] initWithEntity:authorEntity
//         description:"%A > %f", @"royalty", [anAuthorObject salary]];
//
// The Enterprise Object classes here implement convenience methods for
// directly accessing the given attributes: -lastName and -salary for author
// Enterprise Objects, and -lastName for publisher Enterprise Objects.

// The next example calls the method formatValue:forAttribute: on the adaptor.
// This method looks at the attribute and returns a correctly formatted value
// that is suitable for this specific adaptor. In this case, since the
// attribute is a string type, the method will return a quoted copy of the
// with any embedded quotes suitably escaped.
//     myQualifier = [[EOQualifier alloc] initWithEntity:authorEntity
//         description:"%A = %@", [attribute name],
//       [adaptor formatValue:[aPublisherObject lastName]
//        forAttribute:attribute]];


@interface EOQualifier:NSObject <NSCopying>
{
    EOEntity *_entity;
    EOExpressionArray *_contents;
    EORelationship *_flattenedRelationship;
    struct {
    unsigned int usesDistinct:1;
    unsigned int _RESERVED:31;
    } _flags;
}

+ (EOQualifier *)qualifierForPrimaryKey:(NSDictionary *)key
    entity:(EOEntity *)entity;
    // Creates a qualifier for the entity based on the primary key dictionary
    // Such a qualifier will select only the row or object with the primary
    // key supplied.

+ (EOQualifier *)qualifierForRow:(NSDictionary *)row
    relationship:(EORelationship *)relationship;
    // Creates a qualifier for the destination of row's relationship.  This
    // qualifier will select only the row whose primary key matches the given
    // row's foreign key for the relationship.

+ (EOQualifier *)qualifierForObject:sourceObject relationship:(EORelationship *)relationship;
    // Creates a qualifier for the destination of eo's relationship.  This
    // qualifier will select only the row whose primary key matches the eo's
    // foreign key for the relationship.  The EO must store all of the necessary
    // foreign keys as class properties.

- initWithEntity:(EOEntity *)entity
    qualifierFormat:(NSString *)qualifierFormat, ...;
    // Initializes a newly allocated EOQualifier to be rooted in the given
    // entity and to build itself from the format string.  The
    // format string is a printf()-style format string as described at
    // the top of this header file.

- (BOOL)isEmpty;
    // Returns YES if the qualifier will select the entire table for its
    // entity (that is, if has no qualifying information).

- (void)setUsesDistinct:(BOOL)yn;
- (BOOL)usesDistinct;
    // Sets/returns whether the qualifier eliminates duplicates from results.
    // If a select would yield the same row many times, a qualifier that
    // usesDistinct eliminates all duplicates after the first.

- (EOEntity *)entity;
    // Returns the entity that roots data paths in the qualifier.  Any
    // reference to an attribute or relationship in the qualifier must belong
    // to the root entity.

@end


@interface EOQualifier(EOQualifierEditing)

- (void)negate;
    // Negates the entire qualifier.

- (void)conjoinWithQualifier:(EOQualifier *)qualifier;
    // Replaces the contents of the qualifier with the conjunction (logical
    // AND) of the existing contents and the argument.

- (void)disjoinWithQualifier:(EOQualifier *)qualifier;
    // Replaces the contents of the qualifier with the disjunction (logical
    // OR) of the existing contents and the argument.

@end