home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOSQLExpression.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  12.3 KB  |  263 lines
  1. // EOSQLExpression.h
  2. // Copyright (c) 1994, NeXT Software, Inc. All rights reserved.
  3.  
  4. #import <Foundation/Foundation.h>
  5. #import <EOAccess/EORelationship.h>
  6. #import <EOAccess/EODefines.h>
  7.  
  8. @class EOQualifier;
  9. @class EOEntity;
  10. @class EOAttribute;
  11.  
  12. // Adaptors must be capable of performing four basic operations:
  13. // select, insert, update, and delete. The default implementation in
  14. // the abstract super class obtains the adaptor's query language
  15. // expression class, instantiates an expression describing the operation,
  16. // and passes the expression as an argument to evaluateExpression:.
  17. // This is the default expression class for SQL adaptors.
  18. //
  19. // The class will need to be subclassed for specific databases. Normally
  20. // each adaptor will provide its own subclass.
  21. //
  22. // This is class (and its subclasses) are designed for use by anyone who
  23. // needs to assemble SQL expressions.
  24.  
  25. @interface EOSQLExpression : NSObject
  26. {
  27.     NSMutableDictionary *_aliasesByRelationshipPath;
  28.     EOEntity *_entity;
  29.     NSMutableString *_listString;
  30.     NSMutableString *_valueListString;
  31.     NSString *_whereClauseString;
  32.     NSMutableString *_joinClauseString;
  33.     NSMutableString *_orderByString;
  34.     NSMutableArray *_bindings;
  35.     NSMutableArray *_contextStack;
  36.     NSString *_statement;
  37.     BOOL _useAliases;
  38. }
  39.  
  40. // Designated initializer
  41. - initWithEntity:(EOEntity *)entity;
  42.  
  43. + (EOSQLExpression *)expressionForString:(NSString *)string;
  44.     // Create an expression for the given string
  45.  
  46. // Factory Methods for creating an insert, update, delete, or select statement
  47. + (EOSQLExpression *)insertStatementForRow:(NSDictionary *)row entity:(EOEntity *)entity;
  48.     // Builds a SQL INSERT expression to perform the requested operation
  49.  
  50. + (EOSQLExpression *)updateStatementForRow:(NSDictionary *)row qualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity;
  51.     // Builds a SQL UPDATE expression to perform the requested operation
  52.  
  53. + (EOSQLExpression *)deleteStatementWithQualifier:(EOQualifier *)qualifier entity:entity;
  54.     // Builds a SQL DELETE expression to perform the requested operation
  55.  
  56. + (EOSQLExpression *)selectStatementForAttributes:(NSArray *)attributes lock:(BOOL)yn
  57.     fetchSpecification:(EOFetchSpecification *)fetchSpecification
  58.     entity:(EOEntity *)entity;
  59.     // Builds a SQL SELECT expression to perform the requested operation
  60.  
  61. // Accessor methods
  62. - (NSMutableDictionary *)aliasesByRelationshipPath;
  63. - (EOEntity *)entity;
  64.  
  65. // These strings are built up incrementally by appending to the mutableStrings
  66. // below.  E.g. addUpdateListAttribute:value: appends a formated value to
  67. // listString.
  68. - (NSMutableString *)listString;
  69. - (NSMutableString *)valueList;
  70. - (NSMutableString *)joinClauseString;
  71. - (NSMutableString *)orderByString;
  72. - (NSString *)whereClauseString;
  73. - (NSString *)statement;
  74. - (void)setStatement:(NSString *)statement;
  75.  
  76. // These methods use the internal state of the SQLExpression to generate a syntactic
  77. // component of a SQLExpression
  78. - (NSString *)lockClause;
  79.     // Returns a the SQL string which will cause the RDBMS to place a pessimistic lock on
  80.     // any rows fetched
  81.  
  82. - (NSString *)tableListWithRootEntity:(EOEntity *)entity;
  83.     // Returns a list of aliased table names that can be used as the "FROM" part of a
  84.     // SQL expression
  85.  
  86.  
  87. // Instance methods for creating an insert, update, delete, or select statement
  88. - (void)prepareInsertExpressionWithRow:(NSDictionary *)row;
  89.     // Invokes the following methods:
  90.     //    [self addInsertListAttribute:] for each att in row
  91.     //  [self tableListWithRootEntity:]
  92.     //    [self assembleInsertStatementWithTableList: ...]
  93.     
  94. - (void)prepareUpdateExpressionWithRow:(NSDictionary *)row qualifier:(EOQualifier *)qualifier;
  95.     // Invokes the following methods:
  96.     //    [self addUpdateListAttribute:att value:value] for each att in row
  97.     //  [qualifier sqlStringForSQLExpression:self]
  98.     //    [self tableListWithRootEntity:]
  99.     //    [self assembleUpdateStatementWithTableList: ...]
  100.  
  101. - (void)prepareDeleteExpressionForQualifier:(EOQualifier *)qualifier;
  102.     // Invokes the following methods:
  103.     //    [qualifier sqlStringForSQLExpression:self]
  104.     //    [self tableListWithRootEntity:]
  105.     //    [self assembleDeleteStatementWithTableList: ...]
  106.  
  107. - (void)prepareSelectExpressionWithAttributes:(NSArray *)attributes lock:(BOOL)yn fetchSpecification:(EOFetchSpecification *)fetchSpecification;
  108.     // Invokes the following methods:
  109.     //  [self addSelectListAttribute:] for each att in attributes
  110.     //    [qualifier sqlStringForSQLExpression:self]
  111.     //    [self addOrderByAttributeOrdering:] for each attributeOrdering in fetchOrders
  112.     //    [self joinExpression]
  113.     //    [self tableListWithRootEntity:_entity]
  114.     //    [self lockClause]
  115.     //    [self assembleSelectStatementWithSelectString: ...]
  116.  
  117.  
  118. // These three methods are used to generate the part of the where clause that specifies the
  119. // join conditions based on the relationships used in this SQLExpression
  120. - (NSString *)assembleJoinClauseWithLeftName:(NSString *)leftName rightName:(NSString *)rightName joinSemantic:(EOJoinSemantic)semantic;
  121.     // Invoked repeatedly by joinExpression to assemble each simple join expression clause.
  122.  
  123. - (void)addJoinClauseWithLeftName:(NSString *)leftName rightName:(NSString *)rightName joinSemantic:(EOJoinSemantic)semantic;
  124.     // Calls assembleJoinClauseWithLeftName: ... and then appends the resulting string to the
  125.     // joinClause string
  126.  
  127. - (void)joinExpression;
  128.     // Invokes assembleJoinClauseWithLeftName:rightName:joinOperator:joinSemantic on each join pair
  129.     // in each relationship listed in the aliasesByRelationshipPaths dictionary
  130.  
  131.  
  132. // The following four methods allow subclassers to override the assembling of the SQL pieces into
  133. // a SQL statement
  134. - (NSString *)assembleInsertStatementWithRow:(NSDictionary *)row tableList:(NSString *)tableList columnList:(NSString *)columnList valueList:(NSString *)valueList;
  135.  
  136. - (NSString *)assembleUpdateStatementWithRow:(NSDictionary *)row qualifier:(EOQualifier *)qualifier tableList:(NSString *)tableList updateList:(NSString *)updateList whereClause:(NSString *)whereClause;
  137.  
  138. - (NSString *)assembleDeleteStatementWithQualifier:(EOQualifier *)qualifier tableList:(NSString *)tableList whereClause:(NSString *)whereClause;
  139.  
  140. - (NSString *)assembleSelectStatementWithAttributes:(NSArray *)attributes lock:(BOOL)lock qualifier:(EOQualifier *)qualifier fetchOrder:(NSArray *)fetchOrder selectString:(NSString *)selectString columnList:(NSString *)columnList tableList:(NSString *)tableList whereClause:(NSString *)whereClause joinClause:(NSString *)joinClause orderByClause:(NSString *)orderByClause lockClause:(NSString *)lockClause;
  141.  
  142. // Used for assembling the different syntactic bits and pieces
  143. - (void)addSelectListAttribute:(EOAttribute *)attribute;
  144.     // Adds the aliased column name for attribute to the listString instance variable
  145.  
  146. - (void)addInsertListAttribute:(EOAttribute *)attribute value:(NSString *)value;
  147.     // Adds the column name for attribute to the listString and value to the valueList string.
  148.     // calls [[self class] formatValue:forAttribute]
  149.  
  150. - (void)addUpdateListAttribute:(EOAttribute *)attribute value:(NSString *)value;
  151.     // Adds the column name for attribute and value to the listString attribute.
  152.     // calls [[self class] formatValue:forAttribute:]
  153.  
  154.  
  155. + (NSString *)formatStringValue:(NSString *)string;
  156.     // Format an NSString for use as a string constant in a SQL statement.
  157.     // Enclose in single quotes and escape any single quotes in the string.
  158.  
  159. + (NSString *)formatValue:(id)value forAttribute:(EOAttribute *)attribute;
  160.     // Returns a formatted string representation of value that is suitable for use in a sql statement
  161.  
  162. + (NSString *)formatSQLString:(NSString *)sqlString format:(NSString *)format;
  163.     // Format is one of the read or write formats specified on the attribute.
  164.     // Returns a new string based on the format passed in, if format is nil then it
  165.     // just returns the sqlString.
  166.  
  167. // The following methods are used in conjunction with EOQualifier
  168. - (NSString *)sqlStringForConjoinedQualifiers:(NSArray *)qualifiers;
  169. - (NSString *)sqlStringForDisjoinedQualifiers:(NSArray *)qualifiers;
  170. - (NSString *)sqlStringForNegatedQualifier:(EOQualifier *)qualifier;
  171. - (NSString *)sqlStringForKeyValueQualifier:(EOKeyValueQualifier *)qualifier;
  172. - (NSString *)sqlStringForKeyComparisonQualifier:(EOKeyComparisonQualifier *)qualifier;
  173.     // Methods to add SQL for each type of qualifier
  174.  
  175. - (void)addOrderByAttributeOrdering:(EOSortOrdering *)sortOrdering;
  176.     // Adds the appropriate information to the end of the orderBy string
  177.  
  178. - (void)setUseAliases:(BOOL)useAliases;
  179. - (BOOL)useAliases;
  180.     // By default the SQLExpression uses aliasing for select statements but not for
  181.     // insert, update, or delete. Subclassers can change this behavior by overriding the
  182.     // prepare methods and calling setUseAliasing before calling the super class's
  183.     // implementation.
  184.  
  185. - (NSString *)sqlStringForAttributeNamed:(NSString *)name;
  186.     // returns the aliased column name for this attribute
  187.  
  188. - (NSString *)sqlStringForSelector:(SEL)selector value:(id)value;
  189.     // returns a sqlString for one of the predefined selectors in EOQualifier
  190.  
  191. - (NSString *)sqlStringForValue:(id)value attributeNamed:(NSString *)string;
  192.  
  193. - (NSString *)sqlStringForAttribute:(EOAttribute *)anAttribute;
  194.     // Does the appropriate aliasing and name generation for an attribute in
  195.     // the context of this particular query.
  196.  
  197. - (NSString *)sqlStringForAttributePath:(NSArray *)path;
  198.     // Returns an attribute name complete with alias for an attribute path.
  199.     // An attribute path is an array that consists of any number of
  200.     // relationships followed by an attribute.
  201.  
  202. - (void)appendItem:(NSString *)itemString toListString:(NSMutableString *)listString;
  203.     // Appends item to mutable list string.  Default implementation will
  204.     // append the item directly if the list string is empty, and append ", "
  205.     // before the new item if not.
  206.  
  207. + (NSString *)sqlPatternFromShellPattern:(NSString *)pattern;
  208.     // Returns an equivalent sql pattern from the shell pattern
  209.  
  210. // These methods are useful for adaptor writers that want or need to use bind variables
  211. // with their client library. If there is no need for an adaptor to use bind variable
  212. // then no action need be taken on the part of the adaptor writer. If bind variables
  213. // are needed the following 3 methods must be implemented in the subclass.
  214.  
  215. - (NSMutableDictionary *)bindVariableDictionaryForAttribute:(EOAttribute *)attribute value:value;
  216.     // Returns a dictionary to be stored in the EOSQLExpression that contains
  217.     // whatever adaptor specific information is necessary to bind the values.
  218.     // This following keys must have values in the binding dictionary because their
  219.     // values are used by the superclasss: EOBindVariableNameKey, EOBindVariableValueKey,
  220.     // EOBindVariablePlaceHolderKey, and EOBindVariableAttributeKey.
  221.  
  222. - (BOOL)shouldUseBindVariableForAttribute:(EOAttribute *)att;
  223.     // Returns YES if the the adaptor provides bind variable capability for attributes
  224.     // of this type, no otherwise. Bind variables won't be used for values associated
  225.     // with this attribute when -useBindVariable returns NO. This method should return
  226.     // YES for any attribute that must use bind variables also.
  227.  
  228. - (BOOL)mustUseBindVariableForAttribute:(EOAttribute *)att;
  229.     // Returns YES if the the adaptor must use bind variable capability for attributes
  230.     // of this type, no otherwise.
  231.  
  232. // Keys for use in the bindVariableDictionary
  233. EOACCESS_EXTERN NSString *EOBindVariableNameKey;
  234. EOACCESS_EXTERN NSString *EOBindVariableAttributeKey;
  235. EOACCESS_EXTERN NSString *EOBindVariableValueKey;
  236. EOACCESS_EXTERN NSString *EOBindVariablePlaceHolderKey;
  237. EOACCESS_EXTERN NSString *EOBindVariableColumnKey;
  238.  
  239. + (BOOL)useBindVariables;
  240.     // Returns YES if the application is currently using bind variables, NO otherwise.
  241.     // This can be set to YES or NO with the user default named 'EOAdaptorUseBindVariables'
  242.     // in the NSGlobalDomain.
  243. + (void)setUseBindVariables:(BOOL)yn;
  244.     // Applications can override the user default by invoking this method.
  245.  
  246. - (NSArray *)bindVariableDictionaries;
  247.     // Returns the current array of binding variable dictionaries.
  248.  
  249. - (void)addBindVariableDictionary:(NSMutableDictionary *)binding;
  250.     // Add a new BindVariableDictionary to the list maintained by the SQL expression.
  251. @end
  252.  
  253. @interface NSString (EOSQLFormatting)
  254. - (NSString *)sqlString;
  255.     // Returns self    
  256. @end
  257.  
  258. @interface NSNumber (EOSQLFormatting)
  259. - (NSString *)sqlString;
  260.     // returns [sefl stringValue];    
  261. @end
  262.  
  263.