home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOEntity.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  12.8 KB  |  352 lines
  1. // EOEntity.h
  2. // Copyright (c) 1994, NeXT Software, Inc.  All rights reserved. 
  3.  
  4. #import <EOControl/EOControl.h>
  5. #import <EOAccess/EOPropertyListEncoding.h>
  6. #import <EOAccess/EODefines.h>
  7.  
  8.  
  9. @class EOAttribute;
  10. @class EOEntity;
  11. @class EORelationship;
  12. @class EOModel;
  13. @class EOQualifier;
  14. @class EOStoredProcedure;
  15.  
  16. // An EOEntity describes a table, file or collection in a database, and
  17. // associates an internal name with an external name by which the table is
  18. // known to the database.  An entity maintains an array of attributes and
  19. // another array of relationships.
  20. //
  21. // An EOEntity is associated with a specific class whose instances are used
  22. // to represent records (rows) from the database in applications using layers
  23. // at or above the database layer of the Enterprise Objects Framework.  If an
  24. // EOEntity doesn't have a specific class associated with it, instances of
  25. // EOGenericRecord are created.
  26.  
  27.  
  28. @interface EOEntity:NSObject <EOPropertyListEncoding>
  29. {
  30.     NSString *_name;
  31.     NSDictionary *_userInfo;
  32.     EOModel *_model;
  33.     NSString *_externalName;
  34.     NSString *_externalQuery;
  35.     EOQualifier *_restrictingQualifier;
  36.     NSMutableArray *_attributes;
  37.     NSMutableArray *_relationships;
  38.     NSMutableDictionary *_storedProcedures;
  39.     NSString *_className;
  40.     NSMutableArray *_classProperties;
  41.     NSMutableArray *_primaryKeyAttributes;
  42.     NSMutableArray *_attributesUsedForLocking;
  43.     NSMutableArray *_subEntities;
  44.     EOEntity *_parent;
  45.  
  46.     NSArray *_classPropertyNames;
  47.     NSArray *_primaryKeyAttributeNames;
  48.     NSArray *_classPropertyAttributeNames;
  49.     NSArray *_classPropertyToOneRelationshipNames;
  50.     NSArray *_classPropertyToManyRelationshipNames;
  51.     NSMutableArray *_attributesToFetch;
  52.     NSMutableArray *_dbSnapshotKeys;
  53.     NSMutableArray *_attributesToSave;
  54.     NSMutableArray *_propertiesToFault;
  55.     id _propertyDictionaryInitializer;
  56.     id _primaryKeyDictionaryInitializer;
  57.     id _snapshotDictionaryInitializer;
  58.     id _adaptorDictionaryInitializer;
  59.     id _snapshotToAdaptorRowSubsetMapping;
  60.     NSMutableDictionary *_flattenedAttNameToSnapshotKeyMapping;
  61.     EOClassDescription *_classDescription;
  62.     NSMutableArray *_hiddenRelationships;
  63.     unsigned int _batchCount;
  64.     Class _classForInstances;
  65.     
  66.     struct {
  67.         unsigned int attributesIsLazy:1;
  68.         unsigned int relationshipsIsLazy:1;
  69.         unsigned int classPropertiesIsLazy:1;
  70.         unsigned int primaryKeyAttributesIsLazy:1;
  71.         unsigned int attributesUsedForLockingIsLazy:1;
  72.             
  73.     unsigned int isReadOnly:1;
  74.         unsigned int isAbstractEntity:1;
  75.         unsigned int updating:1;
  76.  
  77.         unsigned int useBatchFaulting:1;
  78.  
  79.         unsigned int extraRefCount:23;
  80.     } _flags;
  81. }
  82.  
  83. - (NSString *)name;
  84.     // Returns the internal name of the entity.
  85.  
  86. - (EOModel *)model;
  87.     // Returns the model that owns the entity.
  88.  
  89. - (NSString *)externalName;
  90.     // Returns the name of the entity as understood by the database server.
  91.  
  92. - (NSString *)externalQuery;
  93.     // Returns a query statement used for selecting rows from the entity.  May
  94.     // be nil.
  95.  
  96. - (EOQualifier *)restrictingQualifier;
  97.     // Returns the restricting qualifier used for restrict all queries made
  98.     // against this entity. The restricting qualifier can be used to make an
  99.     // entity map to a subset of the rows in a table.
  100.  
  101. - (BOOL)isReadOnly;
  102.     // Returns YES if the entity can't be modified, NO if it can.
  103.  
  104. - (NSString *)className; 
  105.     // The name of the class that is bound to the entity.  When a row is
  106.     // fetched for the entity by a database-level object, it's returned as an
  107.     // instance of this class.
  108.  
  109. - (EOQualifier *)qualifierForPrimaryKey:(NSDictionary *)row;
  110.     // Return a qualifier to fetch an instance of this entity with
  111.     // the primary key extracted from the row
  112.  
  113. - (BOOL)isQualifierForPrimaryKey:(EOQualifier *)qualifier;
  114.     // Returns yes if qualifier describes primary key and nothing but the
  115.     // primary key.
  116.  
  117. - (EOAttribute *)attributeNamed: (NSString *)attributeName;
  118.     // Returns the attribute with the given name.
  119.  
  120. - (EOAttribute *)anyAttributeNamed:(NSString *)relationshipName;
  121.     // Returns the user-created attribute with the given name, if none
  122.     // exists, this method looks through the "hidden" attributes created
  123.     // by EOF for one with the given name. If none is found, nil is returned.
  124.     // The hidden attributes are used for such things as primary keys on
  125.     // target entities of flattened attributes.
  126.  
  127. - (NSArray *)attributes;
  128.     // Returns all of the entity's attributes.
  129.  
  130. - (EORelationship *)relationshipNamed: (NSString *)relationshipName;
  131.     // Returns the relationship with the given name.
  132.  
  133. - (EORelationship *)anyRelationshipNamed:(NSString *)relationshipName;
  134.     // Returns the user created relationship with the given name, if none
  135.     // exists, this method looks through the "hidden" relationships created
  136.     // by EOF for one with the given name. If none is found, nil is returned.
  137.  
  138. - (NSArray *)relationships;
  139.     // Returns all of the entity's relationships.
  140.  
  141. - (NSArray *)classProperties;
  142.     // Returns an array containing the properties that are bound to the
  143.     // entity's class (so that instances of the class will be passed values
  144.     // corresponding to those properties).  This is a subset of the entity's
  145.     // attributes and relationships.
  146.  
  147. - (NSArray *)classPropertyNames;
  148.     // An array containing the names of all the properties returned by
  149.     // -classProperties.
  150.  
  151. - (NSArray *)primaryKeyAttributes;
  152.     // Returns an array containing the attributes that make up the primary
  153.     // key for the entity.
  154.  
  155. - (NSArray *)primaryKeyAttributeNames;
  156.     // Returns an array containing the names of the attributes returned by
  157.     // -primaryKeyAttributes.
  158.  
  159. - (NSArray *)attributesUsedForLocking;
  160.     // Returns an array containing the properties whose values must not be
  161.     // different from a snapshot any time a row is updated (with an update
  162.     // strategy other than EOUpdateWithNoLocking).
  163.  
  164. - (NSDictionary *)primaryKeyForRow:(NSDictionary *)row;
  165.     // Returns the primary key in dictionary form for a row belonging to the
  166.     // entity.
  167.  
  168. - (BOOL)isValidAttributeUsedForLocking:(EOAttribute *)anAttribute;
  169.     // Returns NO if the attribute isn't an EOAttribute, if the EOAttribute
  170.     // doesn't belong to this entity, or if the EOAttribute is derived.
  171.     // Otherwise returns YES.
  172.  
  173. - (BOOL)isValidPrimaryKeyAttribute: (EOAttribute *)anAttribute;
  174.     // Returns NO if the attribute isn't an EOAttribute, if the EOAttribute
  175.     // doesn't belong to this entity, or if the EOAttribute is derived.
  176.     // Otherwise returns YES.
  177.  
  178. - (BOOL)isPrimaryKeyValidInObject:(id)object;
  179.     // Returns YES if every key attribute is present in the object and has
  180.     // a non-nil and non-EONULL value. Returns NO otherwise. This method
  181.     // uses the key-value coding protocol so a dictionary may be substituted
  182.     // for the actual object.
  183.  
  184. - (BOOL)isValidClassProperty:aProp;
  185.     // Returns NO if either the attribute isn't an EOAttribute or
  186.     // EORelationship, or, if the property doesn't belong to this entity.
  187.     // Otherwise returns YES.
  188.  
  189. - (NSDictionary *)userInfo;
  190.     // Returns a dictionary of user data. You can use this to store any
  191.     // auxiliary information.
  192.  
  193. - (NSArray *)subEntities;
  194.     // Returns the entities which inherit from this entity.
  195.  
  196. - (EOEntity *)parentEntity;
  197.     // Returns the entity that this entity inherits from.
  198.  
  199. - (BOOL)isAbstractEntity;
  200.     // Indicates whether the objects map directly to this entity.
  201.  
  202. - (EOGlobalID *)globalIDForRow:(NSDictionary *)row;
  203.     // Constructs a globalID from a row for this entity.
  204.  
  205. - (NSDictionary *)primaryKeyForGlobalID:(EOGlobalID *)gid;
  206.     // Returns the primary key for the object identified by the global ID.    
  207.  
  208. - (unsigned int)maxNumberOfInstancesToBatchFetch;
  209.     // Returns the max number of EOFaults from this entity to fire at one time.
  210.  
  211. @end
  212.  
  213.  
  214. @interface EOEntity(EOEntityEditing)
  215.  
  216. - (BOOL)setClassProperties: (NSArray *)properties;
  217.     // Sets the entity's class properties to EOAttributes and EORelationships
  218.     // in properties.  Returns YES on success, NO if any of the objects in the
  219.     // array don't return YES to isValidClassProperty:.
  220.  
  221. - (BOOL)setPrimaryKeyAttributes: (NSArray *)keys;
  222.     // Sets the primary key attributes to the attributes in keys.  Returns YES
  223.     // on success, or NO if any object in the array don't return YES to
  224.     // isValidPrimaryKeyAttribute:.
  225.  
  226. - (BOOL)setAttributesUsedForLocking: (NSArray *)attributes;
  227.     // Takes an array of EOAttributes.  Fails if any of the objects in the
  228.     // array don't return YES to isValidAttributeUsedForLocking:.
  229.  
  230. - (NSException *)validateName:(NSString *)name;
  231.     // Returns error description string if name is not a legal entity name
  232.     // and nil otherwise.
  233.  
  234. - (void)setName:(NSString *)name;
  235.     // Sets the entity's name
  236.  
  237. - (void)setExternalName:(NSString *)name;
  238.     // Sets the name of the entity as understood by the database server.
  239.  
  240. - (void)setExternalQuery:(NSString *)query;
  241.     // Sets the query statement used for selecting rows from the entity.
  242.  
  243. - (void)setRestrictingQualifier:(EOQualifier *)qualifier;
  244.     // Sets the restricting qualifier used for restrict all queries made
  245.     // against this entity. The restricting qualifier can be used to make an
  246.     // entity map to a subset of the rows in a table.
  247.  
  248. - (void)setReadOnly:(BOOL)yn;
  249.     // Sets whether the entity can be modified.
  250.  
  251. - (void)addAttribute:(EOAttribute *)attribute;
  252.     // Adds attribute to the entity.
  253.  
  254. - (void)removeAttribute:(EOAttribute *)attribute;
  255.     // Removes the attribute.
  256.  
  257. - (void)addRelationship:(EORelationship *)relationship;
  258.     // Adds relationship to the entity.
  259.  
  260. - (void)removeRelationship:(EORelationship *)relationship;
  261.     // Removes the relationship.
  262.  
  263. - (void)setClassName:(NSString *)name;
  264.     // Sets the class name.
  265.  
  266. - (void)setUserInfo:(NSDictionary *)dictionary;
  267.     // Sets the dictionary of auxiliary data, which your application can use
  268.     // for whatever it needs.
  269.  
  270. - (void)addSubEntity:(EOEntity *)child;
  271.     // Causes the child entity to "inherit" from this entity. This is the first
  272.     // step in setting up an inheritance hierarchy between entities.
  273.  
  274. - (void)removeSubEntity:(EOEntity *)child;
  275.     // Removes the child from this entity's list of subEntities.
  276.  
  277. - (void)setIsAbstractEntity:(BOOL)f;
  278.     // Sets whether the objects map directly to this entity.
  279.  
  280. - (void)setMaxNumberOfInstancesToBatchFetch:(unsigned int)size;
  281.     // Sets the max number of EOFaults from this entity to fire at one time.
  282.  
  283. @end
  284.  
  285. @interface EOEntity(EOModelReferentialIntegrity)
  286.  
  287. - (BOOL)referencesProperty:property;
  288.     // True if any of the entity's attributes or relationships reference
  289.     // property.
  290.  
  291. - (NSArray *)externalModelsReferenced;
  292.     // returns a list of external models referenced by this entity
  293.  
  294. @end
  295.  
  296. @interface EOEntity(EOModelBeautifier)
  297. - (void)beautifyName;
  298.     // Make the entity name and all of its components conform
  299.     // to the Next naming style
  300.     // NAME -> name, FIRST_NAME -> firstName
  301. @end
  302.  
  303.  
  304. EOACCESS_EXTERN NSString *EOFetchAllProcedureOperation;
  305. EOACCESS_EXTERN NSString *EOFetchWithPrimaryKeyProcedureOperation;
  306. EOACCESS_EXTERN NSString *EOInsertProcedureOperation;
  307. EOACCESS_EXTERN NSString *EODeleteProcedureOperation;
  308. EOACCESS_EXTERN NSString *EONextPrimaryKeyProcedureOperation;
  309.  
  310. @interface EOEntity(EOStoredProcedures)
  311. - (EOStoredProcedure *)storedProcedureForOperation:(NSString *)operation;
  312. - (void)setStoredProcedure:(EOStoredProcedure *)storedProcedure forOperation:(NSString *)operation;
  313. @end
  314.  
  315. @interface EOEntity(EOPrimaryKeyGeneration)
  316. - (NSString *)primaryKeyRootName;
  317.     // If this entity inherits from another entity, the method is passed to it's parent.
  318.     // The top level entity returns the externalName if it has one or the entity name
  319.     // otherwise.
  320. @end
  321.  
  322. @interface EOEntity(EOEntityClassDescription)
  323. - (EOClassDescription *)classDescriptionForInstances;
  324. @end
  325.  
  326. // Entities register themselves as class descriptions for
  327. // their classes, thereby dynamically extending their behavior.
  328. @interface EOEntityClassDescription : EOClassDescription
  329. {
  330.     EOEntity *_entity;
  331. }
  332. - initWithEntity:(EOEntity *)entity;
  333. - (EOEntity *)entity;
  334. @end
  335.  
  336. @interface NSString(EODatabaseNameConversion)
  337. + (NSString *)nameForExternalName:(NSString *)externalName
  338.                 separatorString:(NSString *)separatorString initialCaps:(BOOL)initialCaps;
  339.     // Name beautification uses this to convert database names to
  340.     // nicer looking names
  341.     // NAME -> name, FIRST_NAME -> firstName, MY_ENTITY -> MyEntity
  342.  
  343. + (NSString *)externalNameForInternalName:(NSString *)internalName
  344.                  separatorString:(NSString *)separatorString useAllCaps:(BOOL)allCaps;
  345.     // Database-style name from ObjC-style names.
  346.     // With separatorString:@"_" and useAllCaps:YES :
  347.     //   name -> NAME, firstName -> FIRST_NAME, MyEntity -> MY_ENTITY
  348.     // With separatorString:@"_" and useAllCaps:NO :
  349.     //   name -> name, firstName -> first_name, MyEntity -> my_entity
  350.  
  351. @end
  352.