PATH
Documentation > WebObjects 4.5 >
EOAccess Reference
Inherits
from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: EOAccess/EOAttribute.h
Class Description
An EOAttribute represents a column, field or property in a
database, and associates an internal name with an external name
or expression by which the property is known to the database. The
property an EOAttribute represents may be a meaningful value, such
as a salary or a name, or it may be an arbitrary value used for
identification but with no real-world applicability (ID numbers
and foreign keys for relationships fall into this category). An
EOAttribute also maintains type information for binding values to
the instance variables of objects.
EOAttributes are also used to represent arguments for EOStoredProcedures.
You usually define attributes in your EOModel with the EOModeler
application, which is documented in Enterprise Objects
Framework Tools and Techniques. Your code probably won't
need to programmatically interact with EOAttribute unless you're
working at the adaptor level. See "Creating Attributes" for information
on creating your own attribute objects.
Fore detailed discussion of using attribute objects to map
database data types to Objective-C objects, see "Mapping from Database to Objects" and "Working with Custom Data Types" .
EOAttributes can also alter the way values are selected, inserted,
and updated in the database by defining special format strings;
see "SQL Statement Formats" for
more information.
Constants
In EOAttribute.h, EOAccess defines the
enumeration type EOAdaptorValueType.
It is returned from the EOAttribute method adaptorValueType to
indicate the data type that will be fetched from the database for
the receiving attribute.
EOAttribute.h defines another enumeration
type, EOFactoryMethodArgumentType,
to be used by factoryMethodArgumentType and setFactoryMethodArgumentType: to
specify the type of argument that should be passed to the attribute's
"factory method". For more information, see "Working with Custom Data Types" .
EOAttribute.h also defines the enumeration
type EOParameterDirection to
represent parameter direction for EOAttributes that represent arguments
to a stored procedure. For more information, see the parameterDirection method
description.
Adopted Protocols
EOPropertyListEncoding
- awakeWithPropertyList
- encodeIntoPropertyList:
- initWithPropertyList:owner:
Method Types
- Accessing the entity
- - entity
- - parent
- Accessing the name
- - setName:
- - name
- - validateName:
- - beautifyName
- Accessing date information
- - serverTimeZone
- - setServerTimeZone:
- Accessing external definitions
- - setColumnName:
- - columnName
- - setDefinition:
- - definition
- - setExternalType:
- - externalType
- Accessing value type
information
- - setValueClassName:
- - valueClassName
- - setValueType:
- - valueType
- - setAllowsNull:
- - allowsNull
- - setPrecision:
- - precision
- - setScale:
- - scale
- - setWidth:
- - width
- - validateValue:
- Converting to adaptor
value types
- - adaptorValueByConvertingAttributeValue:
- - adaptorValueType
- Working with custom value
types
- - setValueFactoryMethodName:
- - valueFactoryMethod
- - valueFactoryMethodName
- - setFactoryMethodArgumentType:
- - factoryMethodArgumentType
- - setAdaptorValueConversionMethodName:
- - adaptorValueConversionMethod
- - adaptorValueConversionMethodName
- Accessing attribute characteristics
- - setReadOnly:
- - isReadOnly
- - isDerived
- - isFlattened
- Accessing SQL statement
formats
- - setReadFormat:
- - readFormat
- - setWriteFormat:
- - writeFormat
- Accessing the user dictionary
- - setUserInfo:
- - userInfo
- Methods used by the adaptor
- - newDateForYear:month:day:hour:minute:second:millisecond:timezone:zone:
- - newValueForBytes:length:
- - newValueForBytes:length:encoding:
- Working with stored procedures
- - setParameterDirection:
- - parameterDirection
- - storedProcedure
- Working with prototypes
- - overridesPrototypeDefinitionForKey:
- - prototype
- - prototypeName
- - setPrototype:
Instance Methods
- (id)adaptorValueByConvertingAttributeValue:(id)value
Ensures that value is
either an NSString, NSNumber, NSData, or NSDate, converting it if
necessary. If value needs to be converted, adaptorValueByConvertingAttributeValue: uses
the adaptor conversion method to convert value to
one of these four primitive types. If the attribute hasn't a specific
adaptor conversion method, and the type to be fetched from the database
is EOAdaptorBytesType, "archiveData" will
be invoked to convert the attribute value.See
Also: - adaptorValueConversionMethod, - adaptorValueType
- (SEL)adaptorValueConversionMethod
Returns the method used to convert a custom
class into one of the primitive types that the adaptor knows how
to manipulate: NSString, NSNumber, NSData, or NSDate. The return
value of this method is derived from the attribute's adaptor value
conversion method name. If that name doesn't map to a valid selector
in the Objective-C run-time, nil is returned.See
Also: - adaptorValueByConvertingAttributeValue:, - adaptorValueConversionMethodName
- (NSString *)adaptorValueConversionMethodName
Returns the name of the method used to convert
a custom class into one of the primitive types that the adaptor
knows how to manipulate: NSString, NSNumber, NSData, or NSDate.See
Also: - adaptorValueByConvertingAttributeValue:
- (EOAdaptorValueType)adaptorValueType
Returns an EOAdaptorValueType that indicates
the data type that will be fetched from the database. Currently,
this method returns one of the following values:
| Constant |
Description |
EOAdaptorNumberType |
A number value |
EOAdaptorCharactersType |
A string of characters |
EOAdaptorBytesType |
Raw bytes |
EOAdaptorDateType |
A date |
See Also: - factoryMethodArgumentType
- (BOOL)allowsNull
ReturnsYES to indicate that the attribute can
have anil value,NO otherwise. If the attribute maps directly to
a column in the database, it also is used to determine whether the
database column can have a NULL value.See
Also: - setAllowsNull:
- (void)beautifyName
Makes the attribute name conform to a standard
convention. Names that conform to this style are all lower-case
except for the initial letter of each embedded word other than the
first, which is upper case. Thus, "NAME" becomes "name",
and "FIRST_NAME" becomes "firstName". This method is used
in reverse-engineering an EOModel.See Also: - validateName:, - beautifyNames (EOModel)
- (NSString *)columnName
Returns the name of the column in the database
that corresponds to this attribute, or nil if the attribute isn't
simple (that is, if it's derived or flattened). An adaptor uses
this name to identify the column corresponding to the attribute.
Your application should never need to use this name. Note that columnName and definition are mutually
exclusive; if one returns a value, the other returns nil.See
Also: , - externalType
- (NSString *)definition
Returns a derived or flattened attribute's
definition, or nil if the attribute is simple. An attribute's definition
is either a value expression defining a derived attribute, such
as "salary * 12", or a data path for a flattened attribute,
such as "toAuthor.name". Note that columnName and definition are
mutually exclusive; if one returns a value, the other returns nil.See
Also: - externalType, - setDefinition:
- (EOEntity *)entity
Returns the entity that owns the attribute,
or nil if this attribute is acting as an argument for a stored procedure.See
Also: - storedProcedure
- (NSString *)externalType
Returns the attribute's type as understood
by the database; for example, a Sybase "varchar" or an Oracle
"NUMBER".See Also: - columnName, - setExternalType:
- (EOFactoryMethodArgumentType)factoryMethodArgumentType
Returns the type of argument that should be
passed to the "factory method"-which is invoked by the attribute
to create an attribute value for a custom class. This method returns
one of the following values:
| Constant |
Argument Type |
EOFactoryMethodArgumentIsNSData |
NSData |
EOFactoryMethodArgumentIsNSString |
NSString |
EOFactoryMethodArgumentIsBytes |
raw bytes |
See Also: - valueFactoryMethod, - setFactoryMethodArgumentType:
- (BOOL)isDerived
Returns NO if the attribute corresponds exactly
to one column in the table associated with its entity, and YES if
it doesn't. For example, an attribute with a definition of "otherAttributeName
+ 1" is derived.Note that flattened attributes are also
considered as derived attributes.
See
Also: - isFlattened, - definition
- (BOOL)isFlattened
Returns YES if the attribute is flattened, NO otherwise.
A flattened attribute is one that's accessed through an entity's
relationships but belongs to another entity.Note that flattened
attributes are also considered to be derived attributes.
See
Also: - isDerived, - definition
- (BOOL)isReadOnly
Returns YES if the value of the attribute can't
be modified, NO if it can.See Also: - setReadOnly:
- (NSString *)name
Returns the attribute's name.See
Also: - columnName, - definition, - setName:
- (NSCalendarDate *)newDateForYear:(int)year
month:(unsigned)month
day:(unsigned)day
hour:(unsigned)hour
minute:(unsigned)minute
second:(unsigned)second
millisecond:(unsigned)millisecond
timezone:(NSTimeZone *)timezone
zone:(NSZone *)zone
Returns an NSCalendarDate given discrete values
for year, month, day, and so on. This method is used by EOAdaptorChannel
subclasses to create a calendar date object to return in an adaptor
row. For efficiency reasons, the caller is responsible for releasing
the return value.
- (id)newValueForBytes:(const
void *)bytes
length:(int)length
Generates an NSString or custom class value
object from a supplied set of bytes. This method is called by the
adaptor during value creation while fetching from the database.
For efficiency reasons, the caller is responsible for releasing
the return value.
- (id)newValueForBytes:(const
void *)bytes
length:(int)length
encoding:(NSStringEncoding)encoding
Generates an NSData or custom class value object
from a supplied set of bytes with a given NSStringEncoding. This
method is called by the adaptor during value creation while fetching
from the database. For efficiency reasons, the caller is responsible
for releasing the return value.
- (BOOL)overridesPrototypeDefinitionForKey:(NSString
*)key
Returns NO if the requested key gets its value
from the prototype attribute. If the attribute has an override,
then this method returns YES. Valid values for key include @"columnName," @"valueClass," and
so on.See Also: - prototype
- (EOParameterDirection)parameterDirection
Returns the parameter direction for attributes
that are arguments to a stored procedure. This method returns one
of the following values:
| Constant |
Description |
EOVoid |
No parameters |
EOInParameter |
Input only parameters |
EOOutParameter |
Output only parameters |
EOInOutParameter |
Bidirectional parameters (input and output) |
See Also: - storedProcedure, - storedProcedureForOperation: (EOEntity), - setParameterDirection:
- (id)parent
Returns the attribute's parent, which is either
an EOEntity or an EOStoredProcedure. Use this method when you need
to find the model for an attribute:EOModel *myModel = [[anAttribute parent] model];
- (unsigned)precision
Returns the precision of the database representation
for attributes with a value class of NSNumber or NSDecimalNumber.See
Also: - scale
- (EOAttribute *)prototype
Returns the prototype attribute that is used
to define default settings for the receiver.See
Also: - overridesPrototypeDefinitionForKey:
- (NSString *)prototypeName
Returns the name of the prototype attribute
of the receiver.See Also: - prototype
- (NSString *)readFormat
Returns a format string of the appropriate type
that can be used when building an expression that contains the value
of the attribute.See Also: - setReadFormat:, - writeFormat
- (int)scale
Returns the scale of the database representation
for attributes with a value class of NSNumber or NSDecimalNumber.
The returned value can be negative.See Also: - precision, - setScale:
- (NSTimeZone *)serverTimeZone
Returns the time zone assumed for NSDates in
the database server, or the local time zone if one hasn't been
set. An EOAdaptorChannel automatically converts dates between the
time zones used by the server and the client when fetching and saving
values. Applies only to attributes that represent dates.See
Also: + localTimeZone (NSTimeZone), - setServerTimeZone:
- (void)setAdaptorValueConversionMethodName:(NSString
*)conversionMethodName
Sets to conversionMethodName the
name of the method used to convert a custom class into one of the primitive
types that the adaptor knows how to manipulate: NSString, NSNumber,
NSData, or NSDate Note that your adaptor value conversion method
should return an autoreleased object.See
Also: - adaptorValueConversionMethodName
- (void)setAllowsNull:(BOOL)allowsNull
Sets according to allowsNull whether
or not the attribute can have a nil value. If the attribute maps directly
to a column in the database, it also controls whether the database
column can have a NULL value.See Also: - allowsNull
- (void)setColumnName:(NSString
*)columnName
Sets to columnName the
name of the attribute used in communication with the database server.
An adaptor uses this name to identify the column corresponding to
the attribute; this name must match the name of a column in the
database table corresponding to the attribute's entity.This
method makes a derived or flattened attribute simple; the definition is released
and the column name takes its place for use with the server.
| setColumnName: and setDefinition: are
closely related. Only one can be set at any given time. Invoking
either of these methods causes the other value to be set to nil. |
See Also: - columnName
- (void)setDefinition:(NSString
*)definition
Sets to definition the
attribute's definition as recognized by the database server. definition should
be either a value expression defining a derived attribute, such
as "salary * 12", or a data path for a flattened attribute,
such as "toAuthor.name".Prior to invoking this method,
the attribute's entity must have been set by adding the attribute
to an entity. This method will not function correctly if the attribute's
entity has not been set.
This method converts a simple
attribute into a derived or flattened attribute; the columnName is released and
the definition takes its place for use with the server.
| setColumnName: and setDefinition: are
closely related. Only one can be set at any given time. Invoking
either of these methods causes the other value to be set to nil. |
See Also: - definition
- (void)setExternalType:(NSString
*)typeName
Sets to typeName the
type used for the attribute in the database adaptor; for example,
a Sybase "varchar" or an Oracle7 "NUMBER". Each adaptor
defines the set of types that can be supplied to setExternalType:.
The external type you specify for a given attribute must correspond
to the type used in the database server.See
Also: - setDefinition:, - externalType
- (void)setFactoryMethodArgumentType:(EOFactoryMethodArgumentType)argumentType
Sets the type of argument that should be passed
to the "factory method"-which is invoked by the receiver to
create a value for a custom class. Factory methods can accept NSStrings,
NSDatas, or raw bytes; specify an argumentType as EOFactoryMethodArgumentIsNSString, EOFactoryMethodArgumentIsNSData,
or EOFactoryMethodArgumentIsBytes as
appropriate.See Also: - setValueFactoryMethodName:, - factoryMethodArgumentType
- (void)setName:(NSString
*)name
Sets the attribute's name to name. Raises
an NSInvalidArgumentException if name is
already in use by another attribute or relationship of the same
entity, or if name is not a valid
attribute name.See Also: - validateName:, - name
- (void)setParameterDirection:(EOParameterDirection)parameterDirection
Sets the parameter direction for attributes
that are arguments to a stored procedure. parameterDirection should
be one of the following values:See
Also: - setStoredProcedure:forOperation: (EOEntity), - parameterDirection
- (void)setPrecision:(unsigned)precision
Sets to precision the
precision of the database representation for attributes with a value
class of NSNumber or NSDecimalNumber.See
Also: - setScale:, - precision
- (void)setPrototype:(EOAttribute
*)prototype
Sets the prototype attribute. This overrides
any existing settings in the attribute.See
Also: - prototype
- (void)setReadFormat:(NSString
*)aString
Sets the format string that's used to format
the attribute's value for SELECT statements. In aString,
%P is replaced by the attribute's external name. For example:
[myAttribute setReadFormat:@"TO_UPPER(%P)"];
The
read format string is used whenever the attribute is referenced
in a select list or qualifier.
See
Also: - setWriteFormat:, - readFormat
- (void)setReadOnly:(BOOL)flag
Sets whether the value of the attribute can
be modified according to flag. Raises an NSInvalidArgumentException if flag is NO and
the argument is derived but not flattened.See
Also: - isDerived, - isFlattened, - isReadOnly
- (void)setScale:(int)scale
Sets to scale the
scale of the database representation for attributes with a value
class of NSNumber or NSDecimalNumber. scale can
be negative.See Also: - setPrecision:, - scale
- (void)setServerTimeZone:(NSTimeZone
*)aTimeZone
Sets to aTimeZone the
time zone used for NSDates in the database server. If aTimeZone is nil then
the local time zone is used. An EOAdaptorChannel automatically converts
dates between the time zones used by the server and the client when
fetching and saving values. Applies only to attributes that represent dates.See
Also: - serverTimeZone
- (void)setUserInfo:(NSDictionary
*)dictionary
Sets to dictionary the
dictionary of auxiliary data, which your application can use for
whatever it needs. dictionary can
only contain property list data types (that is, NSDictionary, NSArray,
NSData, and NSString).See Also: - userInfo
- (void)setValueClassName:(NSString
*)name
Sets the class name for values of this attribute
to name. When an EOAdaptorChannel
fetches data for the attribute, it's presented to the application
as an instance of this class.The class need not exist in the
run-time system when this message is sent, but it must exist when
an adaptor channel performs a fetch; if the class isn't present
the result depends on the adaptor. See your adaptor's documentation
for information on how absent value classes are handled.
As
an example, if your attribute's values are instances of NSImage,
send the following:
[myAttribute setValueClassName:@"NSImage"];
See
Also: - setValueType:, - valueClassName
- (void)setValueFactoryMethodName:(NSString
*)factoryMethodName
Sets the "factory method"-which is invoked
by the attribute to create an attribute value for a custom class-to factoryMethodName.
The factory method should be a class method returning an autoreleased object
of your custom value class. Use setFactoryMethodArgumentType:to specify
the type of argument that is to be passed to your factory method.See
Also: - valueFactoryMethodName
- (void)setValueType:(NSString
*)typeName
Sets to typeName the
conversion character (such as "i" or "d") for the data type an
NSNumber attribute is converted to and from in your application.
Value types are scalars such as int, float,
and double. Each adaptor supports a different
set of conversion characters for numeric types. However, in most
(if not all) cases it's safe to supply a value of "i" (int)
or "d" (double).See Also: - setValueClassName:, - valueType
- (void)setWidth:(unsigned)length
Sets to length the
maximum amount of bytes the attribute's value may contain. Adaptors
may use this information to allocate space for fetch buffers.See
Also: - width
- (void)setWriteFormat:(NSString
*)string
Sets the format string that's used to format
the attribute's value for INSERT or UPDATE expressions. In string,
%P is replaced by the attribute's value. For example:
[myAttribute setWriteFormat:@"TO_LOWER(%P)"];
See
Also: - setReadFormat:, - writeFormat
- (EOStoredProcedure *)storedProcedure
Returns the stored procedure for which this
attribute is an argument. If this attribute isn't an argument to
a stored procedure but instead is owned by an entity, this method
returns nil.See Also: - entity
- (NSDictionary *)userInfo
Returns a dictionary of user data. Your application
can use this to store any auxiliary information it needs.See
Also: - setUserInfo:
- (NSException *)validateName:(NSString
*)name
Validates name and
returns nil if it is a valid name, or an exception if it isn't.
A name is invalid if it has zero length; starts with a character
other than a letter, a number, or "@", "#", or "_";
or contains a character other than a letter, a number, "@",
"#", "_", or "$". A name is also invalid if the receiver's EOEntity
already has an EOAttribute with the same name, or if the model has
a stored procedure that has an argument with the same name.setName: uses
this method to validate its argument.
- (NSException *)validateValue:(id
*)valueP
Validates valueP by converting it to the attribute's
value type and by testing other attribute validation constraints
(such as allowsNull, width,
and so on). Returns nil if
the value pointed to by *valueP is deemed
to be a legal value for this attribute. Returns a validation exception
otherwise. If, during the validation process, any coercion was performed,
the converted value is assigned to *valueP.See
Also: - adaptorValueByConvertingAttributeValue:, - allowsNull, - valueType, - valueClassName, - width
- (NSString *)valueClassName
Returns the name of the class for custom value
types. When data is fetched for the attribute, it's presented
to the application as an instance of this class. For example, if
a column from the database is represented by instances of NSImage,
this method returns "NSImage".This class must be present
in the run-time system when an EOAdaptorChannel fetches data for
the attribute; if the class isn't present the result depends on
the adaptor. See your adaptor's documentation for information
on how absent value classes are handled.
See
Also: - valueType, - setValueClassName:
- (SEL)valueFactoryMethod
Returns the factory method that's invoked
by the attribute when creating an attribute value that's of a custom
class. The value returned from this method is derived from the attribute's valueFactoryMethodName. If that name
doesn't map to a valid selector in the Objective-C run-time, this method
returns nil.
- (NSString *)valueFactoryMethodName
Returns the name of the factory method that's
used for creating a custom class value.See
Also: - valueFactoryMethod, - setValueFactoryMethodName:
- (NSString *)valueType
Returns the conversion character (such as "i"
or "d") for the data type an NSNumber attribute is converted
to and from in your application. Value types are scalars such as int, float,
and double. See
Also: - valueClassName, - setValueType:
- (unsigned)width
Returns the maximum length (in bytes) for values
that are mapped to this attribute. Returns zero for numeric and
date types.See Also: - setWidth:
- (NSString *)writeFormat
Returns the format string that's used to format
the attribute's value for INSERT or UPDATE expressions. In the
returned string, %P is replaced by the attribute's value.See
Also: - readFormat, - setWriteFormat: