Writing a Database Adapter
Database adapters for Induction are designed to be easy to write. Adapters are packaged as bundles, with their primary class implementing the
DBAdapter protocol. Here is a rundown of the roles and responsibilities of the adapter protocols (note, these interfaces are not final, and subject to evolve and change as the project matures):
Specifies a URL scheme, validates connection URLs and creates connections.
@protocol DBAdapter <NSObject> + (NSString *)primaryURLScheme; + (BOOL)canConnectWithURL:(NSURL *)url; + (id <DBConnection>)connectionWithURL:(NSURL *)url error:(NSError **)error; @end
Initializes and manages a connection client, most often a C interface to a system library.
@protocol DBConnection <NSObject> @property (nonatomic, readonly) NSURL *url; @property (nonatomic, readonly) NSArray *databases; - (id)initWithURL:(NSURL *)url; - (BOOL)open; - (BOOL)close; - (BOOL)reset; @end
Represents an organized collection of data, most often corresponding to a database in the target platform.
It's principle responsibility is to populate the source list on the left side of the connection window.
@protocol DBDatabase <NSObject> @property (nonatomic, readonly) id <DBConnection> connection; @property (nonatomic, readonly) NSOrderedSet *dataSourceGroupNames; - (NSArray *)dataSourcesForGroupNamed:(NSString *)groupName; @end
Following the interpretation used by Yahoo YUI, this is "an abstract representation of a live set of data that presents a common predictable API for other objects to interact with." Examples of this include SQL tables, MongoDB collections, collections of Redis keys according to their type, etc.
Data sources have their responsibilities split across three different protocols, representing the "Explore", "Query", and "Visualize" features of the application. By conforming to its respective protocol, the adapter makes itself available for that feature.
@protocol DBDataSource <NSObject> - (NSUInteger)numberOfRecords; @end
@protocol DBExplorableDataSource <NSObject> - (id <DBResultSet>)resultSetForRecordsAtIndexes:(NSIndexSet *)indexes error:(NSError **)error; @end
@protocol DBQueryableDataSource <NSObject> - (id <DBResultSet>)resultSetForQuery:(NSString *)query error:(NSError **)error; @end
@protocol DBVisualizableDataSource <NSObject> - (id <DBResultSet>)resultSetForDimension:(NSExpression *)dimension measures:(NSArray *)measures error:(NSError **)error; @end
Perhaps the most significant part of an adapter, this object represents a result set of data, and drives the display of information in tables and outlines. Whereas a SQL table is a
DBDataSource, the first page of 1000 results would be a
DBResultSet, and it is the result set that is displayed.
@protocol DBResultSet <NSObject> - (NSUInteger)numberOfRecords; - (NSArray *)recordsAtIndexes:(NSIndexSet *)indexes; - (NSUInteger)numberOfFields; - (NSString *)identifierForTableColumnAtIndex:(NSUInteger)index; @optional - (DBValueType)valueTypeForTableColumnAtIndex:(NSUInteger)index; - (NSCell *)dataCellForTableColumnAtIndex:(NSUInteger)index; - (NSSortDescriptor *)sortDescriptorPrototypeForTableColumnAtIndex:(NSUInteger)index; @end
Records correspond to rows, or individual documents in the result set, and are represented by an object conforming to the
DBResultSet fields correspond to columns or values, which are strings that are passed to
DBRecord objects using
Adapters to graph or document databases can optionally specify the child records, which can be expanded using disclosure indicators in an outline view.
@protocol DBRecord <NSObject> - (id)valueForKey:(NSString *)key; @optional @property (nonatomic, readonly) NSArray *children; @end