home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOAdaptor.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  11.8 KB  |  252 lines
  1. // EOAdaptor.h 
  2. // Copyright (c) 1994, NeXT Software, Inc.  All rights reserved.
  3.  
  4. #import <EOControl/EOControl.h>
  5. #import <EOAccess/EODefines.h>
  6.  
  7. @class EOModel;
  8. @class EOEntity;
  9. @class EOAttribute;
  10. @class EOAdaptorContext;
  11. @class EOAdaptorChannel;
  12. @class EOLoginPanel;
  13.  
  14. // Exceptions raised by adaptors when errors occur during DBMS interactions.
  15. EOACCESS_EXTERN NSString *EOGeneralAdaptorException;
  16.  
  17. // An EOAdaptor represents a single connection to a database server. It's
  18. // responsible for keeping login and model information, performing server-
  19. // specific formatting of SQL expressions, and reporting errors. The EOAdaptor
  20. // class also defines the methods that find and load adaptor bundles.
  21. //
  22. // An EOAdaptor can manage several EOAdaptorContexts, each of which represents
  23. // a transaction scope on the database server. An EOAdaptorContext can in
  24. // turn manage several EOAdaptorChannels, each of which handles actual access
  25. // to the data on the server. An EOAdaptor by default has no
  26. // EOAdaptorContexts; to create a new EOAdaptorContext, send your EOAdaptor a
  27. // -createAdaptorContext message. See EOAdaptorContext.h and
  28. // EOAdaptorChannel.h for more information.
  29. //
  30. // Not all adaptors support multiple contexts.
  31. //
  32. // An EOAdaptorContext retains its adaptor when created and an
  33. // EOAdaptorChannel retains its context, so when you create an adaptor,
  34. // adaptor context, and adaptor channel, you need only retain the channel for
  35. // all objects to remain valid.
  36. //
  37. // CONNECTING TO THE SERVER
  38. //
  39. // An EOAdaptor uses a connection dictionary to connect to the database
  40. // server.  The keys of this dictionary identify the information the server
  41. // expects, and the values of those keys are the values that the adaptor will
  42. // try when connecting. For informix the required keys are dbName, userName,
  43. // and password. For ORACLE databases the required keys are hostMachine,
  44. // serverId, userName, and password.  For Sybase databases the required
  45. // keys are hostName, databaseName, userName, and password.
  46. //
  47. // A connection to the database server isn't actually formed until an adaptor
  48. // channel is opened.  When you ask an adaptor to validate its connection
  49. // dictionary it only confirms with the server that it will accept the values
  50. // in the dictionary when a connection is requested.
  51.  
  52.  
  53. @interface EOAdaptor:NSObject
  54. {
  55.     NSString *_name;
  56.     NSDictionary *_connectionDictionary;
  57.     NSStringEncoding _encoding;
  58.     NSMutableArray *_contexts;
  59.     NSString *_expressionClassName;
  60.     Class _expressionClass;
  61.     id _delegate;
  62.     struct {
  63.     unsigned processValue:1;
  64.     unsigned int _RESERVED:31;
  65.     } _delegateRespondsTo;
  66. }
  67.  
  68. + adaptorWithName:(NSString *)name;
  69.     // Searches the app's main bundle, ~/Library/Adaptors,
  70.     // /LocalLibrary/Adaptors, and /NextLibrary/Adaptors (in that order) for
  71.     // the first adaptor whose base filename matches name.  It then loads
  72.     // that adaptor if needed and inits it.
  73.  
  74. + adaptorWithModel:(EOModel *)model;
  75.     // The EOAdaptor implementation of this method extracts the adaptor name
  76.     // from the model, sends +adaptorWithName: to self, and assigns to the
  77.     // adaptor the model and the connection dictionary of that model.
  78.  
  79. + (void)setExpressionClassName:(NSString *)sqlExpressionClassName
  80.      adaptorClassName:(NSString *)adaptorClassName;
  81.     // Overrides the defaultExpressionClass provided by the adaptor. This allows
  82.     // programmers to subclass the SQLExpression class used by the adaptor with
  83.     // subclassing the entire adaptor. The expression class can be reset to the
  84.     // default by passing nil as the sqlExpressionClassName;
  85.  
  86. + (EOLoginPanel *)sharedLoginPanelInstance;
  87.     // For applications (when [NSApp sharedApplication] is non-nil, this will
  88.     // return an instance of the login panel for this adaptor.  The default
  89.     // implementation looks for "LoginPanel.bundle" in the resources for the
  90.     // adaptor framework, loads this bundle, and returns the result of alloc
  91.     // and initing its principalClass.  The framework uses the returned object
  92.     // to implement runLoginPanel and runLoginPanelAndValidateConnectionDictionary.
  93.  
  94. - initWithName:(NSString *)name;
  95.     // This is the designated initializer for adaptors to be overridden by
  96.     // subclasses.  You MUST use +adaptorWithName: or +adaptorWithModel: to
  97.     // create a new adaptor.
  98.  
  99. - (NSString *)name;
  100.     // Returns the base filename for the bundle the adaptor came from.
  101.  
  102. - (EOAdaptorContext *)createAdaptorContext;
  103.     // Returns a new EOAdaptorContext, or nil if a new context cannot be
  104.     // created.  EOAdaptors by default have no contexts at all.  The newly
  105.     // created context retains its adaptor.
  106.  
  107. - (NSArray *)contexts;
  108.  
  109. - (Class)expressionClass;
  110.     // Returns the subclass of EOSQLExpression used by this adaptor for query
  111.     // language expressions. The EOAdaptor superclass provides a default
  112.     // implementation of this method which looks to see if the programmer has
  113.     // set a new sqlExpressionClass for this adaptor type by invoking
  114.     // setExpressionClassName:adaptorClassName: If no class has been set,
  115.     // the defaultExpressionClass method is invoked on the individual adaptor.
  116.  
  117. - (Class)defaultExpressionClass;
  118.     // This method should never be invoked by the programmer. It is implemented
  119.     // by the adaptor subclass and invoked by the framework when determining which
  120.     // sqlExpression class should be used.
  121.  
  122. - (BOOL)isValidQualifierType:(NSString *)typeName model:(EOModel *)model;
  123.     // Returns YES if an attribute of type typeName can be used in a
  124.     // qualifier, otherwise returns NO.  typeName is the name of a type as
  125.     // determined by the database server, such as a Sybase "varchar" or an
  126.     // Oracle "NUMBER".
  127.  
  128. - (BOOL)hasOpenChannels;
  129.     // Returns YES if the adaptor has any open channels, NO otherwise. See
  130.     // -openChannel in EOAdaptorChannel.h.
  131.  
  132. - (void)assertConnectionDictionaryIsValid;
  133.     // Raises an exception if any error occurs. An actual connection is made
  134.     // when the first adaptor channel is sent an -openChannel message.
  135.  
  136. - (NSDictionary *)connectionDictionary;
  137.     // Returns the adaptor's connection dictionary.
  138.  
  139. - (void)setConnectionDictionary:(NSDictionary *)dictionary;
  140.     // Gives the adaptor a dictionary with information about how and where to
  141.     // open connections to a database server; see CONNECTING TO THE SERVER for
  142.     // more information.  Raises NSInvalidArgumentException if there are open
  143.     // channels--you can't reset the connection information while the adaptor
  144.     // is connected.
  145.  
  146. - (BOOL)canServiceModel:(EOModel *)model;
  147.     // Returns YES if this adaptor instance can service access requests
  148.     // for this model, NO otherwise.  Default implementation checks if
  149.     // this model has an identical connection dictionary to the current
  150.     // connectionDicionaries.  Subclasses may want to override to be
  151.     // more permissive of unimportant differences in the connection
  152.     // dictionaries.
  153.  
  154. - (NSStringEncoding)databaseEncoding;
  155.     // Looks in the connection dictionary for an entry entitled
  156.     // "databaseEncoding". If it finds one it returns the corresponding
  157.     // NSStringEncoding value. If it doesn't find one it returns the
  158.     // default encoding. This method can raise if an entry exists in the
  159.     // dictionary that doesn't map to one of the legal NSStringEncoding
  160.     // values. (e.g. if the value is misspelled)
  161.  
  162. - (id)fetchedValueForValue:(id)value attribute:(EOAttribute *)attribute;
  163.     // Called for each value that is inserted or updated so that the adaptor
  164.     // may perform database specific transformations before they are assigned
  165.     // back to the object and snapshots. For example, say the object holds an
  166.     // NSDecimalNumber with value 5.24. The precision and scale of the attribute
  167.     // and corresponding database column is 2 and 1 respectively. When the value
  168.     // gets stored in the database it's value will be truncated to 5.4. At this
  169.     // point, the value in the database is different than the one in the snapshot.
  170.     // In order to avoid the problems that can occur in such situations, this
  171.     // method gives the adaptor a chance to adjust any values that have been sent
  172.     // to the database in a DBMS specific manner before they are placed in the
  173.     // snapshot.
  174.     // Subclassers may override this method as well as the next 4 methods which
  175.     // used to perform the conversion for each of the possible adaptor types.
  176.     // This method doesn't do any conversion of custom classes. Programs that need
  177.     // to process custom classes must implement the processValue:attribute:adaptor:
  178.     // delegate on the adaptor.
  179.  
  180. - (NSString *)fetchedValueForStringValue:(NSString *)value attribute:(EOAttribute *)attribute;
  181.     // Superclass implementation returns value. Adaptors should override to mimic specific
  182.     // DBMS behavior.
  183.  
  184. - (NSNumber *)fetchedValueForNumberValue:(NSNumber *)value attribute:(EOAttribute *)attribute;
  185.     // Superclass implementation returns value. Adaptors should override to mimic specific
  186.     // DBMS behavior.
  187.  
  188. - (NSCalendarDate *)fetchedValueForDateValue:(NSCalendarDate *)value attribute:(EOAttribute *)attribute;
  189.     // Superclass implementation returns value. Adaptors should override to mimic specific
  190.     // DBMS behavior.
  191.  
  192. - (NSData *)fetchedValueForDataValue:(NSData *)value attribute:(EOAttribute *)attribute;
  193.     // Superclass implementation returns value. Adaptors should override to mimic specific
  194.     // DBMS behavior.
  195.  
  196. - delegate;
  197. - (void)setDelegate:delegate;
  198.     // These methods return/set the delegate of the adaptor context.
  199.  
  200. @end
  201.  
  202. @interface EOAdaptor (EOAdaptorLoginPanel)
  203. - (BOOL)runLoginPanelAndValidateConnectionDictionary;
  204.     // Runs a login panel until the user enters a valid login or clicks
  205.     // Cancel.  Valid login information entered in the panel is stored in the
  206.     // adaptor's connection dictionary. Returns YES if the user enters correct
  207.     // connection information and NO otherwise.
  208.  
  209. - (NSDictionary *)runLoginPanel;
  210.     // This method runs the adaptor's login panel but does not affect the
  211.     // adaptor's connection dictionary.  The returned dictionary contains the
  212.     // values of the fields entered by the user (which aren't validated), or
  213.     // is nil if the user clicked cancel.
  214. @end
  215.  
  216. @interface EOAdaptor (EOExternalTypeMapping)
  217. + (NSString *)internalTypeForExternalType:(NSString *)extType model:(EOModel *)model;
  218. + (NSArray *)externalTypesWithModel:(EOModel *)model;
  219. + (void)assignExternalInfoForAttribute:(EOAttribute *)attribute;
  220.     // should convert the columnName and external type based on the
  221.     // internalType, precision, and length info.
  222.     // Default implementation creates columnName from name:
  223.     // e.g. "firstName" -> "FIRST_NAME"
  224.     // Adaptor subclasses should override to assign external types.
  225. + (void)assignExternalInfoForEntity:(EOEntity *)entity;
  226.     // Creates external name based on internal name.  Default implementation
  227.     // will covert name of style "EmpPhoto" to "EMP_PHOTO".
  228.     // This does not recurse over the attributes.
  229. + (void)assignExternalInfoForEntireModel:(EOModel *)model;
  230.     // Recurses through entities and their attributes calling the
  231.     // conversion methods above
  232.  
  233. @end
  234.  
  235. @interface EOLoginPanel : NSObject
  236. - (NSDictionary *)runPanelForAdaptor:(EOAdaptor *)adaptor validate:(BOOL)yn;
  237.     // Adaptor subclasses should implement a subclass that implements
  238.     // this method.  If validate==YES, the panel should call
  239.     // [adaptor setConnectionDictionary:connDict], and return only if
  240.     // [adaptor assertConnectionDictionaryIsValid] does not raise or the user
  241.     // cancels the operation. This method returns a nil dictionary if the user
  242.     // does cancel the operation.
  243. @end
  244.  
  245. @interface EOAdaptor (EOAdaptorDelegation)
  246. - (id)adaptor:(EOAdaptor *)adaptor fetchedValueForValue:(id)value attribute:(EOAttribute *)attribute;
  247.     // Allows the adaptor delegate to handle attribute processing when saving
  248.     // eos to the database. When this method is implemented, it must return the
  249.     // processed value. Returning nil as the new value is OK.
  250. @end
  251.  
  252.