home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOAttribute.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  13.5 KB  |  342 lines
  1. // EOAttribute.h
  2. // Copyright (c) 1994, NeXT Software, Inc. All rights reserved. 
  3.  
  4. #import <EOControl/EOControl.h>
  5. #import <EOAccess/EOPropertyListEncoding.h>
  6.  
  7. @class EOExpressionArray;
  8. @class EOEntity;
  9. @class EOStoredProcedure;
  10.  
  11. // An EOAttribute represents a column, field or property in a database, and
  12. // associates an internal name with an external name or expression by which
  13. // the property is known to the database.  An EOAttribute also maintains type
  14. // information required for binding to the instance variables of objects.
  15. // EOAttributes are also used to represent arguments for EOStoredProcedures.
  16. //
  17. // FLATTENED AND DERIVED ATTRIBUTES
  18. //
  19. // An attribute may be flattened by setting its external name to a model
  20. // path. For example, if a Book entity has the relationship toAuthor and
  21. // the Author entity has the attribute name, you can assign the author's
  22. // name as an attribute of your Book EOEntity by creating an EOAttribute
  23. // with an external name of "toAuthor.name".
  24. //
  25. // A derived attribute is an attribute that doesn't correspond to a single
  26. // column or field in the database. A derived attribute is usually created by
  27. // simply modifying a non-derived attribute; for example, by adding a certain
  28. // amount or appending a string. Examples of derived attribute external
  29. // names are: "commision / 2", "salary + overtime".
  30.  
  31. typedef enum {
  32.     EOFactoryMethodArgumentIsNSData = 0,
  33.     EOFactoryMethodArgumentIsNSString,
  34.     EOFactoryMethodArgumentIsBytes
  35. } EOFactoryMethodArgumentType;
  36.  
  37. typedef enum {
  38.     EOAdaptorNumberType,
  39.     EOAdaptorCharactersType,
  40.     EOAdaptorBytesType,
  41.     EOAdaptorDateType
  42. } EOAdaptorValueType;
  43.  
  44. typedef enum {
  45.   EOVoid = 0,
  46.   EOInParameter,
  47.   EOOutParameter,
  48.   EOInOutParameter,
  49. } EOParameterDirection;
  50.  
  51.  
  52. @interface EOAttribute : NSObject <EOPropertyListEncoding>
  53. {
  54.     NSString *_name;
  55.     id _parent;
  56.     NSString *_columnName;
  57.     EOExpressionArray *_definitionArray;
  58.     NSString *_externalType;
  59.     NSString *_valueType;
  60.     NSString *_valueClassName;
  61.     NSString *_readFormat;
  62.     NSString *_writeFormat;
  63.     NSTimeZone *_serverTimeZone;
  64.     unsigned int _width;
  65.     unsigned short _precision;
  66.     short _scale;
  67.     Class _valueClass;
  68.     EOFactoryMethodArgumentType _argumentType;
  69.     NSString *_valueFactoryMethodName;
  70.     NSString *_adaptorValueConversionMethodName;
  71.     SEL _valueFactoryMethod;
  72.     SEL _adaptorValueConversionMethod;
  73.     struct {
  74.         unsigned int allowsNull:1;
  75.         unsigned int isReadOnly:1;
  76.         unsigned int isParentAnEOEntity:1;
  77.         unsigned int extraRefCount:29;
  78.     } _flags;
  79.     
  80.     NSDictionary *_sourceToDestinationKeyMap;
  81.     EOParameterDirection _parameterDirection;
  82.     NSDictionary *_userInfo;
  83. }
  84.  
  85. - (NSString *)name;
  86.     // Returns the internal name of the attribute.
  87.  
  88. - (EOEntity *)entity;
  89.     // Returns the entity that owns the attribute.
  90.     // If this attribute is acting as an argument for a stored procedure,
  91.     // this will return nil.
  92.  
  93. - (EOStoredProcedure *)storedProcedure;
  94.     // Returns the store procedure for which this attribute is an
  95.     // argument. If this is an attribute in an entity, this method
  96.     // will return nil;
  97.  
  98. - (id)parent;
  99.     // Returns an EOEntity or EOStoredProcedure.
  100.     // Should be used when you need to find the model for an attribute.
  101.     // [[attribute parent] model]
  102.  
  103. - (NSString *)externalType;
  104.     // Returns the attribute's type as understood by the database.
  105.  
  106. // The following two methods are closely related. Only one can be set
  107. // at any given time. Invoking either of these methods causes the other
  108. // value to be set to nil.
  109. - (NSString *)columnName;
  110.     // Returns the name of the column in the database that corresponds to this
  111.     // attribute.
  112.  
  113. - (NSString *)definition;
  114.     // Returns the definition of this attribute. The definition is used to
  115.     // describe flattened and derived attributes. The DBMS specific language
  116.     // generator will make extensive use of this value.
  117.  
  118. - (BOOL)isFlattened;
  119.     // Returns YES if the attribute is flattened, NO otherwise.
  120.  
  121. - (BOOL)isDerived;
  122.     // Returns YES if the attribute doesn't correspond exactly to one column
  123.     // in a table (for example, "attrName + 1"), NO otherwise.
  124.  
  125. - (BOOL)isReadOnly;
  126.     // Returns YES if the value of the attribute can't be modified, NO if
  127.     // it can.
  128.  
  129. - (NSString *)valueClassName;
  130.     // Returns the name of the class for custom-value types. If a column
  131.     // from the database is to be represented by an NSImage, for example,
  132.     // this returns "NSImage".
  133.  
  134. - (NSString *)valueType;
  135.     // A format for custom-value types, such as "TIFF" or "RTF".
  136.  
  137. - (unsigned)width;
  138.     // the maximum length in bytes for values mapped to this attribute.
  139.     // Returns zero for number and date types
  140.  
  141. - (unsigned)precision;
  142.     // For attributes with a value class of NSNumber or NSDecimalNumber,
  143.     // the precision of the database representation
  144.  
  145. - (int)scale;
  146.     // For attributes with a value class of NSNumber or NSDecimalNumber, the
  147.     // scale of the database representation (can be negative).
  148.  
  149. - (BOOL)allowsNull;
  150.  
  151. - (NSString *)writeFormat;
  152. - (NSString *)readFormat;
  153.     // These methods return format strings for building expressions of the
  154.     // appropriate type to contain the value of the attribute.
  155.  
  156. - (EOParameterDirection)parameterDirection;
  157.     // For Attributes that are stored procedure arguments
  158.  
  159. - (NSDictionary *)userInfo;
  160.     // Returns a dictionary of user data. You can use this to store any
  161.     // auxiliary information.
  162. @end
  163.  
  164.  
  165. @interface EOAttribute(EOAttributeEditing)
  166.  
  167. - (NSException *)validateName:(NSString *)name;
  168.  
  169. - (void)setName:(NSString *)name;
  170.     // Sets the attribute's name.  Returns YES if successful, NO if name is
  171.     // already in use by another attribute or relationship of the same entity.
  172.  
  173. - (void)setReadOnly:(BOOL)yn;
  174.     // Sets whether the value of the attribute can be modified.
  175.  
  176. // The following two methods are closely related. Only one can be set
  177. // at any given time.  Invoking either of these methods causes the other
  178. // value to be set to nil.
  179. - (void)setColumnName:(NSString *)columnName;
  180.     // Sets the name to a string which is the actual name of a column in
  181.     // database.  This method will cause the definition value of this 
  182.     // attribute to be set to nil.
  183.  
  184. - (void)setDefinition:(NSString *)definition;
  185.     // Sets the definition of the attribute. This method will cause the value
  186.     // for columnName to be set to nil. The attribute's entity must have
  187.     // been set by adding the attribute to an entity. This method will not
  188.     // function correctly if the attribute's entity has not been set.
  189.  
  190. - (void)setExternalType:(NSString *)type;
  191.     // Sets the type as recognized by the database server.
  192.  
  193. - (void)setValueType:(NSString *)type;
  194.     // Sets the format for custom-value types, such as "TIFF" or "RTF".
  195.  
  196. - (void)setValueClassName:(NSString *)name;
  197.     // Sets the class name for values of this attribute. If values are
  198.     // instances of NSImage, you would send:
  199.     //     [myAttribute setValueClassName:@"NSImage"];
  200.  
  201. - (void)setWidth:(unsigned)length;
  202.     // This field indicates the maximum amount of bytes the value may contain.
  203.     // Adaptors may use this information to allocate space for fetch buffers.
  204.  
  205. - (void)setPrecision:(unsigned)precision;
  206.     // For attributes with a value class of NSNumber or NSDecimalNumber, sets
  207.     // the precision of the database representation.
  208.     // Will raise if called for attributes that have a value class other than
  209.     // NSNumber or NSDecimalNumber.
  210.  
  211. - (void)setScale:(int)scale;
  212.     // For attributes with a value class of NSDecimalNumber, the scale
  213.     // of the database representation (can be negative).
  214.     // Will raise if called for attributes that have a value class other than
  215.     // NSNumber or NSDecimalNumber.
  216.  
  217. - (void)setAllowsNull:(BOOL)allowsNull;
  218.     // The field indicates whether or not the attribute can have a nil value.
  219.     // if the attribute maps directly to a column in the database it also
  220.     // is used to determine whether the database column can have a NULL value.        
  221.  
  222. // The strings supplied to the two following methods are used to generate
  223. // the attribute's expression value for insert, update and select statements.
  224. // In the read format string, %P is replaced by the attribute's external name; in
  225. // the write format string, %V is replaced by its value. The read format string
  226. // is used whenever the attribute is referenced in a select list or qualifier.
  227. // The write format string is is used whenever a value is used in an insert or
  228. // update statement.
  229.  
  230. - (void)setWriteFormat:(NSString *)string;
  231.     // Supplies a string used to format the value in update expressions.
  232.  
  233. - (void)setReadFormat:(NSString *)string;
  234.     // Supplies a string used to format the value in select expressions.
  235.  
  236. - (void)setParameterDirection:(EOParameterDirection)parameterDirection;
  237.     // Set the direction for Stored Procedure Arguments
  238.  
  239. - (void)setUserInfo:(NSDictionary *)dictionary;
  240.     // Sets the dictionary of auxiliary data, which your application can use
  241.     // for whatever it needs.
  242.  
  243. @end
  244.  
  245. @interface EOAttribute(EOModelBeautifier)
  246. - (void)beautifyName;
  247.     // Make the name conform to the Next naming style
  248.     // NAME -> name, FIRST_NAME -> firstName
  249. @end
  250.  
  251. @interface EOAttribute (NSCalendarDateSupport)
  252. - (NSTimeZone *)serverTimeZone;
  253.     // Set/return the implicit time zone of the dates provided by the database
  254.     // server.
  255. @end
  256.  
  257. @interface EOAttribute(NSCalendarDateSupportEditing)
  258. - (void)setServerTimeZone: (NSTimeZone *)tz;
  259. @end
  260.  
  261.  
  262. // This category is designed for use by adaptors. Clients of the model should not need
  263. // to use these methods.
  264. @interface EOAttribute (EOAttributeValueCreation)
  265.  
  266. - (id)newValueForBytes:(const void *)bytes length:(int)length;
  267.     // Called by the adaptor during value creation while fetching from the database.
  268.     // This method will generate an NSData or custom class value.
  269.     // For efficiency reasons, the caller is responsible for releasing the return value.
  270.  
  271. - (id)newValueForBytes:(const void *)bytes length:(int)length encoding:(NSStringEncoding)encoding;
  272.     // Called by the adaptor during value creation while fetching from the database.
  273.     // This method will generate an NSString or custom class value.
  274.     // For efficiency reasons, the caller is responsible for releasing the return value.
  275.  
  276. - (NSCalendarDate *)newDateForYear:(int)year month:(unsigned)month day:(unsigned)day hour:(unsigned)hour minute:(unsigned)minute second:(unsigned)second millisecond:(unsigned)millisecond timezone:(NSTimeZone *)timezone zone:(NSZone *)zone;
  277.     // Used by AdaptorChannel subclasses to create a calendar date object
  278.     // to return in an adaptor row.
  279.     // For efficiency reasons, the caller is responsible for releasing the return value.
  280.  
  281. - (NSString *)valueFactoryMethodName;
  282.     // Returns the name of the of the factory method used for creating a custom class value.
  283.  
  284. - (SEL)valueFactoryMethod;
  285.     // Returns the factory method invoked by the attribute when creating an
  286.     // attribute value that is of a custom classs. This return value of this method is
  287.     // derived from the attribute's valueFactoryMethodName. If that name does not map
  288.     // to a valid selector in the Obj-C runtime, nil is returned.
  289.  
  290. - (id)adaptorValueByConvertingAttributeValue:(id)value;
  291.     // Checks the type of value to make sure it is one of the following primitive
  292.     // adaptor types. If value is different, the method returned by the
  293.     // primitiveValueMethod on this attribute is invoked to convert the type into
  294.     // one of the following: NSString, NSData, NSNumber, or NSDate.
  295.  
  296. - (NSString *)adaptorValueConversionMethodName;
  297.     // Returns the name of the method used to convert a custom class into one of the
  298.     // primitive types that the adaptor knows how to manipulate.
  299.  
  300. - (SEL)adaptorValueConversionMethod;
  301.     // Returns the method used to convert a custom class into one of the primitive
  302.     // types that the adaptor knows how to manipulate. This return value of this
  303.     // method is derived from the attribute's adaptorValueConversionMethodName. If
  304.     // that name does not map to a valid selector in the Obj-C runtime, nil is returned.
  305.  
  306. - (EOAdaptorValueType)adaptorValueType;
  307.     // Returns a value indicating which type should be fetched from the database.
  308.  
  309. - (EOFactoryMethodArgumentType)factoryMethodArgumentType;
  310.     // The valueFactoryMethod can be one of three arguments: NSData, NSString,
  311.     // or raw bytes. This enum indicates the type of argument that should
  312.     // be passed to the valueFactoryMethod.    
  313. @end
  314.  
  315. @interface EOAttribute(EOAttributeValueCreationEditing)
  316. - (void)setValueFactoryMethodName:(NSString *)factoryMethodName;
  317.     // Sets the value factory method name. This should be a class method that
  318.     // returns an autoreleased object.
  319.  
  320. - (void)setAdaptorValueConversionMethodName:(NSString *)conversionMethodName;
  321.     // Sets the adaptorValueConversionMethod. This method should return a an
  322.     // autoreleased object.
  323.  
  324. - (void)setFactoryMethodArgumentType:(EOFactoryMethodArgumentType)argumentType;
  325.     // Sets the factoryMethodArgumentType;
  326. @end
  327.  
  328. @interface EOAttribute(EOAttributeValueMapping)
  329. - (NSException *)validateValue:(id *)valueP;
  330.     // Attempts to convert value to type specified in attribute and tests other
  331.     // attribute validation constraints (e.g. allowsNull, width, etc).
  332.     // Returns nil on success, exception otherwise.
  333.     // If any coercion was performed, the converted value is assigned to *valueP.
  334. @end
  335.  
  336. @interface NSObject (EOCustomClassArchiving)
  337. + objectWithArchiveData:(NSData *)data;
  338.     // This is the default value factory method when creating custom values.
  339. - (NSData *)archiveData;
  340.     // This is the default value conversion method when saving default values.
  341. @end
  342.