Inherits From:
NSObject
Inherits From:
com.apple.yellow.eoaccess
Class Description
EOSQLExpression is an abstract superclass that defines how to build SQL statements for adaptor channels. You don't typically use instances of EOSQLExpression; rather, you use EOSQLExpression subclasses written to work with a particular RDBMS and corresponding adaptor. A concrete subclass of EOSQLExpression overrides many of its methods in terms of the query language syntax for its specific RDBMS. EOSQLExpression objects are used internally by the Framework, and unless you're creating a concrete adaptor, you won't ordinarily need to interact with EOSQLExpression objects yourself. You most commonly create and use an EOSQLExpression object when you want to send an SQL statement directly to the server. In this case, you simply create an expression with the EOSQLExpression static method expressionForString
, and send the expression object to an adaptor channel using EOAdaptorChannel's evaluateExpression:
method.
For more information, see "More about EOSQLExpression".
EOSQLExpression
()
public EOSQLExpression
(EOEntity anEntity)
Creates a new EOSQLExpression. If anEntity is provided, the new EOSQLExpression is rooted to anEntity.
See also:
entity
appendExpression
public static void appendExpression
(EOSQLExpression anSQLExpression, java.lang.String script)
Append's anSQLExpression's statement
to script along with any necessary delimiter. EOSQLExpression's implementation append the SQL statement for anSQLExpression to script followed by a semicolon and a newline. A subclass of EOSQLExpression only needs to override this method if the delimiter for its database server is different. For example, the Oracle and Informix use the default implementation, whereas the Sybase adaptor appends the word "go" instead of a semicolon.
See also:
createTableStatementsForEntityGroups
createDatabaseStatementsForConnectionDictionary
public static NSArray createDatabaseStatementsForConnectionDictionary
(
NSDictionary connectionDictionary,
NSDictionary adminDictionary,)
Generates the SQL statements that will create a database (or user, for Oracle) that can be accessed by the provided connection dictionary and administrative connection dictionary.
See also:
dropDatabaseStatementsForConnectionDictionary
createTableStatementsForEntityGroup
public static NSArray createTableStatementsForEntityGroup
(NSArray entityGroup)
Returns an array of EOSQLExpression objects that define the SQL necessary to create a table for entityGroup, an array of Entity objects that have the same externalName
. Returns an empty array if entityGroup is null
or empty.
EOSQLExpression's implementation does the following:
entity
to the first entity in entityGroup.
statement
to CREATE TABLE TABLE_NAME (LIST_STRING), where TABLE_NAME is the externalName
of the Entity objects in entityGroup and LIST_STRING is the expression's listString
.
create table EMPLOYEE (
EMP_ID int not null ,
DEPT_ID int null ,
LAST_NAME varchar( 40 ) not null ,
PHONE char( 12 ) null ,
HIRE_DATE date null ,
SALARY number( 7 , 2 ) null
)
If a subclass's database server's table creation semantics are different, the subclass should override this method or one or more of the following methods as appropriate:
See also:
createTableStatementsForEntityGroups
, dropTableStatementsForEntityGroup
createTableStatementsForEntityGroups
public static NSArray createTableStatementsForEntityGroups
(NSArray entityGroups)
Returns an array of EOSQLExpression objects that define the SQL necessary to create the tables specified in entityGroups. An entity group is an array of Entity objects that have the same externalName
, and entityGroups is an array of entity groups. Returns an empty array if entityGroups is null
or empty. EOSQLExpression's implementation invokes createTableStatementsForEntityGroup
for each entity group in entityGroups and returns an array of all the resulting SQLExpressions.
See also:
schemaCreationStatementsForEntities
deleteStatementWithQualifier
public static EOSQLExpression deleteStatementWithQualifier
(com.apple.yellow.eocontrol.EOQualifier qualifier, java.lang.Object entity)
Creates and returns an SQL DELETE expression to delete the rows described by qualifier. Creates an instance of EOSQLExpression, initializes it with entity (an EOEntity object), and sends it a prepareDeleteExpressionForQualifier
message. Throws an exception if qualifier is null
.
The expression created with this method does not use table aliases because Enterprise Objects Framework assumes that all INSERT, UPDATE, and DELETE statements are single-table operations. As a result, all keys in qualifier should be simple key names; no key paths are allowed. To generate DELETE statements that do use table aliases, you must override prepareDeleteExpressionForQualifier:
to send a setUseAliases
(true
) message prior to invoking super
's version.
dropDatabaseStatementsForConnectionDictionary
public static NSArray dropDatabaseStatementsForConnectionDictionary
(
NSDictionary connectionDictionary,
NSDictionary adminDictionary,)
Generates the SQL statements to drop the database (or user, for Oracle).
See also:
createDatabaseStatementsForConnectionDictionary
dropPrimaryKeySupportStatementsForEntityGroup
public static NSArray dropPrimaryKeySupportStatementsForEntityGroup
(NSArray entityGroup)
Returns an array of EOSQLExpression objects that define the SQL necessary to drop the primary key generation support for entityGroup, an array of Entity objects that have the same externalName
. The drop statement generated by this method should be sufficient to remove the primary key support created by primaryKeySupportStatementsForEntityGroup
's statements.
EOSQLExpression's implementation creates a statement of the following form:
drop sequence SEQUENCE_NAME
Where SEQUENCE_NAME is the primaryKeyRootName
for the first entity in entityGroup concatenated with "_SEQ" (EMP_ID_SEQ, for example).
If a subclass uses a different primary key generation mechanism or if the subclass's database server's drop semantics are different, the subclass should override this method.
See also:
dropPrimaryKeySupportStatementsForEntityGroups
dropPrimaryKeySupportStatementsForEntityGroups
public static NSArray dropPrimaryKeySupportStatementsForEntityGroups
(
NSArray entityGroups)
Returns an array of EOSQLExpression objects that define the SQL necessary to drop the primary key generation support for the Entities specified in entityGroups. An entity group is an array of Entity objects that have the same externalName
, and entityGroups is an array of entity groups. EOSQLExpression's implementation invokes dropPrimaryKeySupportStatementsForEntityGroup
for each entity group in entityGroups and returns an array of all the resulting SQLExpressions.
See also:
schemaCreationStatementsForEntities
dropTableStatementsForEntityGroup
public static NSArray dropTableStatementsForEntityGroup
(NSArray entityGroup)
Returns an array of EOSQLExpression objects that define the SQL necessary to drop the table identified by entityGroup, an array of Entity objects that have the same externalName
. The drop statement generated by this method should be sufficient to remove the table created by createTableStatementsForEntityGroup
's statements.
EOSQLExpression's implementation creates a statement of the following form:
DROP TABLE TABLE_NAME
Where TABLE_NAME is the externalName
of the first entity in entityGroup.
If a subclass's database server's drop semantics are different, the subclass should override this method.
See also:
dropTableStatementsForEntityGroups
dropTableStatementsForEntityGroups
public static NSArray dropTableStatementsForEntityGroups
(NSArray entityGroups)
Returns an array of EOSQLExpression objects that define the SQL necessary to drop the tables for entityGroups. An entity group is an array of Entity objects that have the same externalName
, and entityGroups is an array of entity groups. EOSQLExpression's implementation invokes dropTableStatementsForEntityGroups
for each entity group in entityGroups and returns an array of all the resulting SQLExpressions.
See also:
schemaCreationStatementsForEntities
expressionForString
public static EOSQLExpression expressionForString
(java.lang.String string)
Creates and returns an SQL expression for string. string should be a valid expression in the target query language. This method does not perform substitutions or formatting of any kind.
See also:
setStatement
foreignKeyConstraintStatementsForRelationship
public static NSArray foreignKeyConstraintStatementsForRelationship
(EORelationship aRelationship)
Returns an array of EOSQLExpression objects that define the SQL necessary to create foreign key constraints for aRelationship. EOSQLExpression's implementation generates statements such as the following:
ALTER TABLE EMPLOYEE ADD CONSTRAINT TO_DEPARTMENT FOREIGN KEY (DEPT_ID)
REFERENCES DEPARTMENT(DEPT_ID)
It returns an empty array if either of the following are true:
destinationEntity
is in a different model than aRelationship's source entity
)
prepareConstraintStatementForRelationship
, and returns an array containing the expression.
If a subclass's database server's foreign key constraint semantics are different, the subclass should override this method or override the method prepareConstraintStatementForRelationship
.
See also:
schemaCreationStatementsForEntities
formatSQLString
public static java.lang.String formatSQLString
(java.lang.String sqlString, java.lang.String format)
Applies format (an EOAttribute object's "read" or "write" format) to sqlString (a value for the attribute). If format is null
, this method returns sqlString unchanged.
See also: -- readFormat (EOAttribute), - writeFormat (EOAttribute)
formatStringValue
public static java.lang.String formatStringValue
(java.lang.String string)
Formats string for use as a string constant in a SQL statement. EOSQLExpression's implementation encloses the string in single quotes, escaping any single quotes already present in string. Throws an exception if string is null
.
formatValue:forAttribute
public static java.lang.String formatValueForAttribute
(java.lang.Object value, EOAttribute attribute)
Overridden by subclasses to return a string representation of value suitable for use in an SQL statement. EOSQLExpression's implementation returns value unchanged. A subclass should override this method to format value depending on attribute's externalType
. For example, a subclass might format a date using a special database-specific syntax or standard form or truncate numbers to attribute's precision and scale.
insertStatementForRow
public static EOSQLExpression insertStatementForRow
(NSDictionary row, EOEntity entity)
Creates and returns an SQL INSERT expression to insert row. Creates an instance of EOSQLExpression, initializes it with entity, and sends it prepareInsertExpressionWithRow
. Throws an exception if entity is null
.
The expression created with this method does not use table aliases because Enterprise Objects Framework assumes that all INSERT, UPDATE, and DELETE statements are single-table operations. To generate INSERT statements that do use table aliases, you must override prepareInsertExpressionWithRow:
to send a setUseAliases
(true
) message prior to invoking super
's version.
primaryKeyConstraintStatementsForEntityGroup
public static NSArray primaryKeyConstraintStatementsForEntityGroup
(NSArray entityGroup)
Returns an array of EOSQLExpression objects that define the SQL necessary to create the primary key constraints for entityGroup, an array of Entity objects that have the same externalName
. Returns an empty array if any of the primary key attributes in entityGroup don't have a columnName
.
EOSQLExpression's implementation creates a statement of the following form:
ALTER TABLE TABLE_NAME ADD PRIMARY KEY (PRIMARY_KEY_COLUMN_NAMES)
Where TABLE_NAME is the externalName
for the first entity in entityGroup and PRIMARY_KEY_COLUMN_NAMES is a comma-separated list of the columnName
s of the first entity's primaryKeyAttributes
.
If the subclass's database server's primary key constraint semantics are different, the subclass should override this method.
See also:
primaryKeyConstraintStatementsForEntityGroups
primaryKeyConstraintStatementsForEntityGroups
public static NSArray primaryKeyConstraintStatementsForEntityGroups
(NSArray entityGroups)
Returns an array of EOSQLExpression objects that define the SQL necessary to create the primary key constraints for the Entities specified in entityGroups. An entity group is an array of Entity objects that have the same externalName
, and entityGroups is an array of entity groups. EOSQLExpression's implementation invokes primaryKeyConstraintStatementsForEntityGroup
for each entity group in entityGroups and returns an array of all the resulting SQLExpressions.
primaryKeySupportStatementsForEntityGroup
public static NSArray primaryKeySupportStatementsForEntityGroup
(NSArray entityGroup)
Returns an array of EOSQLExpression objects that define the SQL necessary to create the primary key generation support for entityGroup, an array of Entity objects that have the same externalName
. EOSQLExpression's implementation creates a statement of the following form:
create sequence SEQUENCE_NAME
Where SEQUENCE_NAME is the primaryKeyRootName
for the first entity in entityGroup concatenated with "_SEQ" (EMP_ID_SEQ, for example).
If a subclass uses a different primary key generation mechanism or if the subclass's database server's drop semantics are different, the subclass should override this method.
See also:
primaryKeySupportStatementsForEntityGroups
,
dropPrimaryKeySupportStatementsForEntityGroup
, primaryKeyForNewRowWithEntity
(EOAdaptorChannel)
primaryKeySupportStatementsForEntityGroups
public static NSArray primaryKeySupportStatementsForEntityGroups
(NSArray entityGroups)
Returns an array of EOSQLExpression objects that define the SQL necessary to create the primary key generation support for the Entities specified in entityGroups. An entity group is an array of Entity objects that have the same externalName
, and entityGroups is an array of entity groups. EOSQLExpression's implementation invokes primaryKeySupportStatementsForEntityGroup
for each entity group in entityGroups and returns an array of all the resulting SQLExpressions.
schemaCreationScriptForEntities
public static java.lang.String schemaCreationScriptForEntities
(NSArray entities, NSDictionary options)
Returns a script of SQL statements suitable to create the schema for the Entity objects in entities. The options dictionary specifies the aspects of the schema for which to create SQL statements as described in the method description for schemaCreationStatementsForEntities
. EOSQLExpression's implementation invokes schemaCreationStatementsForEntities:options:
with entities and options and then uses appendExpression
to generate the script from the SQLExpressions generated by schemaCreationStatementsForEntities:options:
.
schemaCreationStatementsForEntities
public static NSArray schemaCreationStatementsForEntities
(NSArray entities, NSDictionary options)
Returns an array of SQLExpressions suitable to create the schema for the Entity objects in entities. The options dictionary specifies the aspects of the schema for which to create SQLExpressions:
Dictionary Key | Acceptable Values (java.util.Strings) | Default |
---|---|---|
createTables | "YES" or "NO" | YES |
dropTables | "YES" or "NO" | YES |
createPrimaryKeySupport | "YES" or "NO" | YES |
dropPrimaryKeySupport | "YES" or "NO" | YES |
primaryKeyConstraints | "YES" or "NO" | YES |
foreignKeyConstraints | "YES" or "NO" | NO |
createDatabase | "YES" or "NO" | NO |
dropDatabase | "YES" or "NO" | NO |
If you specify "createDatabase" or "dropDatabase," the SQL for those statements must be executed by an administrative user.
EOSQLExpression's implementation uses the following methods:
See also:
schemaCreationScriptForEntities
selectStatementForAttributes
public static EOSQLExpression selectStatementForAttributes
(NSArray attributes,
boolean flag,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpecification,
EOEntity entity)
Creates and returns an SQL SELECT expression. Creates an instance of EOSQLExpression, initializes it with entity, and sends it prepareSelectExpressionWithAttributes
. The expression created with this method uses table aliases. Throws an exception if attributes is null
or empty, fetchSpecification is null
, or entity is null
.
The expression created with this method uses table aliases. To generate SELECT statements that don't use them, you must override prepareSelectExpressionWithAttributes:lock:fetchSpecification:
to send a setUseAliases
(false
) message prior to invoking super
's version.
setUseBindVariables
public static void setUseBindVariables
(boolean flag)
Sets according to flag whether all instances of EOSQLExpression subclasses use bind variables. By default, instances don't use bind variables; if the value for the global user default named EOAdaptorUseBindVariables is true
, though, instances do use them. For more information on bind variables, see the discussion in the class description.
See also:
useBindVariables
setUseQuotedExternalNames
public static void setUseQuotedExternalNames
(boolean flag)
Sets whether all instances of EOSQLExpression subclasses quote external names when they are referenced in SQL statements. By setting flag to true
, you can access database tables with names such as "%return", "1st year", and "TABLE" that you couldn't otherwise access. By default, instances don't quote external names; if the value for the global user default named EOAdaptorQuotesExternalNames is true
, though, instances do use quotes.
See also:
useQuotedExternalNames
, sqlStringForSchemaObjectName
,
externalNameQuoteCharacter
sqlPatternFromShellPattern
public static java.lang.String sqlPatternFromShellPattern
(java.lang.String pattern)
Translates a "like" qualifier to an SQL "like" expression. Invoked from sqlStringForKeyValueQualifier
when the qualifier argument is an EOKeyValueQualifier object whose selector is QualifierOperatorLike. EOSQLExpression's implementation performs the following substitutions
Character in pattern | Substitution string |
---|---|
* | % |
? | _ |
% | [%] (unless the percent character appears in square brackets) |
_ | [_] (unless the underscore character appears in square brackets) |
See also:
sqlPatternFromShellPattern:withEscapeCharacter
sqlPatternFromShellPattern:withEscapeCharacter
public static java.lang.String sqlPatternFromShellPatternWithEscapeCharacter
(java.lang.String pattern, char escapeCharacter)
Like sqlPatternFromShellPattern
except the argument escapeCharacter allows you to specify a character for escaping the wild card characters "%" and "_".
updateStatementForRow
public static EOSQLExpression updateStatementForRow
(NSDictionary row, com.apple.yellow.eocontrol.EOQualifier qualifier,
EOEntity entity)
Creates and returns an SQL UPDATE expression to update the row identified by qualifier with the values in row. row should only contain entries for values that have actually changed. Creates an instance of EOSQLExpression, initializes it with entity, and sends it prepareUpdateExpressionWithRow
. Throws an exception if row is null
or empty, qualifier is null
, or entity is null
.
The expression created with this method does not use table aliases because Enterprise Objects Framework assumes that all INSERT, UPDATE, and DELETE statements are single-table operations. As a result, all keys in qualifier should be simple key names; no key paths are allowed. To generate UPDATE statements that do use table aliases, you must override prepareUpdateExpressionWithRow:qualifier:
to send a setUseAliases
(true
) message prior to invoking super
's version.
See also:
setUseAliases
useBindVariables
public static boolean useBindVariables
()
Returns true
if instances use bind variables, false
otherwise. For more information on bind variables, see the discussion in the class description.
See also:
setUseBindVariables
useQuotedExternalNames
public static boolean useQuotedExternalNames
()
Returns true
if instances use quoted external names, false
otherwise.
See also:
setUseQuotedExternalNames
, sqlStringForSchemaObjectName
,
externalNameQuoteCharacter
Instance Methods
addBindVariableDictionary
public void addBindVariableDictionary
(NSMutableDictionary binding)
Adds binding to the receiver's array of bind variable dictionaries. binding is generally created using the method bindVariableDictionaryForAttribute
and is added to the receiver's bind variable dictionaries in sqlStringForValue
when the receiver uses a bind variable for the specified attribute. See the method description for bindVariableDictionaryForAttribute:value:
for a description of the contents of a bind variable dictionary, and for more information on bind variables, see the discussion in the class description.
See also:
bindVariableDictionaries
addCreateClauseForAttribute
public void addCreateClauseForAttribute
(EOAttribute attribute)
Adds the SQL string for creating attribute to a comma-separated list of attribute creation clauses. The list is constructed for use in a CREATE TABLE statement produced by createTableStatementsForEntityGroup
. Use the method listString
to access creation clauses.
EOSQLExpression's implementation creates clauses in the following form:
COLUMN_NAME COLUMN_TYPE ALLOWS_NULL_CLAUSE
Where
columnTypeStringForAttribute
for anAttribute.
allowsNullClauseForConstraint
with true
if anAttribute allowsNull
or with false
if anAttribute doesn't.
addInsertListAttribute
(EOAttribute attribute, java.lang.String value)
Adds the SQL string for attribute to a comma-separated list of attributes and value to a comma-separated list of values. Both lists are constructed for use in an INSERT statement. Use the methods listString
and valueList
to access the attributes and value lists.
Invokes appendItemToListString
to add an SQL string for attribute to the receiver's listString
, and again to add a formatted SQL string for value to the receiver's valueList
.
See also:
sqlStringForAttribute
, sqlStringForValue
, formatValue:forAttribute
addJoinClauseWithLeftName:rightName:joinSemantic:
public void addJoinClause
(java.lang.String leftName, java.lang.String rightName, int semantic)
Creates a new join clause by invoking assembleJoinClause
and adds it to the receiver's join clause string. Separates join conditions already in the join clause string with the word "and". Invoked from joinExpression
.
See also:
joinClauseString
addOrderByAttributeOrdering
public void addOrderByAttributeOrdering
(com.apple.yellow.eocontrol.EOSortOrdering sortOrdering)
Adds an attribute-direction pair ("LAST_NAME asc", for example) to the receiver's ORDER BY string. If sortOrdering's selector is CompareCaseInsensitiveAscending or CompareCaseInsensitiveDescending, the string generated has the format "upper(attribute) direction". Use the method orderByString
to access the ORDER BY string. addOrderByAttributeOrdering:
invokes appendItemToListString
to add the attribute-direction pair.
See also:
sqlStringForAttributeNamed
addSelectListAttribute
public void addSelectListAttribute
(EOAttribute attribute)
Adds an SQL string for attribute to a comma-separated list of attribute names for use in a SELECT statement. The SQL string for attribute is formatted with attribute's "read" format. Use listString
to access the list. addSelectListAttribute:
invokes appendItemToListString
to add the attribute name.
See also:
sqlStringForAttribute
, formatSQLString
, - readFormat (EOAttribute)
addUpdateListAttribute
public void addUpdateListAttribute
(EOAttribute attribute, java.lang.String value)
Adds a attribute-value assignment ("LAST_NAME = `Thomas'", for example) to a comma-separated list for use in an UPDATE statement. Formats value with attribute's "write" format. Use listString
to access the list. addUpdateListAttribute:value:
invokes appendItemToListString
to add the attribute-value assignment.
See also:
formatSQLString
aliasesByRelationshipPath
public NSMutableDictionary aliasesByRelationshipPath
()
Returns a dictionary of table aliases. The keys of the dictionary are relationship paths-"department" and "department.location", for example. The values are the table aliases for the corresponding table-"t1" and "t2", for example. The aliasesByRelationshipPath
dictionary always has at least one entry: an entry for the EOSQLExpression's entity. The key of this entry is the empty string ("") and the value is "t0". The dictionary returned from this method is built up over time with successive calls to sqlStringForAttributePath
.
See also:
tableListWithRootEntity
allowsNullClauseForConstraint
public java.lang.String allowsNullClauseForConstraint
(boolean flag)
Returns according to flag an adaptor specific string for use in a CREATE TABLE statement. The returned string indicates whether a column allows null values. EOSQLExpression's implementation returns the empty string if flag is true
, "NOT NULL" otherwise. A subclass should override this if its database server's semantics are different. For example, the SybaseSLQExpression returns "null" if flag is true
, the empty string otherwise.
See also:
addCreateClauseForAttribute
appendItemToListString
public void appendItemToListString
(java.lang.String itemString, java.lang.String listString)
Adds itemString to a comma-separated list. If listString already has entries, this method appends a comma followed by itemString. Invoked from addSelectListAttribute
, addInsertListAttribute
, addUpdateListAttribute
, and addOrderByAttributeOrdering
assembleDeleteStatementWithQualifier
public java.lang.String assembleDeleteStatementWithQualifier
(com.apple.yellow.eocontrol.EOQualifier qualifier, java.lang.String tableList, java.lang.String whereClause)
Invoked from prepareDeleteExpressionForQualifier
to return an SQL DELETE statement of the form:
DELETE FROM tableList
SQL_WHERE whereClause
qualifier is the argument to prepareDeleteExpressionForQualifier:
from which whereClause was derived. It is provided for subclasses that need to generate the WHERE clause in a particular way.
assembleInsertStatementWithRow
public java.lang.String assembleInsertStatementWithRow
(NSDictionary row, java.lang.String tableList, java.lang.String columnList, java.lang.String valueList)
Invoked from prepareInsertExpressionWithRow
to return an SQL INSERT statement of the form:
INSERT INTO tableList (columnList)
VALUES valueList
or, if columnList is null
:
INSERT INTO tableList
VALUES valueList
row is the argument to prepareInsertExpressionWithRow:
from which columnList and valueList were derived. It is provided for subclasses that need to generate the list of columns and values in a particular way.
assembleJoinClause
public java.lang.String assembleJoinClause
(java.lang.String leftName,
java.lang.String rightName,
int semantic)
Returns a join clause of the form:
leftName operator rightName
Where operator is "=" for an inner join, "*=" for a left-outer join, and "=*" for a right-outer join. Invoked from addJoinClauseWithLeftName:rightName:joinSemantic:
.
assembleSelectStatementWithAttributes
public java.lang.String assembleSelectStatementWithAttributes
(NSArray attributes,
boolean lock,
com.apple.yellow.eocontrol.EOQualifier qualifier,
NSArray fetchOrder,
java.lang.String selectString,
java.lang.String columnList,
java.lang.String tableList,
java.lang.String whereClause,
java.lang.String joinClause,
java.lang.String orderByClause,
java.lang.String lockClause)
Invoked from prepareSelectExpressionWithAttributes
to return an SQL SELECT statement of the form:
SELECT columnList
FROM tableList lockClause
WHERE whereClause AND joinClause
ORDER BY orderByClause
If lockClause is null
, it is omitted from the statement. Similarly, if orderByClause is null
, the "ORDER BY orderByClause" is omitted. If either whereClause or joinClause is null
, the "AND" and null
-valued argument are omitted. If both are null
, the entire WHERE clause is omitted.
attributes, lock, qualifier, and fetchOrder are the arguments to prepareSelectExpressionWithAttributes:lock:fetchSpecification:
from which the other assembleSelect...
arguments were derived. They are provided for subclasses that need to generate the clauses of the SELECT statement in a particular way.
assembleUpdateStatementWithRow
public java.lang.String assembleUpdateStatementWithRow
(NSDictionary row, com.apple.yellow.eocontrol.EOQualifier qualifier, java.lang.String tableList, java.lang.String updateList, java.lang.String whereClause)
Invoked from prepareUpdateExpressionWithRow
to return an SQL UPDATE statement of the form:
UPDATE tableList
SET updateList
WHERE whereClause
row and qualifier are the arguments to prepareUpdateExpressionWithRow:qualifier:
from which updateList and whereClause were derived. They are provided for subclasses that need to generate the clauses of the UPDATE statement in a particular way.
bindVariableDictionaries
public NSArray bindVariableDictionaries
()
Returns the receiver's bind variable dictionaries. For more information on bind variables, see the discussion in the class description.
See also:
addBindVariableDictionary
bindVariableDictionaryForAttribute
public abstract NSMutableDictionary bindVariableDictionaryForAttribute
(EOAttribute attribute, java.lang.Object value)
Implemented by subclasses to create and return the bind variable dictionary for attribute and value. The dictionary returned from this method must contain at least the following key-value pairs:
Key | Value |
---|---|
BindVariableNameKey | the name of the bind variable for attribute |
BindVariablePlaceHolderKey | the placeholder string used in the SQL statement |
BindVariableAttributeKey | attribute |
BindVariableValueKey | value |
An adaptor subclass may define additional entries as required by its RDBMS.
Invoked from sqlStringForValue
when the message mustUseBindVariableForAttribute
(attribute) returns true
or when the receiver's class uses bind variables and the message shouldUseBindVariableForAttribute
(attribute) returns true
. For more information on bind variables, see the discussion in the class description.
A subclass that uses bind variables should implement this method without invoking EOSQLExpression's implementation. The subclass implementation must return a dictionary with entries for the keys listed above and may add additional keys.
See also:
bindVariableDictionaryForAttribute
, useBindVariables
columnTypeStringForAttribute
public java.lang.String columnTypeStringForAttribute
(EOAttribute anAttribute)
Returns an adaptor specific type string for anAttribute that's suitable for use in a CREATE TABLE statement. EOSQLExpression's implementation creates a string based on anAttribute's externalType
, precision
, and width
as follows:
If Condition | Generated Type String |
---|---|
precision is non-zero | externalType(precision, scale) |
precision is zero and width is non-zero | externalType(scale) |
precision and width are zero | externalType |
A subclass should override the default implementation if its database server requires column types in a different format.
See also:
addCreateClauseForAttribute
entity
public EOEntity entity
()
Returns the receiver's entity.
See also: "Constructors"
externalNameQuoteCharacter
public java.lang.String externalNameQuoteCharacter
()
Returns the string `\"' (an escaped quote character) if the receiver uses quoted external names, or the empty string ("") otherwise.
See also:
useQuotedExternalNames
, sqlStringForSchemaObjectName
joinClauseString
public java.lang.String joinClauseString
()
Returns the part of the receiver's WHERE clause that specifies join conditions. Together, the joinClauseString
and the whereClauseString
make up a statement's WHERE clause. If the receiver's statement doesn't contain join conditions, this method returns an empty string.
An EOSQLExpression's joinClauseString
is generally set by invoking joinExpression
.
See also:
addJoinClauseWithLeftName:rightName:joinSemantic:
joinExpression
public void joinExpression()
Builds up the joinClauseString
for use in a SELECT statement. For each relationship path in the aliasesByRelationshipPath
dictionary, this method invokes addJoinClauseWithLeftName:rightName:joinSemantic:
for each of the relationship's EOJoin objects.
If the aliasesByRelationshipPath
dictionary only has one entry (the entry for the EOSQLExpression's entity), the joinClauseString
is empty.
You must invoke this method after invoking addSelectListAttribute
for each attribute to be selected and after sending sqlStringForSQLExpression
(this
)to the qualifier for the SELECT statement. (These methods build up the aliasesByRelationshipPath
dictionary by invoking sqlStringForAttributePath
.)
See also:
whereClauseString
listString
public java.lang.String listString
()
Returns a comma-separated list of attributes or "attribute = value" assignments. listString
is built up with successive invocations of addInsertListAttribute
, addSelectListAttribute
, or addUpdateListAttribute
for INSERT statements, SELECT statements, and UPDATE statements, respectively. The contents of listString
vary according to the type of statement the receiver is building:
Type of Statement | Sample listString Contents |
---|---|
INSERT | FIRST_NAME, LAST_NAME, EMPLOYEE_ID |
UPDATE | FIRST_NAME = "Timothy", LAST_NAME = "Richardson" |
SELECT | t0.FIRST_NAME, t0.LAST_NAME, t1.DEPARTMENT_NAME |
lockClause
public java.lang.String lockClause
()
Overridden by subclasses to return the SQL string used in a SELECT statement to lock selected rows. A concrete subclass of EOSQLExpression must override this method to return the string used by its adaptor's RDBMS.
mustUseBindVariableForAttribute
public boolean mustUseBindVariableForAttribute
(EOAttribute attribute)
Returns true
if the receiver must use bind variables for attribute, false
otherwise. EOSQLExpression's implementation returns false
. An SQL expression subclass that uses bind variables should override this method to return true
if the underlying RDBMS requires that bind variables be used for attributes with attribute's external type.
See also:
shouldUseBindVariableForAttribute
, bindVariableDictionaryForAttribute
orderByString
public java.lang.String orderByString
()
Returns the comma-separated list of "attribute direction" pairs ("LAST_NAME asc, FIRST_NAME asc", for example) for use in a SELECT statement.
See also:
addOrderByAttributeOrdering
prepareConstraintStatementForRelationship
public void prepareConstraintStatementForRelationship
(EORelationship relationship, NSArray sourceColumns, NSArray destinationColumns)
Sets the receiver's statement
to an adaptor specific constraint for relationship. EOSQLExpression's implementation generates statements of the form:
ALTER TABLE TABLE_NAME ADD CONSTRAINT CONSTRAINT_NAME
FOREIGN KEY (SOURCE_KEY_LIST)
REFERENCES DESTINATION_TABLE_NAME (DESTINATION_KEY_LIST)
Where
foreignKeyConstraintStatementsForRelationship
prepareDeleteExpressionForQualifier
public void prepareDeleteExpressionForQualifier
(com.apple.yellow.eocontrol.EOQualifier qualifier)
Generates a DELETE statement by performing the following steps:
sqlStringForSQLExpression
(this
)message to qualifier to generate the receiver's whereClauseString
.
tableListWithRootEntity
to get the table name for the FROM clause.
assembleDeleteStatementWithQualifier
.
deleteStatementWithQualifier
prepareInsertExpressionWithRow
public void prepareInsertExpressionWithRow
(NSDictionary row)
Generates an INSERT statement by performing the following steps:
addInsertListAttribute
for each entry in row to prepare the comma-separated list of attributes and the corresponding list of values.
tableListWithRootEntity
to get the table name.
assembleInsertStatementWithRow
.
insertStatementForRow
prepareSelectExpressionWithAttributes
public void prepareSelectExpressionWithAttributes
(NSArray attributes, boolean flag,
com.apple.yellow.eocontrol.EOFetchSpecification fetchSpecification)
Generates a SELECT statement by performing the following steps:
addSelectListAttribute
for each entry in attributes to prepare the comma-separated list of attributes.
sqlStringForSQLExpression
(this
)message to fetchSpecification's qualifier to generate the receiver's whereClauseString
.
addOrderByAttributeOrdering
for each EOAttributeOrdering object in fetchSpecification. First conjoins the qualifier in fetchSpecification with the restricting qualifier, if any, of the receiver's entity.
joinExpression
to generate the receiver's joinClauseString
.
tableListWithRootEntity
to get the comma-separated list of tables for the FROM clause.
true
, invokes lockClause
to get the SQL string to lock selected rows.
assembleSelectStatementWithAttributes
.
selectStatementForAttributes
prepareUpdateExpressionWithRow
public void prepareUpdateExpressionWithRow
(NSDictionary row, com.apple.yellow.eocontrol.EOQualifier qualifier)
Generates an UPDATE statement by performing the following steps:
addUpdateListAttribute
for each entry in row to prepare the comma-separated list of "attribute = value" assignments.
sqlStringForSQLExpression
(this
)message to qualifier to generate the receiver's whereClauseString
.
tableListWithRootEntity
to get the table name for the FROM clause.
assembleUpdateStatementWithRow
.
updateStatementForRow
setStatement
public void setStatement
(java.lang.String string)
Sets the receiver's SQL statement to string, which should be a valid expression in the target query language. Use this method-instead of a prepare...
method-to directly assign an SQL string to an EOSQLExpression object. This method does not perform substitutions or formatting of any kind.
See also:
expressionForString
, statement
setUseAliases
public void setUseAliases
(boolean flag)
Tells the receiver whether or not to use table aliases.
See also:
useAliases
shouldUseBindVariableForAttribute
public boolean shouldUseBindVariableForAttribute
(EOAttribute attribute)
Returns true
if the receiver can provide a bind variable dictionary for attribute, false
otherwise. Bind variables aren't used for values associated with this attribute when the static method useBindVariables
returns false
. EOSQLExpression's implementation returns false
. An SQL expression subclass should override this method to return true
if the receiver should use bind variables for attributes with attribute's external type. It should also return true
for any attribute for which the receiver must use bind variables.
See also:
mustUseBindVariableForAttribute
sqlStringForAttribute
public java.lang.String sqlStringForAttribute
(EOAttribute attribute)
Returns the SQL string for attribute, complete with a table alias if the receiver uses table aliases. Invoked from sqlStringForAttributeNamed
when the attribute name is not a path.
See also:
sqlStringForAttributePath
sqlStringForAttributeNamed
public java.lang.String sqlStringForAttributeNamed
(java.lang.String name)
Returns the SQL string for the attribute named name, complete with a table alias if the receiver uses table aliases. Generates the return value using sqlStringForAttributePath
if name is an attribute path ("department.name", for example); otherwise, uses sqlStringForAttribute
.
sqlStringForAttributePath
public java.lang.String sqlStringForAttributePath
(NSArray path)
Returns the SQL string for path, complete with a table alias if the receiver uses table aliases. Invoked from sqlStringForAttributeNamed
when the specified attribute name is a path ("department.location.officeNumber", for example). path is an array of any number of EORelationship objects followed by an EOAttribute object. The EORelationship and EOAttribute objects each correspond to a component in path. For example, if the attribute name argument to sqlStringForAttributeNamed:
is "department.location.officeNumber", path is an array containing the following objects in the order listed:
If the receiver uses table aliases, this method has the side effect of adding a "relationship path"-"alias name" entry to the aliasesByRelationship
dictionary.
See also:
sqlStringForAttribute
sqlStringForConjoinedQualifiers
public java.lang.String sqlStringForConjoinedQualifiers
(NSArray qualifiers)
Creates and returns an SQL string that is the result of interposing the word "AND" between the SQL strings for the qualifiers in qualifiers. Generates an SQL string for each qualifier by sending sqlStringForSQLExpression:
messages to the qualifiers with this
as the argument. If the SQL string for a qualifier contains only white space, it isn't included in the return value. The return value is enclosed in parentheses if the SQL strings for two or more qualifiers were ANDed together.
sqlStringForDisjoinedQualifiers
public java.lang.String sqlStringForDisjoinedQualifiers
(NSArray qualifiers)
Creates and returns an SQL string that is the result of interposing the word "OR" between the SQL strings for the qualifiers in qualifiers. Generates an SQL string for each qualifier by sending sqlStringForSQLExpression:
messages to the qualifiers with this
as the argument. If the SQL string for a qualifier contains only white space, it isn't included in the return value. The return value is enclosed in parentheses if the SQL strings for two or more qualifiers were ORed together.
sqlStringForKeyComparisonQualifier
public java.lang.String sqlStringForKeyComparisonQualifier
(
com.apple.yellow.eocontrol.EOKeyComparisonQualifier qualifier)
Creates and returns an SQL string that is the result of interposing an operator between the SQL strings for the right and left keys in qualifier. Determines the SQL operator by invoking sqlStringForSelector
with qualifier's selector and null
for the value. Generates SQL strings for qualifier's keys by invoking sqlStringForAttributeNamed
to get SQL strings. This method also formats the strings for the right and left keys using formatSQLString
with the corresponding attributes' "read" formats.
sqlStringForKeyValueQualifier
public java.lang.String sqlStringForKeyValueQualifier
(
com.apple.yellow.eocontrol.EOKeyValueQualifier qualifier)
Creates and returns an SQL string that is the result of interposing an operator between the SQL strings for qualifier's key and value. Determines the SQL operator by invoking sqlStringForSelector
with qualifier's selector and value. Generates an SQL string for qualifier's key by invoking sqlStringForAttributeNamed
to get an SQL string and formatSQLString
with the corresponding attribute's "read" format. Similarly, generates an SQL string for qualifier's value by invoking sqlStringForValue
to get an SQL string and formatValue:forAttribute
to format it. (First invokes sqlPatternFromShellPattern
for the value if qualifier's selector is QualifierOperatorLike.)
sqlStringForNegatedQualifier
public java.lang.String sqlStringForNegatedQualifier
(com.apple.yellow.eocontrol.EOQualifier qualifier)
Creates and returns an SQL string that is the result of surrounding the SQL string for qualifier in parentheses and appending it to the word "not". For example, if the string for qualifier is "FIRST_NAME = `John'", sqlStringForNegatedQualifier:
returns the string "not (FIRST_NAME = `John')".
Generates an SQL string for qualifier by sending an sqlStringForSQLExpression:
:
message to qualifier with this
as the argument. If the SQL string for qualifier contains only white space, this method returns null
.
sqlStringForNumber
public java.lang.String sqlStringForNumber
(java.lang.Number aNumber)
Returns the SQL string for aNumber.
sqlStringForQualifier
public java.lang.String sqlStringForQualifier
(com.apple.yellow.eocontrol.EOQualifier aQualifier)
Returns a SQL statement for aQualifier suitable for inclusion in a WHERE clause. Invoked from an EOSQLExpression while it's preparing a SELECT, UPDATE, or DELETE statement.
See also:
whereClauseString
sqlStringForSchemaObjectName
public java.lang.String sqlStringForSchemaObjectName
(java.lang.String name)
Returns name enclosed in the external name quote character if the receiver uses quoted external names, otherwise simply returns name unaltered.
See also:
useQuotedExternalNames
, externalNameQuoteCharacter
sqlStringForSelector
public java.lang.String sqlStringForSelector
(NSSelector selector, java.lang.Object value)
Returns an SQL operator for selector and value. The following table summarizes EOSQLExpression's default mapping:
Selector | SQL Operator |
---|---|
QualifierOperatorIsEqual | "is" if value is an EONull, "=" otherwise |
QualifierOperatorNotEqual | "is not" if value is an EONull, "<> otherwise |
QualifierOperatorLessThan | "<" |
QualifierOperatorGreaterThan | ">" |
QualifierOperatorLessThanOrEqualTo | "<=" |
QualifierOperatorGreaterThanOrEqualTo | ">=" |
QualifierOperatorLike | "like" |
Throws an exception if selector is an unknown operator.
See also:
sqlStringForKeyComparisonQualifier
, sqlStringForKeyValueQualifier
sqlStringForString
public java.lang.String sqlStringForString
(java.lang.String aString)
Returns the SQL string for aString.
sqlStringForValue
public java.lang.String sqlStringForValue
(java.lang.Object value, java.lang.String name)
Returns a string for value appropriate for use in an SQL statement. If the receiver uses a bind variable for the attribute named name, then sqlStringForValue:attributeNamed:
gets the bind variable dictionary for the attribute, adds it to the receiver's array of bind variables dictionaries, and returns the value for the binding's EOBindVariablePlaceHolderKey. Otherwise, this method invokes formatValue:forAttribute
and returns the formatted string for value.
See also:
mustUseBindVariableForAttribute
, shouldUseBindVariableForAttribute
, useBindVariables
,
bindVariableDictionaries
, addBindVariableDictionary
statement
public java.lang.String statement
()
Returns the complete SQL statement for the receiver. An SQL statement can be assigned to an EOSQLExpression object directly using the static method expressionForString
or using the instance method setStatement
. Generally, however, an EOSQLExpression's statement is built up using one of the following methods:
tableListWithRootEntity
(EOEntity entity)Returns the comma-separated list of tables for use in a SELECT, UPDATE, or DELETE statement's FROM clause. If the receiver doesn't use table aliases, the table list consists only of the table name for entity-"EMPLOYEE", for example. If the receiver does use table aliases (only in SELECT statements by default), the table list is a comma separated list of table names and their aliases, for example:
EMPLOYEE t0, DEPARTMENT t1
tableListWithRootEntity:
creates a string containing the table name for entity and a corresponding table alias ("EMPLOYEE t0", for example). For each entry in aliasesByRelationshipPath
, this method appends a new table name and table alias.
See also:
useAliases
useAliases
public boolean useAliases()
Returns true
if the receiver generates statements with table aliases, false
otherwise. For example, the following SELECT statement uses table aliases:
SELECT t0.FIRST_NAME, t0.LAST_NAME, t1.NAME
FROM EMPLOYEE t0, DEPARTMENT t1
WHERE t0.DEPARTMENT_ID = t1.DEPARTMENT_ID
The EMPLOYEE table has the alias t0, and the DEPARTMENT table has the alias t1.
By default, EOSQLExpression uses table aliases only in SELECT statements. Enterprise Objects Framework assumes that INSERT, UPDATE, and DELETE statements are single-table operations. For more information, see the discussion in the class description.
See also:
setUseAliases
, aliasesByRelationshipPath
valueList
public java.lang.String valueList
()
Returns the comma-separated list of values used in an INSERT statement. For example, the value list for the following INSERT statement:
INSERT EMPLOYEE (FIRST_NAME, LAST_NAME, EMPLOYEE_ID, DEPARTMENT_ID, SALARY)
VALUES ('Shaun', 'Hayes', 1319, 23, 4600)
is "`Shaun', `Hayes', 1319, 23, 4600". An EOSQLExpression's valueList
is generated a value at a time with addInsertListAttribute
messages.
whereClauseString
public java.lang.String whereClauseString
()
Returns the part of the receiver's WHERE clause that qualifies rows. The whereClauseString does not specify join conditions; the joinClauseString
does that. Together, the whereClauseString
and the joinClauseString
make up a statement's where clause. For example, a qualifier for an Employee entity specifies that a statement only affects employees who belong to the Finance department and whose monthly salary is greater than $4500. Assume the corresponding where clause looks like this:
WHERE EMPLOYEE.SALARY > 4500 AND DEPARTMENT.NAME = `Finance'
AND EMPLOYEE.DEPARTMENT_ID = DEPARTMENT.DEPARTMENT_ID
EOSQLExpression generates both a whereClauseString
and a joinClauseString
for this qualifier. The whereClauseString
qualifies the rows and looks like this:
EMPLOYEE.SALARY > 4500 AND DEPARTMENT.NAME = `Finance'
The joinClauseString
specifies the join conditions between the EMPLOYEE table and the DEPARTMENT table and looks like this:
EMPLOYEE.DEPARTMENT_ID = DEPARTMENT.DEPARTMENT_ID
An EOSQLExpression's whereClauseString
is generally set by sending a sqlStringForSQLExpression:
message to an EOQualifier object.