com.webobjects.eoaccess
Class EOAttribute

java.lang.Object
  |
  +--com.webobjects.eoaccess.EOProperty
        |
        +--com.webobjects.eoaccess.EOAttribute

All Implemented Interfaces:

EOPropertyListEncoding, EOSQLExpression.SQLValue

public class EOAttribute

extends EOProperty

implements EOPropertyListEncoding, EOSQLExpression.SQLValue

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. In addition, EOAttributes are used to represent arguments for EOStoredProcedures.

You usually define attributes in the EOModel with the EOModeler application. Your code probably won't need to interact programmatically with EOAttribute unless you are working at the adaptor level.

Creating Attributes

An attribute may be simple, derived, or flattened. A simple attribute typically corresponds to a single column in the database, and may be read or updated directly from or to the database. A simple EOAttribute may also be set as read-only with the setReadOnly method. Read-only attributes of Enterprise Objects are never updated.

A flattened attribute of an entity is actually an attribute of some other entity that is fetched through a relationship by means of a database join. A flattened attribute's external definition is a data path ending in an attribute name. For example, if a Book entity has the relationship toAuthor and the Author entity has the attribute name, you can assign the name of the author as an attribute of your Book entity by creating an EOAttribute with an external name of "toAuthor.name".

A derived attribute is an attribute that does not correspond to a single column or field in the database. A derived attribute is usually created by simply modifying a non-derived attribute, for example, by performing a mathematical operation or appending a string. Some examples of derived attribute external names are "commision / 2" or "salary + overtime". Derived attributes are read-only. Since they don't correspond to actual values in the database, it makes no sense to write a derived value.

Creating a Simple Attribute

A simple attribute needs at least the following characteristics:

• A name unique within its EOEntity.
• The name of a column in the database table for its entity (the EOAttribute's external name)
• A declaration of the type of that column as defined by the database and adaptor (the EOAttribute's external type).
• A declaration of the Java class used to represent values outside the context of an Enterprise Object.
• For Java value classes that require it, a subtype for such distinctions as the distinction between numeric types.

You also have to set whether the attribute is part of its entity's primary key, is a class property, or is used for locking. See the EOEntity class description for more information.

Creating a Derived Attribute

A derived attribute depends on another attribute, so you base it on a definition including that attribute's name rather than on an external name. Because a derived attribute isn't mapped directly to anything in the database, you shouldn't include it in the entity's set of primary key attributes or attributes used for locking.

Creating a Flattened Attribute

A flattened attribute depends on a relationship, so you base it on a definition including that relationship's name rather than on an external name. Because a flattened attribute doesn't correspond directly to anything in its entity's table, you don't have to specify an external name, and shouldn't include it in the entity's set of primary key attributes or attributes used for locking.

Instead of flattening attributes in your model, a better approach is often to directly traverse the object graph through relationships.

Mapping from Database to Objects

Every EOAttribute has an external type, which is the type used by the database to store its associated data, and a Java class used as the type for that data in the client application. The type used by the database is accessed with the setExternalType and externalType methods. You can map database types to a set of standard value classes, which includes:

• String
• Number
• java.math.BigDecimal
• NSData
• NSTimestamp

Database-specific adaptors automatically handle value conversions for these classes. You can also create your own custom value class, so long as you define a format that it uses to interpret data.

The handling of dates assumes by default that both the database server and the client application are running in the local time zone. You can alter the time zone that is assumed for the database server with the setServerTimeZone method. If you alter the server time zone, the adaptor automatically converts dates as they pass into and out of the server.

Working with Custom Data Types

When you create a new model, EOModeler maps each attribute in the model to one of the primitive data types that the adaptor knows how to manipulate: String, Number, java.math.BigDecimal, NSData, and NSTimestamp. For example, suppose you have a photo attribute that is stored in the database as a LONG RAW. When you create a new model, this attribute is mapped to NSData. However, NSData is just an object wrapper for binary data. It doesn't have any methods for operating on images, which would limit what you could do with the image in your application. In such a case, you would probably choose to use a custom data type, such as com.apple.cocoa.NSImage.

For a custom data type to be usable in Enterprise Objects Framework, it must supply methods for importing and exporting itself as one of the primitive types so that it can be read from and written to the database. Specifically, to use a custom data type you need to do the following:

• Set the attribute's value class using the method setValueClassName.
• Set the factory method that will be used to create instances of the class from raw data using the method setValueFactoryMethodName.
• Set the type of the argument that should be passed to the factory method using the method setFactoryMethodArgumentType.
• Set the conversion method that is used to convert the data back into one of the primitive data types that the adaptor can work with using the method setAdaptorValueConversionMethodName. This enables the data to be stored in the database.

If an EOAttribute represents a binary column in the database, the factory method argument type can be either FactoryMethodArgumentIsData or FactoryMethodArgumentIsBytes, indicating that the method takes an NSData object or raw bytes as an argument. If the EOAttribute represents a string or character column, the factory method argument type can be either FactoryMethodArgumentIsString or FactoryMethodArgumentIsBytes, indicating that the method takes a String object or raw bytes as an argument. These types apply when fetching custom values.

Instead of setting the class information programmatically, you can use the Attributes Inspector in EOModeler, which is the more common approach.

Fetching Custom Values

Custom values are created during fetching in EOAdaptorChannel's fetchRow method. This method fetches data in the external (server) type and converts it to a value object, applying the custom value factory method, valueFactoryMethod, to convert the value into the custom class if necessary. Once the value is converted, the EOAdaptorChannel puts it into the dictionary for the row being fetched.

Converting Custom Values

Custom values are converted back to binary or character data in EOAdaptorChannel's evaluateExpression method. For each value in the EOSQLExpression to be evaluated, the EOAdaptorChannel sends the appropriate EOAttribute an adaptorValueByConvertingAttributeValue message to convert it. If the value is any of the standard value classes, it is returned unchanged. If the value is of a custom class, it is converted by applying the conversion method adaptorValueConversionMethod specified in the EOAttribute.

SQL Statement Formats

In addition to mapping database values to object values, an EOAttribute can alter the way values are selected, inserted, and updated in the database by defining special format strings. These format strings allow a client application to extend its reach right down to the server for certain operations. For example, you might want to view an employee's salary on a yearly basis, without defining a derived attribute as in a previous example. In this case, you could set the salary attribute's SELECT statement format to "salary * 12" using setReadFormat and the INSERT and UPDATE statement formats to "salary / 12" using setWriteFormat. Whenever the application retrieves values for the salary attribute, the fetched values are multiplied by 12, and when it writes values back to the database, the values are divided by 12.

Your application can use any legal SQL value expression in a format string, and can even access server-specific features such as functions and stored procedures (see EOEntity's setStoredProcedure method description for more information). Accessing server-specific features can offer the application great flexibility in dealing with its server, but does limit its portability. You are responsible for ensuring that the SQL is well-formed and will be understood by the database server.

Format strings for setReadFormat should use "%P" as the substitution character for the value that is being formatted; format strings for setWriteFormat should use "%V" as the substitution character for the value that is being formatted. The "%@" character will not work. For example:

     myAttribute.setReadFormat("TO_UPPER(%P)");
     myAttribute.setWriteFormat("TO_LOWER(%V)");

Instead of setting the read and write formats programmatically, you can set them in EOModeler, which is the more common approach.

See Also:

FactoryMethodArgumentIsData, FactoryMethodArgumentIsBytes, FactoryMethodArgumentIsString, setReadOnly(boolean flag), setExternalType(String typeName), externalType(), valueClassName(), setServerTimeZone(TimeZone tz), setValueClassName(String name), setValueFactoryMethodName(String factoryMethodName), setFactoryMethodArgumentType(int argumentType), setAdaptorValueConversionMethodName(String conversionMethodName), setReadFormat(String string), setWriteFormat(String string), EOEntity.setStoredProcedure(EOStoredProcedure storedProcedure , String operation)

Field Summary

static int	AdaptorBytesType Integer constant returned by the method adaptorValueType.
static int	AdaptorCharactersType Integer constant returned by the method adaptorValueType.
static int	AdaptorDateType Integer constant returned by the method adaptorValueType.
static int	AdaptorNumberType Integer constant returned by the method adaptorValueType.
static int	FactoryMethodArgumentIsBytes Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, an array of bytes.
static int	FactoryMethodArgumentIsData Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, a binary (NSData) argument.
static int	FactoryMethodArgumentIsString Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, a String argument.
static int	InOutParameter Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.
static int	InParameter Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.
static int	OutParameter Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.
static int	Void Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.

Constructor Summary

	EOAttribute()
protected	EOAttribute(EOEntity entity, String definition)
	EOAttribute(NSDictionary plist, Object owner) Creates an EOAttribute object with the state specified in plist whose parent is owner.

Method Summary

Object	adaptorValueByConvertingAttributeValue(Object value) Checks that the type of value is one of the following primitive adaptor types: String, Number, NSData, or NSTimestamp.
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 NSTimestamp.
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 NSTimestamp.
int	adaptorValueType() Returns a constant that indicates the data type that will be fetched from the database.
boolean	allowsNull() Returns true if the attribute can have a null value, false otherwise.
void	awakeWithPropertyList(NSDictionary plist) Finishes initializing the receiver from plist.
void	beautifyName() Makes the attribute's name conform to the Enterprise Objects Framework's naming convention.
String	className() Returns the fully qualified Java class name of the attribute, for example "java.lang.String".
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 a derived or flattened attribute).
String	definition() Returns the definition of a derived or flattened attribute or null if the attribute is simple.
void	encodeIntoPropertyList(NSMutableDictionary result) Encodes the receiver as a property list.
EOEntity	entity() Returns the entity that owns the attribute, or null if this attribute is acting as an argument for a stored procedure.
String	externalType() Returns the attribute's type as understood by the database.
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.
boolean	isDerived() Returns true if the attribute does not correspond exactly to one column in a table, false otherwise.
boolean	isFlattened() Returns true if the attribute is flattened, false otherwise.
boolean	isReadOnly() Returns true if the value of the attribute can not be modified, false if it can.
String	name() Returns the internal name of the attribute.
Object	newValueForBytes(byte[] bytes, int length) Called by the adaptor during value creation while fetching from the database.
Object	newValueForBytesString(byte[] bytes, int length) Deprecated.
Object	newValueForImmutableBytes(byte[] bytes) Called by the adaptor during value creation while fetching from the database.
Object	newValueForString(String str) Called by the adaptor during value creation while fetching from the database.
boolean	overridesPrototypeDefinitionForKey(String key) Returns true if the attribute has an override, false if the requested key gets its value from the prototype attribute.
int	parameterDirection() Returns the parameter direction for attributes that are arguments to a stored procedure.
Object	parent() Returns the attribute's parent, which is either an EOEntity or an EOStoredProcedure.
int	precision() Returns the precision of the database representation of attributes with a numeric type, i.e., Number or java.math.BigDecimal.
EOAttribute	prototype() Returns the prototype attribute that is used to define default settings for the receiver, or null
String	prototypeName() Returns the name of the prototype attribute of the receiver, or null if there is none.
String	readFormat() Returns a format string used to appropriately format the attribute's value when it is read from the database.
String	relationshipPath() Returns the relationship path for flattened attributes, or null if the receiver is not a flattened attribute.
int	scale() Returns the scale of the database representation for attributes with a numeric type, i.e., Number or java.math.BigDecimal.
TimeZone	serverTimeZone() Returns the time zone assumed for dates in the database server, or the local time zone if one hasn't been set.
void	setAdaptorValueConversionMethodName(String conversionMethodName) Sets the name of the method used to convert a custom class to a primitive type to conversionMethodName.
void	setAllowsNull(boolean allowsNull) Sets whether or not the attribute can have a null value to allowsNull.
void	setClassName(String name) Sets the name of the attribute's class to name.
void	setColumnName(String columnName) Sets the name of the database column that corresponds with this attribute to columnName.
void	setDefinition(String definition) Sets the attribute's definition to definition.
void	setExternalType(String string) Sets the type of the attribute, as recognized by the database adaptor and the database server, to string.
void	setFactoryMethodArgumentType(int argumentType) Sets the type of argument that should be passed to the factory method, which is invoked by the attribute to create a value for a custom class.
void	setName(String name) Sets the attribute's name to name, which can not be a name that is already in use by an attribute or relationship belonging to the same entity as the receiver.
void	setParameterDirection(int parameterDirection) Sets the parameter direction for attributes that are arguments to a stored procedure.
void	setPrecision(int precision) Sets the precision of the database representation for numeric attributes to precision.
void	setPrototype(EOAttribute prototype) Sets the prototype attribute.
void	setReadFormat(String string) Sets the format string that is used to generate the expression value for the attribute for SELECT statements.
void	setReadOnly(boolean yn) Sets whether the value of the attribute can be modified.
void	setScale(int scale) Sets the scale of the database representation of the attribute to scale, which may be negative.
void	setServerTimeZone(TimeZone tz) Sets the time zone used for dates provided by the database server to tz.
void	setUserInfo(NSDictionary dictionary) Sets the dictionary of auxiliary data associated with the attribute to dictionary.
void	setValueClassName(String name) Deprecated.
void	setValueFactoryMethodName(String factoryMethodName) Sets the name of the factory method which is invoked by the attribute to create a value for a custom class to factoryMethodName.
void	setValueType(String string) Sets the format for custom value types, such as "TIFF" or "RTF", to string.
void	setWidth(int length) Sets the maximum number of bytes that the attribute's value may contain to length.
void	setWriteFormat(String string) Sets the format string that is used to generate the expression value for the attribute for INSERT or UPDATE statements.
EOStoredProcedure	storedProcedure() Returns the stored procedure for which this attribute is an argument.
String	toString() Returns a string representation of the receiver.
NSDictionary	userInfo() Returns a dictionary of user data.
Object	validateValue(Object valueP) Validates valueP by attempting to convert it to the attribute's value type and by testing other attribute validation constraints (such as allowsNull, width, and so on).
String	valueClassName() Deprecated.
NSSelector	valueFactoryMethod() Returns the factory method invoked by the attribute when creating an attribute value that's of a custom class.
String	valueFactoryMethodName() Returns the name of the factory method used for creating a custom class value.
String	valueForSQLExpression(EOSQLExpression context) If the context parameter is not null, returns the SQL expression for the receiver.
String	valueType() Returns the format for custom value types, such as "TIFF" or "RTF".
int	width() Returns the maximum length (in bytes) for values that are mapped to this attribute.
String	writeFormat() Returns the format string used to format the attribute's value for INSERT or UPDATE expressions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AdaptorBytesType

public static final int AdaptorBytesType

Integer constant returned by the method adaptorValueType. Represents one of four possible value types to be fetched from a database, in this case, raw byte data.

AdaptorCharactersType

public static final int AdaptorCharactersType

Integer constant returned by the method adaptorValueType. Represents one of four possible value types to be fetched from a database, in this case, character (string) data.

AdaptorDateType

public static final int AdaptorDateType

Integer constant returned by the method adaptorValueType. Represents one of four possible value types to be fetched from a database, in this case, date data.

AdaptorNumberType

public static final int AdaptorNumberType

Integer constant returned by the method adaptorValueType. Represents one of four possible value types to be fetched from a database, in this case, numeric data.

FactoryMethodArgumentIsBytes

public static final int FactoryMethodArgumentIsBytes

Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, an array of bytes.

FactoryMethodArgumentIsData

public static final int FactoryMethodArgumentIsData

Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, a binary (NSData) argument.

FactoryMethodArgumentIsString

public static final int FactoryMethodArgumentIsString

Integer constant used with the methods factoryMethodArgumentType and setFactoryMethodArgumentType to specify the type of argument that should be passed to the attribute's factory method, in this case, a String argument.

InOutParameter

public static final int InOutParameter

Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.

InParameter

public static final int InParameter

Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.

OutParameter

public static final int OutParameter

Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.

Void

public static final int Void

Integer constant representing one of four possible parameter directions for EOAttributes that represent arguments to a stored procedure.

Constructor Detail

EOAttribute

public EOAttribute()

EOAttribute

public EOAttribute(NSDictionary plist,
                   Object owner)

Creates an EOAttribute object with the state specified in plist whose parent is owner. The possible keys for plist are:

• prototypeName
• externalType
• isReadOnly
• allowsNull
• valueType
• writeFormat
• readFormat
• width
• factoryMethodArgumentType
• adaptorValueConversionMethodName
• valueFactoryMethodName
• precision
• scale
• serverTimeZone
• parameterDirection
• userInfo
• internalInfo

Parameters:

plist - A dictionary whose keys are attribute names and whose values are the attribute values for the new EOAttribute object.

owner - The parent object for the new EOAttribute.

EOAttribute

protected EOAttribute(EOEntity entity,
                      String definition)

Method Detail

adaptorValueByConvertingAttributeValue

public Object adaptorValueByConvertingAttributeValue(Object value)

Checks that the type of value is one of the following primitive adaptor types: String, Number, NSData, or NSTimestamp. If not, this method attempts to convert value to a primitive type by invoking the method returned by adaptorValueConversionMethod. Throws an exception if unable to convert value.

Parameters:

value - The value whose type is to be checked.

Returns:

value, or the converted object.

Throws:

IllegalArgumentException - if unable to convert value to a primitive adaptor type.

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 NSTimestamp. 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 method at runtime, null is returned.

Returns:

The method used to convert a custom class into one of the primitive types, or null.

See Also:

adaptorValueByConvertingAttributeValue(Object value), adaptorValueConversionMethodName(), NSSelector

adaptorValueConversionMethodName

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

Returns:

The name of the conversion method.

See Also:

adaptorValueByConvertingAttributeValue(Object value)

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 constants:

Constant	Description
AdaptorNumberType	A numeric value
AdaptorCharactersType	A string of characters
AdaptorBytesType	An array of raw bytes
AdaptorDateType	A date

Throws an exception if the attribute uses a custom class and has not specified a FactoryMethodArgumentType.

Returns:

A constant indicating the data type that will be fetched from the database.

Throws:

IllegalStateException - if the attribute uses a custom class and has not specified a FactoryMethodArgumentType.

See Also:

factoryMethodArgumentType()

allowsNull

public boolean allowsNull()

Returns true if the attribute can have a null value, false otherwise. If the attribute maps directly to a column in the database, allowsNull also specifies whether the database column can have a null value.

Returns:

true if the attribute can have a null value.

See Also:

setAllowsNull(boolean allowsNull)

awakeWithPropertyList

public void awakeWithPropertyList(NSDictionary plist)

Finishes initializing the receiver from plist. 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 plist.

Specified by:

awakeWithPropertyList in interface EOPropertyListEncoding

Parameters:

plist - A dictionary of attribute keys and values with which to complete initialization of an EOAttribute object.

beautifyName

public void beautifyName()

Makes the attribute's name conform to the Enterprise Objects Framework's naming 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:

EOEntity.nameForExternalName(String name, String separatorString , boolean initialCaps ), EOModel.beautifyNames()

className

public String className()

Returns the fully qualified Java class name of the attribute, for example "java.lang.String".

Returns:

The fully qualified name of the attribute's class.

See Also:

setClassName(String name)

columnName

public 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 a derived or flattened attribute). An adaptor uses this name to identify the column corresponding to the attribute. The application should never need to use the column name.

Note that columnName and definition are mutually exclusive; if one returns a value, the other returns null.

Returns:

The name of the column in the database that corresponds to the attribute, or null.

See Also:

externalType(), definition()

definition

public String definition()

Returns the definition of a derived or flattened attribute 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.

Returns:

The definition for a derived or flattened attribute, or null.

See Also:

externalType(), setDefinition(String definition), columnName()

encodeIntoPropertyList

public void encodeIntoPropertyList(NSMutableDictionary result)

Encodes the receiver as a property list.

Specified by:

encodeIntoPropertyList in interface EOPropertyListEncoding

Parameters:

result - A mutable dictionary into which the keys and values of the EOAttribute object's state are encoded.

See Also:

EOAttribute(NSDictionary plist, Object owner)

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.

Returns:

The entity that owns the attribute, or null.

See Also:

storedProcedure()

externalType

public String externalType()

Returns the attribute's type as understood by the database.

Returns:

The attribute's data type in the database.

See Also:

columnName(), setExternalType(String typeName)

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 constants:

Constant	Argument Type
FactoryMethodArgumentIsData	NSData
FactoryMethodArgumentIsString	String
FactoryMethodArgumentIsBytes	an array of bytes

Returns:

The type of argument that should be passed to the factory method.

See Also:

valueFactoryMethod(), setFactoryMethodArgumentType(int argumentType)

isDerived

public boolean isDerived()

Returns true if the attribute does not correspond exactly to one column in a table, false otherwise. For example, an attribute with a definition of "attributeName + 1" is a derived attribute.

Returns:

true if the attribute does not correspond exactly to one column in a table, false otherwise.

See Also:

isFlattened(), definition()

isFlattened

public boolean isFlattened()

Returns true if the attribute is flattened, false otherwise. A flattened attribute is one that is accessed through an entity's relationships but belongs to another entity.

For example, if a Book entity has the relationship toAuthor and the Author entity has the attribute name, you can assign the name of the author as an attribute of your Book entity by creating flattened attribute with an external name "toAuthor.name".

Returns:

true if the attribute is flattened, false otherwise.

See Also:

isDerived(), definition()

isReadOnly

public boolean isReadOnly()

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

Returns:

true if the value of the attribute can not be modified.

See Also:

setReadOnly(boolean flag)

name

public String name()

Returns the internal name of the attribute.

Overrides:

name in class EOProperty

Returns:

The attribute's name.

See Also:

columnName(), definition(), setName(String name)

newValueForBytes

public Object newValueForBytes(byte[] bytes,
                               int length)

Called by the adaptor during value creation while fetching from the database. This method will generate an NSData or custom class value.

You should not need to use this method unless you are implementing a subclass of EOAdaptor. Clients of the model should not call this method.

Parameters:

bytes - The bytes from which to create the new value.

length - Unused.

Returns:

A new value object generated from bytes.

newValueForBytesString

public Object newValueForBytesString(byte[] bytes,
                                     int length)

Deprecated.

newValueForImmutableBytes

public Object newValueForImmutableBytes(byte[] bytes)

Called by the adaptor during value creation while fetching from the database. This method will generate an NSData or custom class value.

You should not need to use this method unless you are implementing a subclass of EOAdaptor. Clients of the model should not call this method. Callers of this method must guarantee that bytes can not be modified after this call.

Parameters:

bytes - The bytes from which to create the new value.

Returns:

A new value object generated from bytes.

newValueForString

public Object newValueForString(String str)

Called by the adaptor during value creation while fetching from the database. This method will generate a String, NSData or custom class value.

You should not need to use this method unless you are implementing a subclass of EOAdaptor. Clients of the model should not call this method.

overridesPrototypeDefinitionForKey

public boolean overridesPrototypeDefinitionForKey(String key)

Returns true if the attribute has an override, false if the requested key gets its value from the prototype attribute. Valid keys include "columnName", "externalType", and so on.

Parameters:

key - An attribute key.

Returns:

true if the value for the requested key is overridden, false otherwise.

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 constants:

Constant	Description
Void	No parameters
InParameter	Input only parameters
OutParameter	Output only parameters
InOutParameter	Bi-directional parameters (both input and output)

Returns:

The parameter direction for attributes that are arguments to a stored procedure.

See Also:

storedProcedure(), setParameterDirection(int parameterDirection), EOEntity.storedProcedureForOperation(String operation)

parent

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

Returns:

The attribute's parent.

See Also:

entity(), storedProcedure(), EOEntity, EOStoredProcedure

precision

public int precision()

Returns the precision of the database representation of attributes with a numeric type, i.e., Number or java.math.BigDecimal.

Returns:

The precision of the database representation of the attribute.

See Also:

setPrecision(int precision), scale()

prototype

public EOAttribute prototype()

Returns the prototype attribute that is used to define default settings for the receiver, or null

Returns:

The prototype attribute for the receiver, or null.

See Also:

overridesPrototypeDefinitionForKey(String key)

prototypeName

public String prototypeName()

Returns the name of the prototype attribute of the receiver, or null if there is none.

Returns:

The name of the prototype attribute of the receiver.

See Also:

prototype()

readFormat

public String readFormat()

Returns a format string used to appropriately format the attribute's value when it is read from the database.

Returns:

A format string used to format the attribute value when reading from the database.

See Also:

setReadFormat(String string), writeFormat()

relationshipPath

public String relationshipPath()

Returns the relationship path for flattened attributes, or null if the receiver is not a flattened attribute.

Overrides:

relationshipPath in class EOProperty

Returns:

The relationship path for the attribute, or null.

See Also:

isFlattened()

scale

public int scale()

Returns the scale of the database representation for attributes with a numeric type, i.e., Number or java.math.BigDecimal. The returned value can be negative.

Returns:

The scale of the database representation of the attribute.

See Also:

setScale(int scale), precision()

serverTimeZone

public TimeZone serverTimeZone()

Returns the time zone assumed for dates 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.

Returns:

The implicit time zone for dates provided by the database server.

See Also:

setServerTimeZone(TimeZone tz)

setAdaptorValueConversionMethodName

public void setAdaptorValueConversionMethodName(String conversionMethodName)

Sets the name of the method used to convert a custom class to a primitive type to conversionMethodName.

Parameters:

conversionMethodName - The name of the method used to convert a custom class.

See Also:

adaptorValueConversionMethodName()

setAllowsNull

public void setAllowsNull(boolean allowsNull)

Sets whether or not the attribute can have a null value to allowsNull. If the attribute maps directly to a column in the database, it also determines whether the database column can have a null value.

Parameters:

allowsNull - Specifies whether the attribute can be null.

See Also:

allowsNull()

setClassName

public void setClassName(String name)

Sets the name of the attribute's class to name. The name argument should be a fully qualified Java class name, such as "java.lang.String".

Parameters:

name - The fully qualified Java class name for the attribute.

setColumnName

public void setColumnName(String columnName)

Sets the name of the database column that corresponds with this attribute to columnName. An adaptor uses this name to identify the column corresponding to the attribute; columnName must match the name of a column in the database table corresponding to the attribute's entity.

Setting the column name has the effect of making a derived or flattened attribute simple. The column name takes the place of the model path (for flattened attributes) or expression (for derived attributes) used to obtain the value of the attribute from the database server.

Note: setColumnName and setDefinition are mutually exclusive. Only one can be set at any given time. Invoking either of these methods causes the other value to be set to null.

Parameters:

columnName - The name of the database column corresponding to this attribute.

See Also:

setDefinition(String definition), columnName(), definition()

setDefinition

public void setDefinition(String definition)

Sets the attribute's definition to definition. 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 set to null and the definition takes its place for use with the database server.

Note: setColumnName and setDefinition are mutually exclusive. Only one can be set at any given time. Invoking either of these methods causes the other value to be set to null.

Parameters:

definition - The attribute's definition.

See Also:

setColumnName(String columnName), definition(), columnName()

setExternalType

public void setExternalType(String string)

Sets the type of the attribute, as recognized by the database adaptor and the database server, to string. 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 to store the value of the attribute.

Parameters:

string - The type used by the database server to store the attribute.

See Also:

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 attribute to create a value for a custom class. Factory methods can accept Strings, NSDatas, or raw bytes. argumentType must be one of the following constants:

• FactoryMethodArgumentIsString
• FactoryMethodArgumentIsData
• FactoryMethodArgumentIsData

Parameters:

argumentType - Constant representing the type of argument that should be passed to the factory method.

See Also:

setValueFactoryMethodName(String factoryMethodName), factoryMethodArgumentType()

setName

public void setName(String name)

Sets the attribute's name to name, which can not be a name that is already in use by an attribute or relationship belonging to the same entity as the receiver.

Parameters:

name - The name to set for the attribute.

See Also:

name(), entity()

setParameterDirection

public void setParameterDirection(int parameterDirection)

Sets the parameter direction for attributes that are arguments to a stored procedure. parameterDirection must be one of the following constants:

• Void
• InParameter
• OutParameter
• InOutParameter

Parameters:

parameterDirection - The parameter direction of arguments to a stored procedure.

See Also:

parameterDirection(), EOEntity.setStoredProcedure( EOStoredProcedure storedProcedure, String operation)

setPrecision

public void setPrecision(int precision)

Sets the precision of the database representation for numeric attributes to precision.

Parameters:

precision - The precision of the database representation for the attribute.

See Also:

precision(), setScale(int scale)

setPrototype

public void setPrototype(EOAttribute prototype)

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

Parameters:

prototype - The protytpe attribute to set for the receiver.

See Also:

prototype()

setReadFormat

public void setReadFormat(String string)

Sets the format string that is used to generate the expression value for the attribute for SELECT statements. For example,

     myAttribute.setReadFormat("TO_UPPER(%P)");
 

%P in string is replaced by the attribute's external name at runtime. The read format string is used whenever the attribute is referenced in a select list or qualifier.

Parameters:

string - A string to format the attribute's value when reading from the database.

See Also:

setWriteFormat(String string), readFormat()

setReadOnly

public void setReadOnly(boolean yn)

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

Parameters:

yn - Boolean flag that specifies whether the attribute can be modified.

Throws:

IllegalArgumentException - if yn is false and the attribute is derived but not flattened.

See Also:

isDerived(), isFlattened(), isReadOnly()

setScale

public void setScale(int scale)

Sets the scale of the database representation of the attribute to scale, which may be negative.

Parameters:

scale - The scale of the database representation of the attribute.

See Also:

scale(), setPrecision(int precision)

setServerTimeZone

public void setServerTimeZone(TimeZone tz)

Sets the time zone used for dates provided by the database server to tz. If tz is null, 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.

Parameters:

tz - The time zone to assume for dates from the database server.

See Also:

serverTimeZone()

setUserInfo

public void setUserInfo(NSDictionary dictionary)

Sets the dictionary of auxiliary data associated with the attribute to dictionary. The application can use the userInfo dictionary for whatever it needs. dictionary can only contain property list data types (that is, NSDictionary, NSArray, NSData, and java.lang.String).

Parameters:

dictionary - A dictionary of arbitrary auxiliary data for the attribute.

See Also:

userInfo()

setValueClassName

public void setValueClassName(String name)

Deprecated.

setValueFactoryMethodName

public void setValueFactoryMethodName(String factoryMethodName)

Sets the name of the factory method which is invoked by the attribute to create a value for a custom class to factoryMethodName. The factory method should be a static method returning an object of the custom value class. Use setFactoryMethodArgumentType to specify the type of argument to pass to the factory method.

Parameters:

factoryMethodName - The name of the factory method.

See Also:

valueFactoryMethodName(), setFactoryMethodArgumentType(int argumentType)

setValueType

public void setValueType(String string)

Sets the format for custom value types, such as "TIFF" or "RTF", to string.

Parameters:

string - A string identifying the format for a custom value type.

See Also:

setValueClassName(String name), valueType()

setWidth

public void setWidth(int length)

Sets the maximum number of bytes that the attribute's value may contain to length. Adaptors may use this information to allocate space for fetch buffers.

Parameters:

length - The maximum number of bytes the attribute's value may contain.

See Also:

width()

setWriteFormat

public void setWriteFormat(String string)

Sets the format string that is used to generate the expression value for the attribute for INSERT or UPDATE statements. For example,

     myAttribute.setWriteFormat("TO_LOWER(%V)");
 

%V in string is replaced by the attribute's value at runtime.

Parameters:

string - A string to format the attribute's value when writing to the database.

See Also:

setReadFormat(String string), writeFormat()

storedProcedure

public EOStoredProcedure storedProcedure()

Returns the stored procedure for which this attribute is an argument. If the receiver is an attribute in an entity, this method returns null.

Returns:

The stored procedure for which this attribute is an argument, or null.

See Also:

entity()

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

A string representation of the receiver.

userInfo

public NSDictionary userInfo()

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

Returns:

A dictionary of arbitrary user data.

See Also:

setUserInfo(NSDictionary dictionary)

validateValue

public Object validateValue(Object valueP)
                     throws NSValidation.ValidationException

Validates valueP by attempting to convert it to the attribute's value type and by testing other attribute validation constraints (such as allowsNull, width, and so on). Throws an exception if any errors occur during validation. On success, returns either the converted value or, if no conversion was performed, returns the original value.

Parameters:

valueP - The object to be validated.

Returns:

valueP, the converted value, or null.

Throws:

NSValidation.ValidationException - if validation fails.

See Also:

adaptorValueByConvertingAttributeValue(Object value)

valueClassName

public String valueClassName()

Deprecated.

valueFactoryMethod

public NSSelector valueFactoryMethod()

Returns the factory method 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 valueFactoryMethodName does not map to a valid selector at runtime, this method returns null.

Returns:

The factory method invoked by the attribute when creating a custom class value, or nullSee Also:

valueFactoryMethodName(), NSSelector

valueFactoryMethodName

public String valueFactoryMethodName()

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

Returns:

The name of the factory method used for creating a custom class value.

See Also:

valueFactoryMethod(), setValueFactoryMethodName(String factoryMethodName)

valueForSQLExpression

public String valueForSQLExpression(EOSQLExpression context)

If the context parameter is not null, returns the SQL expression for the receiver. If context is null and the receiver has a definition set, returns the SQL expression that corresponds to the receiver's definition. If both context and definition are null, returns the receiver's name.

Specified by:

valueForSQLExpression in interface EOSQLExpression.SQLValue

Parameters:

context - An EOSQLExpression object.

Returns:

The SQL expression for the receiver, or its name.

valueType

public String valueType()

Returns the format for custom value types, such as "TIFF" or "RTF".

Returns:

The format for custom value types.

See Also:

setValueType(String typeName)

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.

Returns:

The maximum length (in bytes) for values mapped to this attribute.

See Also:

setWidth(int length)

writeFormat

public String writeFormat()

Returns the format string used to format the attribute's value for INSERT or UPDATE expressions.

Returns:

A format string used to format the attribute's value for writing to the database.

See Also:

readFormat(), setWriteFormat(String string)