OpenStep (Enterprise)/OpenStepENTCD.toast/OEDEV/EODEV.Z/EOSQLQualifier.h

Text File | 1996-09-09 | 6.2 KB | 154 lines

// EOSQLQualifier.h
// Copyright (c) 1994, NeXT Software, Inc. All rights reserved.

#import <EOControl/EOControl.h>

@class EOExpressionArray;
@class EOSQLExpression;
@class EOEntity;
@class EOModel;


//
// This file contains the declarations needed for EOSQLQualifier as well as the
// access layer specific categories of EOQualifier.
//
// EOSQLQualifier contains unstructured text that can be transformed into a SQL
// expression. EOSQLQualifier is provided for backwards compatibility with EOF 1.x
// products and to provide a way that programmers can create SQL expressions with any
// arbitrary SQL. In general, programmers should use EOQualifier whenever possible and
// use EOSQLQualifier only in cases that absolutely require it.
//


// All qualifiers that can be used to generate SQL queries implement this protocol
@protocol EOQualifierSQLGeneration
- (NSString *)sqlStringForSQLExpression:(EOSQLExpression *)sqlExpression;
- (EOQualifier *)schemaBasedQualifierWithRootEntity:(EOEntity *)entity;
    // Returns an equivalent qualifier with object references replaced by foreign
    // key references.
@end


// An EOSQLQualifier holds qualifications expressed in the target query language
// and rooted in a single EOEntity. EOSQLQualifier formats differ from EOQualifier
// formats. EOSQLQualifier formats are not parsed, they are simply scanned for
// keys and format characters. EOSQLQualifiers should be used only when you want
// to use a query available in the database query language that cannot be expressed
// using the EOQualifier formats.
//
// EOSQLQualifiers cannot be applied to objects in memory.
//
// CREATING A SQL QUALIFIER FROM A FORMAT STRING
//
// An EOSQLQualifier format may contain keys(attribute names), key paths
// (attributes referenced through a relationship, format characters
// (e.g. %@, %s, etc), and arbitrary text. The format is scanned by the
// EOSQLQualifier class and the keys, key paths, and format characters.
// The keys and key paths are substituted with the appropriate column
// names and the format characters are replaced by the argument
// indicated by the format characters. All SQL syntax is the
// responsibility of the coder. EOSQLQualifier does not attempt to
// understand the contents of the format string.

// The following are examples of simple EOSQLQualifier format strings.
// In these examples, the keys "lastName" and "royalty" will be replaced
// with the appropriately aliased column names as will the key path
// "publisher.name".
//     lastName = "smith"
//     royalty > 2.5
//     toPublisher.name = "Eco Publishing House"
//
// An EOSQLQualifier's format string recognizes the following format characters.
//
//    %s expects a (char *) argument
//    %A expects an (NSString *) argument, which should be a key or key path
//    %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:
//       valueForSQLExpression:(EOSQLExpression *)context
//    %% is a '%' passed through.
//    % followed by any other character is ignored
//

// The following examples build qualifiers similar to the above examples but
// use format characters to build the values from a existing EO. In these
// examples, we assume that the EO has implemented the following accessor methods:
//    - (NSString *)lastName;
//    - (float)salary;
//
//     myQualifier = [[EOSQLQualifier alloc] initWithEntity:authorEntity
//         qualifierFormat:"%A = '%@'", @"last_name", [anAuthur lastName]];
//
//     myQualifier = [[EOSQLQualifier alloc] initWithEntity:authorEntity
//         qualifierFormat:"%A > %f", @"royalty", [anAuthur salary]];
//
// Since it is the responsibility of the programmer to ensure that all formatting
// is correct in the resulting SQL statement, it is sometimes useful to use a
// particular adaptor for doing certain formatting tasks like quoting strings,
// formatting dates, etc.
//
// The next example calls the method formatValue:forAttribute: on the adaptor
// specific subclass of EOSQLExpression to ensure that certain values are
// formatted correctly. 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 = [[EOSQLQualifier alloc] initWithEntity:authorEntity
//         qualifierFormat:"%A = %@", [attribute name],
//       [[adaptor expressionClass] formatValue:[anAuthor lastName]
//        forAttribute:attribute]];


//
// This category is access layer specific since it uses information contained in an EOModel
//
@interface EOQualifier (EOModelExtensions)
- (EOQualifier *)qualifierMigratedFromEntity:(EOEntity *)entity relationshipPath:(NSString *)relationshipPath;
    // Create a new qualifier by moving the qualifier from the source entity to
    // the destination of the relationship path. This method a returns a copy
    // the reciever with all of the keys translated to work with the specified
    // relationshipPath.
@end


//
// All of the EOF supplied qualifiers conform to the EOQualifierSQLGeneration
// protocol, so we declare that here.
//
@interface EOAndQualifier (EOQualifierSQLGeneration) <EOQualifierSQLGeneration>
@end
@interface EOOrQualifier (EOQualifierSQLGeneration) <EOQualifierSQLGeneration>
@end
@interface EOKeyComparisonQualifier (EOQualifierSQLGeneration) <EOQualifierSQLGeneration>
@end
@interface EOKeyValueQualifier (EOQualifierSQLGeneration) <EOQualifierSQLGeneration>
@end
@interface EONotQualifier (EOQualifierSQLGeneration) <EOQualifierSQLGeneration>
@end


//
// Finally, declare the EOSQLQualifier class.
//
@interface EOSQLQualifier : EOQualifier <EOQualifierSQLGeneration> {
    EOEntity *_entity;
    EOExpressionArray *_contents;
    struct {
    unsigned int usesDistinct:1;
    unsigned int _RESERVED:31;
    } _flags;
}

+ (EOQualifier *)qualifierWithQualifierFormat:(NSString *)format, ...;
    // This method overrides the superclass method and always raises an exception.
    // EOSQLQualifier must be initialized with an entity and this method does not
    // provide one. Creators of EOSQLQualifier should invoke the
    // initWithEntity:qualifierFormat: method.

- initWithEntity:(EOEntity *)entity qualifierFormat:(NSString *)qualifierFormat, ...;
    // This is the designated initializer for EOSQLQualifier.

@end