home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / 3.3Headers / eoaccess / EOAdaptor.h < prev    next >
Encoding:
Text File  |  1994-05-17  |  7.2 KB  |  172 lines
  1. // EOAdaptor.h 
  2. // Copyright (c) 1994, NeXT Computer, Inc.  All rights reserved.
  3.  
  4. #import <foundation/NSArray.h>
  5. #import <foundation/NSData.h>
  6. #import <foundation/NSDictionary.h>
  7. #import <foundation/NSObject.h>
  8. #import <foundation/NSString.h>
  9.  
  10. @class EOModel;
  11. @class EOAttribute;
  12. @class EOAdaptorContext;
  13. @class EOAdaptorChannel;
  14.  
  15.  
  16. // An EOAdaptor represents a single connection to a database server. It's
  17. // responsible for keeping login and model information, performing server-
  18. // specific formatting of SQL expressions, and reporting errors. The EOAdaptor
  19. // class also defines the methods that find and load adaptor bundles.
  20. //
  21. // An EOAdaptor can manage several EOAdaptorContexts, each of which represents
  22. // a transaction scope on the database server. An EOAdaptorContext can in
  23. // turn manage several EOAdaptorChannels, each of which handles actual access
  24. // to the data on the server. An EOAdaptor by default has no
  25. // EOAdaptorContexts; to create a new EOAdaptorContext, send your EOAdaptor a
  26. // -createAdaptorContext message. See EOAdaptorContext.h and
  27. // EOAdaptorChannel.h for more information.
  28. //
  29. // Not all adaptors support multiple contexts.
  30. //
  31. // An EOAdaptorContext retains its adaptor when created and an
  32. // EOAdaptorChannel retains its context, so when you create an adaptor,
  33. // adaptor context, and adaptor channel, you need only retain the channel for
  34. // all objects to remain valid.
  35. //
  36. // CONNECTING TO THE SERVER
  37. //
  38. // An EOAdaptor uses a connection dictionary to connect to the database
  39. // server.  The keys of this dictionary identify the information the server
  40. // expects, and the values of those keys are the values that the adaptor will
  41. // try when connecting.  For ORACLE databases the required keys are
  42. // hostMachine, serverId, userName, and password.  For Sybase databases the
  43. // required keys are hostName, databaseName, userName, and password.
  44. //
  45. // A connection to the database server isn't actually formed until an adaptor
  46. // channel is opened.  When you ask an adaptor to validate its connection
  47. // dictionary it only confirms with the server that it will accept the values
  48. // in the dictionary when a connection is requested.
  49.  
  50.  
  51. @interface EOAdaptor:NSObject
  52. {
  53.     NSString *_name;
  54.     EOModel *_model;
  55.     NSDictionary *_connectionDictionary;
  56.     id _delegate;
  57.     struct {
  58.     unsigned willReportError:1;
  59.     unsigned int _RESERVED:31;
  60.     } _delegateRespondsTo;
  61. }
  62.  
  63. + adaptorWithName:(NSString *)name;
  64.     // Searches the app's main bundle, ~/Library/Adaptors,
  65.     // /LocalLibrary/Adaptors, and /NextLibrary/Adaptors (in that order) for
  66.     // the first adaptor whose base filename matches name.  It then loads
  67.     // that adaptor if needed and inits it.
  68.  
  69. + adaptorWithModel:(EOModel *)model;
  70.     // The EOAdaptor implementation of this method extracts the adaptor name
  71.     // from the model, sends +adaptorWithName: to self, and assigns to the
  72.     // adaptor the model and the connection dictionary of that model.
  73.  
  74. - initWithName:(NSString *)name;
  75.     // This is the designated initializer for adaptors to be overridden by
  76.     // subclasses.  You MUST use +adaptorWithName: or +adaptorWithModel: to
  77.     // create a new adaptor.
  78.  
  79. - (NSString *)name;
  80.     // Returns the base filename for the bundle the adaptor came from.
  81.  
  82. - (void)setModel:(EOModel *)model;
  83.     // Sets the model used by the adaptor. The model may also provide a
  84.     // default connection dictionary.
  85.  
  86. - (EOModel *)model;
  87.     // Returns the model that describes the adaptor's database.  This may be
  88.     // nil; an adaptor must have a model to work with higher layers of the
  89.     // Framework, though.
  90.  
  91. - (EOAdaptorContext *)createAdaptorContext;
  92.     // Returns a new EOAdaptorContext, or nil if a new context cannot be
  93.     // created.  EOAdaptors by default have no contexts at all.  The newly
  94.     // created context retains its adaptor.
  95.  
  96. - (Class)expressionClass;
  97.     // Returns the subclass of EOSQLExpression used by this adaptor for query
  98.     // language expressions.  You directly invoke this method, but an
  99.     // adaptor subclass must properly implement this method.
  100.  
  101. - formatAttribute:(EOAttribute *)attribute;
  102.     // Returns an expression formatting the attribute for a SQL select
  103.     // statement. You never directly invoke this method, but an adaptor
  104.     // subclass must properly implement this method.
  105.  
  106. - formatValue:value forAttribute:(EOAttribute *)attribute;
  107.     // Returns an expression formatting the value for the given attribute for
  108.     // a SQL select statement. You never directly invoke this method, but an
  109.     // adaptor subclass must properly implement this method.
  110.  
  111. - (BOOL)isValidQualifierType:(NSString *)typeName;
  112.     // Returns YES if an attribute of type typeName can be used in a
  113.     // qualifier, otherwise returns NO.  typeName is the name of a type as
  114.     // determined by the database server, such as a Sybase "varchar" or an
  115.     // Oracle "NUMBER".
  116.  
  117. - (BOOL)hasOpenChannels;
  118.     // Returns YES if the adaptor has any open channels, NO otherwise. See
  119.     // -openChannel in EOAdaptorChannel.h.
  120.  
  121. - (BOOL)runLoginPanelAndValidateConnectionDictionary;
  122.     // Runs a login panel until the user enters a valid login or clicks
  123.     // Cancel.  Valid login information entered in the panel is stored in the
  124.     // adaptor's connection dictionary.  Returns YES if the connection
  125.     // dictionary is validated, NO if the user cancels the login panel.
  126.  
  127. - (NSDictionary *)runLoginPanel;
  128.     // This method runs the adaptor's login panel but does not affect the
  129.     // adaptor's connection dictionary.  The returned dictionary contains the
  130.     // values of the fields entered by the user (which aren't validated), or
  131.     // is nil if the user clicked cancel.
  132.  
  133. - (BOOL)hasValidConnectionDictionary;
  134.     // Returns YES if the adaptor can connect with the current connection
  135.     // dictionary, NO otherwise. An actual connection is made when the first
  136.     // adaptor channel is sent an -openChannel message.
  137.  
  138. - (NSDictionary *)connectionDictionary;
  139.     // Returns the adaptor's connection dictionary.
  140.  
  141. - (void)setConnectionDictionary:(NSDictionary *)dictionary;
  142.     // Gives the adaptor a dictionary with information about how and where to
  143.     // open connections to a database server; see CONNECTING TO THE SERVER for
  144.     // more information.  Raises NSInvalidArgumentException if there are open
  145.     // channels--you can't reset the connection information while the adaptor
  146.     // is connected.
  147.  
  148. - delegate;
  149. - (void)setDelegate:delegate;
  150.     // These methods return/set the delegate of the adaptor context.
  151.  
  152. - (void)reportError:(NSString *)error;
  153.     // The adaptor components send this message to their EOAdaptor to have
  154.     // errors reported to the user.  The EOAdaptor first checks its delegate
  155.     // with -adaptor:willReportError:.  If the delegate returns NO then
  156.     // EOAdaptor does nothing.  If the delegate returns YES or is not present,
  157.     // the EOAdaptor tries to open an alert panel, or if there is no
  158.     // Application instance, it logs the error to the console.
  159.  
  160. @end
  161.  
  162.  
  163. @interface NSObject(EOAdaptorDelegate)
  164.  
  165. - (BOOL)adaptor:(EOAdaptor *)adaptor willReportError:(NSString *)error;
  166.     // An adaptor sends this message to its delegate when an error has
  167.     // occurred.  If the delegate returns NO, the adaptor doesn't open an
  168.     // alert panel (or log the error to the console if it isn't in an
  169.     // application).
  170.  
  171. @end
  172.