Adun  0.83
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Member Functions | Static Public Member Functions
ULDatabaseInterface Class Reference

#import <ULDatabaseInterface.h>

Collaboration diagram for ULDatabaseInterface:
Collaboration graph
[legend]

List of all members.

Public Member Functions

(NSArray *) - backends
(NSDictionary *) - backendErrors
(BOOL) - addBackend:
(void) - removeBackendForClient:
(id) - backendForClient:
(ULDatabaseClientConnectionState- connectionStateForClient:
(BOOL) - addObject:toSchema:ofClient:error:
(BOOL) - addObjectToFileSystemDatabase:
(BOOL) - addObjectToFileSystemDatabase:updateReferences:
(BOOL) - removeObjectOfClass:withID:fromSchema:ofClient:error:
(BOOL) - removeObjectsOfClass:withIDs:fromSchema:ofClient:error:
(id) - unarchiveObjectWithID:ofClass:fromSchema:ofClient:error:
(id) - unarchiveObjectWithMetadata:error:
(NSArray *) - metadataForObjectsOfClass:inSchema:ofClient:
(id) - metadataForObjectWithID:ofClass:inSchema:ofClient:error:
(NSDictionary *) - metadataForObjectAtIndex:ofClass:inSchema:ofClient:
(BOOL) - updateMetadataForObject:inSchema:ofClient:error:
(BOOL) - updateOutputReferencesForObject:error:
(BOOL) - addOutputReferences:toObjectWithMetadata:error:
(id) - outputReferencesForObjectWithID:ofClass:inSchema:ofClient:error:
(id) - inputReferencesForObjectWithID:ofClass:inSchema:ofClient:error:
(BOOL) - removeOutputReferencesToObjectWithID:ofClass:inSchema:ofClient:error:
(ULSchemaMode- modeForSchema:ofClient:
(NSArray *) - contentTypeInformationForSchema:ofClient:
(NSArray *) - availableClients
(NSArray *) - schemaInformationForClient:
(NSArray *) - clientsForDatabase:
(NSArray *) - clientsConnectedToHost:
(ULFileSystemDatabaseBackend *) - primaryFileSystemBackend
(BOOL) - objectInFileSystemDatabase:
(NSArray *) - findObjectsWithID:ofClass:
(NSArray *) - findObjectsMatchingReference:

Static Public Member Functions

(id) + databaseInterface

Detailed Description

ULDatabaseInterface is a singleton which provides a unified interface to a number of database backends. The individual backends add, remove and retrieve data from a given database as a given user. The object which handles the connection to the database is called a "client". Hence each backend object has an associated "client" instance which it uses to interact with the database. The client instance is identified by a name which also serves to identify the corresponding backend. The client name must be a unique string (in the context of the set of backends handled by the ULDatabaseInterface instance).

A client can also be thought of as a specific instance of a database. Two clients can be connected to the same database but they may not be able to perform the same actions on it. Hence we could write methods like "addObject:toDatabase:usingClient" howver since by specifying a client you already determine a database this is shortend to "addObject:toClient:".

Terminology

Exceptions & Errors

Exceptions are raised in the following circumstances

These are consider avoidable programmatic errors since the correct information is readily available.

Errors result when attempting database operations in the following situations

Users can have either read/write/update permissions to the schema. Without read permissions the following methods will return an error.

Without write permission these methods return an error

You can check the permissions of a schema using modeForSchema:ofClient:

Notifications

ULDatabaseInterface sends notifications in a number of situtations. Notifications are sent on add/remove/update operations so an object which monitors the database's state can react to them e.g. the database browser in the interface.

Todo:

Add handling of corruption notifications

Add metadata based methods e.g. unarchiveObjectWithMetadata:, outputReferencesForObjectWithMetadata: etc.

Automate addition of output references when an object is added. Currently this must be done separately.


Member Function Documentation

- (BOOL) addBackend: (id)  object

Adds the backend object to the backends handled by the receiver. The clientName associated with the backend (as returned by e.g. ULFileSystemDatabaseBackend::clientName()) must not be in use by another backend allready handled by the reciever i.e. not in the array returned by availableClients. If it is this method returns NO. Otherwise the backend is added and this method returns YES. The configuration of the backend is saved by the receiver and when ULDatabaseInterface is next initialised the backend is automatically recreated and added to the availableClients. Posts an ULDatabaseInterfaceDidAddBackendNotification on success.

- (BOOL) addObject: (id)  object
toSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Adds object to schema of the database identified by clientname.

- (BOOL) addObjectToFileSystemDatabase: (id)  object

Adds object to the primary file system database.

- (BOOL) addObjectToFileSystemDatabase: (AdModelObject*)  object
updateReferences: (BOOL)  addRefs 

Adds object to the primary file system database. In addition if addRefs is YES it adds a reference to object to every archived object in the list returned by [object inputReferences]

- (BOOL) addOutputReferences: (NSArray*)  references
toObjectWithMetadata: (NSDictionary*)  metadata
error: (NSError**)  error 

Description forthcoming

- (NSArray*) availableClients

Returns an array containing the names of all the available clients.

- (NSDictionary*) backendErrors

Returns an NSDictionary containing error objects describing problems with the backends. If there are no problems the dictionary is empty. Otherwise the keys are client names and the values error objects describing the problems.

- (id) backendForClient: (NSString*)  clientName

Returns the object which uses the connection clientName

- (NSArray*) backends

Returns an array of all the backends managed by the receiver

- (NSArray *) clientsConnectedToHost: (NSHost*)  host

Returns an array containing the names of the clients that access databases on host Databases are identified by comparing host to the return value of the backends databaseHost metho. If no clients are found that access host this method returns an empty array.

- (NSArray *) clientsForDatabase: (NSString*)  string

Returns an array containing the names of the clients that access the database identified by string. Databases are identified by comparing string to the return value of databaseIdentifier (ULFileSystemDatabaseBackend). If no clients are found that access string this method returns an empty array.

- (ULDatabaseClientConnectionState) connectionStateForClient: (NSString*)  clientName

Returns the connection state of clientName

- (NSArray *) contentTypeInformationForSchema: (NSString*)  schema
ofClient: (NSString*)  clientName 

Returns an array of dictionaries. Each dictionary contains information on a specific type of data contained in schema. Each dictionary has two keys ULObjectDisplayName & ULObjectClassName. The value of the latter is a AdModelObject descendant class name. The former is the display name associated with this class.

+ (id) databaseInterface

Returns the applications databaseInterface object

- (NSArray*) findObjectsMatchingReference: (NSDictionary *)  reference

As findObjectsWithID:ofClass: except extracts the class and identification from reference. reference must contain the same keys as the dictionary returned by reference (AdModelObject).

- (NSArray*) findObjectsWithID: (NSString *)  ident
ofClass: (NSString *)  className 

Searches for objects with idenfication ident and class className in all the schemas of all the currently connected clients. Returns an array containing information on the objects found The information for each object is the dictionary returned by metadataForObjectWithID:ofClass:inSchema:ofClient:error().

- (id) inputReferencesForObjectWithID: (NSString*)  ident
ofClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Description forthcomming

- (NSDictionary *) metadataForObjectAtIndex: (unsigned int)  objectIndex
ofClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName 

Returns a copy of the metadata dictionary of the object at index objectIndex of the array that would be returned by metadataForObjectsOfClass:inSchema:ofClient: for the specified className, schema and clientName. This dictionary has an additional key ULDatabaseClientName.

- (NSArray *) metadataForObjectsOfClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName 

Returns an array containing information on the objects of class className that are contained in schema of clientName. The information for each object is the dictionary returned by metadataForObjectWithID:ofClass:inSchema:ofClient:error(). If clientName is not connected to the database or does not have permission to read schema this method returns an empty array.

- (id) metadataForObjectWithID: (NSString*)  ident
ofClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Returns copy of the dictionary returned by the object identified by idents AdModelObject::allData() method with an additional key "Class".

- (ULSchemaMode) modeForSchema: (NSString*)  schema
ofClient: (NSString*)  clientName 

Description forthcomming

- (BOOL) objectInFileSystemDatabase: (id)  object

Returns True if object is in the primary file system database.

Note:
Will be deprecated.
- (id) outputReferencesForObjectWithID: (NSString*)  ident
ofClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Description forthcomming

- (ULFileSystemDatabaseBackend *) primaryFileSystemBackend

Returns the backend managing the applications primary file system database.

- (void) removeBackendForClient: (NSString*)  clientName

Removes the backend associated with clientName. However clientName cannot be the name associated with the primary file system backend. If it is an NSInvalidArgumentException is raised. If no backend is associated with clientName this method does nothing. Posts an ULDatabaseInterfaceDidRemoveBackendNotification on success.

- (BOOL) removeObjectOfClass: (NSString*)  className
withID: (NSString*)  ident
fromSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Removes an object of class className, which is uniquely identified by ident from schema of clientName.

- (BOOL) removeObjectsOfClass: (NSString*)  className
withIDs: (NSArray*)  idents
fromSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Calls removeObjectOfClass:withID:fromSchema:ofClient: for each id in idents.

- (BOOL) removeOutputReferencesToObjectWithID: (id)  ident
ofClass: (NSString*)  className
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Removes all output references to objects with id ident. className , schema and client are required in order to retrieve the objects input references from one of its instances. Note that a reference is global - i.e. all output references containing this id are removed if possible. Objects in an unwritable schema are not updated.

Note:
Currently errors are only reported if the input references cannot be retrieved. Other errors are ignored.
- (NSArray *) schemaInformationForClient: (NSString*)  clientName

Returns an array containing the names of all the schemas contained in the database associated with clientName.

- (id) unarchiveObjectWithID: (NSString*)  ident
ofClass: (NSString*)  className
fromSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

Unarchives the object of class className, whose identification is ident from the given schema of clientName. Returns nil if the object doenst exist.

- (id) unarchiveObjectWithMetadata: (NSDictionary*)  metadata
error: (NSError**)  error 

Unarchives the object with metadata.

- (BOOL) updateMetadataForObject: (id)  object
inSchema: (NSString*)  schema
ofClient: (NSString*)  clientName
error: (NSError**)  error 

The schema and clientName args are redundant here since they are available through object

- (BOOL) updateOutputReferencesForObject: (id)  object
error: (NSError**)  error 

Description forthcoming