PATH  WebObjects 4.0 Documentation > EOAccess Reference



EOAttribute

Inherits From:
NSObject

EOPropertyListEncoding

Inherits From:
com.apple.yellow.eoaccess


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 WebObjects 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 JavaObjective-C objects, see "Mapping Attributes." 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.

EOPropertyListEncoding
awakeWithPropertyList
encodeIntoPropertyList

Method Types

Constructors
EOAttribute
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
Converting to adaptor value types
adaptorValueByConvertingAttributeValue
adaptorValueType
Working with custom value types
setValueFactoryMethodName
valueFactoryMethod
valueFactoryMethodName
setFactoryMethodArgumentType
factoryMethodArgumentType
setAdaptorValueConversionMethodName
adaptorValueConversionMethod
adaptorValueConversionMethodName
archiveDataForObject
Accessing attribute characteristics
setReadOnly
isReadOnly
isDerived
isFlattened
Accessing SQL statement formats
setReadFormat
readFormat
setWriteFormat
writeFormat
Accessing the user dictionary
setUserInfo
userInfo
Working with stored procedures
setParameterDirection
parameterDirection
storedProcedure
Working with prototypes
overridesPrototypeDefinitionForKey
prototype
prototypeName
setPrototype

Constructors


EOAttribute

public EOAttribute()

Creates a new EOAttribute.

public EOAttribute(NSDictionary propertyList, java.lang.Object owner)

Creates a new EOAttribute initialized from propertyList-a dictionary containing only property list data types (that is, java.lang.Strings, NSDictionary, NSArrays, and NSDatas). This constructor is used by EOModeler when it reads in a Model from a file, for example. The owner argument should be the EOAttribute's EOEntity or EOStoredProcedure. EOAttributes created from a property list must receive an awakeWithPropertyList message immediately after creation before they are fully functional, but the awake... message should be deferred until the all of the other objects in the model have also been created.

See also: awakeWithPropertyList (EOPropertyListEncoding), encodeIntoPropertyList (EOPropertyListEncoding)



archiveDataForObject

public static NSData archiveDataForObject(NSObject anObject)

Return anObject's value as a NSData object whose bytes can be stored in an external repository.

<<Need to add more info to this on the implications to custom value classes.>>


Instance Methods


adaptorValueByConvertingAttributeValue

public java.lang.Object adaptorValueByConvertingAttributeValue(java.lang.Object value)

Ensures that value is either a String, Number, 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, archiveDataForObject will be invoked to convert the attribute value.

See also: adaptorValueConversionMethod, adaptorValueType


adaptorValueConversionMethod

public NSSelector adaptorValueConversionMethod()

Returns the method used to convert a custom class into one of the primitive types that the adaptor knows how to manipulate: String, Number, 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 Java run-time, null is returned.

See also: adaptorValueByConvertingAttributeValue, adaptorValueConversionMethodName


adaptorValueConversionMethodName

public java.lang.String 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: String, Number, NSData, or NSDate.

See also: adaptorValueByConvertingAttributeValue


adaptorValueType

public int adaptorValueType()

Returns a constant that indicates the data type that will be fetched from the database. Currently, this method returns one of the following values:

Constant Description
AdaptorNumberType A number value
AdaptorCharactersType A string of characters
AdaptorBytesType Raw bytes
AdaptorDateType A date

See also: factoryMethodArgumentType


allowsNull

public boolean allowsNull()

Returns true to indicate that the attribute can have a null value, false 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


awakeWithPropertyList

public void awakeWithPropertyList(NSDictionary propertyList)

Finishes initializing the receiver from propertyList, which must have been created with a constructor of the form:

public ClassName(NSDictionary propertyList, java.lang.Object owner)

awakeWithPropertyList is responsible for restoring references to other objects. Consequently, it should not be invoked until all other objects that the receiver might reference have been created from propertyList.

See also: encodeIntoPropertyList


beautifyName

public 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: nameForExternalName (EOEntity), validateName, beautifyNames (EOModel)


columnName

public java.lang.String columnName()

Returns the name of the column in the database that corresponds to this attribute, or null 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 null.

See also: , externalType


definition

public java.lang.String definition()

Returns a derived or flattened attribute's definition, or null 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 null.

See also: externalType, setDefinition


encodeIntoPropertyList

public void encodeIntoPropertyList(NSMutableDictionary propertyList)

Returns the receiver as a property list.

See also: awakeWithPropertyList


entity

public EOEntity entity()

Returns the entity that owns the attribute, or null if this attribute is acting as an argument for a stored procedure.

See also: storedProcedure


externalType

public java.lang.String externalType()

Returns the attribute's type as understood by the database; for example, a Sybase "varchar" or an Oracle "NUMBER".

See also: columnName, setExternalType


factoryMethodArgumentType

public int 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
FactoryMethodArgumentIsData NSData
FactoryMethodArgumentIsString java.lang.String NSString
FactoryMethodArgumentIsBytes raw bytes

See also: valueFactoryMethod, setFactoryMethodArgumentType


isDerived

public boolean isDerived()

Returns false if the attribute corresponds exactly to one column in the table associated with its entity, and true 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


isFlattened

public boolean isFlattened()

Returns true if the attribute is flattened, false 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


isReadOnly

public boolean isReadOnly()

Returns true if the value of the attribute can't be modified, false if it can.

See also: setReadOnly


name

public java.lang.String name()

Returns the attribute's name.

See also: columnName, definition, setName


overridesPrototypeDefinitionForKey

public boolean overridesPrototypeDefinitionForKey(java.lang.String key)

Returns false if the requested key gets its value from the prototype attribute. If the attribute has an override, then this method returns true. Valid values for key include "columnName," "valueClass," and so on.

See also: prototype


parameterDirection

public int parameterDirection()

Returns the parameter direction for attributes that are arguments to a stored procedure. This method returns one of the following values:

Constant Description
Void No parameters
InParameter Input only parameters
OutParameter Output only parameters
InOutParameter Bidirectional parameters (input and output)

See also: storedProcedure, storedProcedureForOperation (EOEntity), setParameterDirection


parent

public java.lang.Object 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.


precision

public int precision()

Returns the precision of the database representation for attributes with a value class of java.lang.Number or java.math.BigDecimal.

See also: scale


prototype

public EOAttribute prototype()

Returns the prototype attribute that is used to define default settings for the receiver.

See also: overridesPrototypeDefinitionForKey


prototypeName

public java.lang.String prototypeName()

Returns the name of the prototype attribute of the receiver.

See also: prototype


readFormat

public java.lang.String 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


scale

public int scale()

Returns the scale of the database representation for attributes with a value class of Number or java.math.BigDecimal. The returned value can be negative.

See also: precision, setScale


serverTimeZone

public TimeZone 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: setServerTimeZone


setAdaptorValueConversionMethodName

public void setAdaptorValueConversionMethodName(java.lang.String 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: java.lang.String, java.lang.Number, com.apple.yellow.foundation.NSData, or com.apple.yellow.foundation.NSDate..

See also: adaptorValueConversionMethodName


setAllowsNull

public void setAllowsNull(boolean allowsNull)

Sets according to allowsNull whether or not the attribute can have a nullvalue. 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


setColumnName

public void setColumnName(java.lang.String 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.

Note: 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 null

See also: columnName


setDefinition

public void setDefinition(java.lang.String 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 removed and the definition takes its place for use with the server.

Note: 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 null.

See also: definition


setExternalType

public void setExternalType(java.lang.String 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


setFactoryMethodArgumentType

public void setFactoryMethodArgumentType(int 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 java.lang.Strings, com.apple.yellow.foundation.NSDatas, or raw bytes; specify an argumentType as EOFactoryMethodArgumentIsNSString, EOFactoryMethodArgumentIsNSData, or EOFactoryMethodArgumentIsBytes as appropriate.

See also: setValueFactoryMethodName, factoryMethodArgumentType


setName

public void setName(java.lang.String name)

Sets the attribute's name to name. Throws an exception 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


setParameterDirection

public void setParameterDirection(int 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 (EOEntity), parameterDirection


setPrecision

public void setPrecision(int precision)

Sets to precision the precision of the database representation for attributes with a value class of Number or java.math.BigDecimal.

See also: setScale, precision


setPrototype

public void setPrototype(EOAttribute prototype)

Sets the prototype attribute. This overrides any existing settings in the attribute.

See also: prototype


setReadFormat

public void setReadFormat(java.lang.String 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.

The read format string is used whenever the attribute is referenced in a select list or qualifier.

See also: setWriteFormat, readFormat


setReadOnly

public void setReadOnly(boolean flag)

Sets whether the value of the attribute can be modified according to flag. Throws an exception if flag is false and the argument is derived but not flattened.

See also: isDerived, isFlattened, isReadOnly


setScale

public void setScale(int scale)

Sets to scale the scale of the database representation for attributes with a value class of Number or java.math.BigDecimal. scale can be negative.

See also: setPrecision, scale


setServerTimeZone

public void setServerTimeZone(NSTimeZone aTimeZone)

Sets to aTimeZone the time zone used for NSDates in the database server. If aTimeZone is null 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


setUserInfo

public 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 java.lang.String).

See also: userInfo


setValueClassName

public void setValueClassName(java.lang.String 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.

See also: setValueType, valueClassName


setValueFactoryMethodName

public void setValueFactoryMethodName(java.lang.String 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 static method returning an object of your custom value class. Use setFactoryMethodArgumentTypeto specify the type of argument that is to be passed to your factory method.

See also: valueFactoryMethodName


setValueType

public void setValueType(java.lang.String typeName)

Sets to typeName the conversion character (such as "i" or "d") for the data type a Number 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


setWidth

public void setWidth(int 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


setWriteFormat

public void setWriteFormat(java.lang.String 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.

See also: setReadFormat, writeFormat


storedProcedure

public 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 null.

See also: entity


userInfo

public NSDictionary userInfo()

Returns a dictionary of user data. Your application can use this to store any auxiliary information it needs.

See also: setUserInfo


validateName

public java.lang.Throwable validateName(java.lang.String name)

Validates name and returns null 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 characterother 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.


valueClassName

public java.lang.String 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.

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


valueFactoryMethod

public NSSelector 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 method in the Java run-time, this method returns null.


valueFactoryMethodName

public java.lang.String valueFactoryMethodName()

Returns the name of the factory method that's used for creating a custom class value.

See also: valueFactoryMethod, setValueFactoryMethodName


valueType

public java.lang.String valueType()

Returns the conversion character (such as "i" or "d") for the data type a Number attribute is converted to and from in your application. Value types are scalars such as int, float, and double.

See also: valueClassName, setValueType


width

public int 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


writeFormat

public java.lang.String 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





Copyright © 1998, Apple Computer, Inc. All rights reserved.