WebObjects 5.2

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:

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:

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:

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:

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:


ConstantDescription
VoidNo parameters
InParameterInput only parameters
OutParameterOutput only parameters
InOutParameterBi-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)

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.