- Conforms To:
- NSCopying
- NSObject
- Declared In:
- RTSQLSession.h
- - host
- - port
- - userid
- - databaseName
- - plugin
- - dataTypes
- - lastErrorMessage
- - dataLoaded
- - invalidateData
- - databases
- - databaseWithName:
- - supportsDatabaseSelection
- - requiresDatabaseSelection
- - defaultDatabaseName
- - selectDatabase:
- - valueForKeyPath:
- - performQuery:onDatabase:
- - resultSets
- - escapeString:
- - namesCaseSensitive
- - supportsLimit
- - supportsPerformInsert
- - supportsPerformUpdate
- - supportsConstraints
- - requiresSchemaQualifiers
- - sqlKeywords
- - supportsTransactions
- - transactionInProgress
- - beginTransaction
- - commit
- - rollback
- - performInsert:forColumns:ofTypes:withNativeTypes:usingValues:
- - performUpdate:forColumns:ofTypes:withNativeTypes:usingValues:forRows:
- - tryLockSession
- - lockSession
- - unlockSession
- (BOOL)beginTransaction
Starts a transaction for this session. Returns false if fails to start transaction. This can happen if the plugin does not support transactions. If a transaction is already in progress, it will be rolled-back and a new transaction will be started. Disables auto-commit.
- (BOOL)commit
Commits the current transaction. Returns false if commit fails. An error message is available via lastErrorMessage and the transaction will be rolled back.
- (BOOL)dataLoaded
if NO is returned, documented methods could require network traffic to the remote server.
- (NSArray*)dataTypes
Returns an array of RTSQLDataType objects representing the data types supported by the remote server.
- (NSString*)databaseName
Returns the initial database name provided while opening the connection. This value is not necessarily the name of an RTSQLDatabase. For most plugins, it is the equivalent to a SQL catalog name.
- (id <RTSQLDatabase>)databaseWithName:(NSString*)name
Returns the RTSQLDatabase with the specified name, or nil if no such database exists.
- (NSArray*)databases
Return an array of RTSQLDatabase objects for the remote server. If dataLoaded == NO, then the server will be contacted for information, which could result in the current thread be blocked.
- (NSString*)defaultDatabaseName
Returns the default database name to use as the current database (if known).
- (NSString*)escapeString:(NSString*)inString
Returns inString escaped for use in a SQL query.
- (NSString*)host
Returns the host this session is connected to.
- (void)invalidateData
Causes the session object to invalidate the lists of databases and data types from server. The next time they are requested, they will be refetch.
- (NSString*)lastErrorMessage
Returns the last error message from the server as an auto-released string.
- (void)lockSession
Locks the session's lock. If not available, blocks until lock is free. -unlockSession must be called to release the lock.
- (BOOL)namesCaseSensitive
Returns YES if the names of columns/tables/databases are case-sensitive.
- (void)performInsert:(id <RTSQLTable>)table forColumns:(NSArray *)columnNames ofTypes:(NSArray*)dataTypes withNativeTypes:(NSArray*)nativeTypes usingValues:(NSArray*)values
Inserts a new row into table. All arrays should have the same number of elements. columnNames are the names of the columns, dataTypes are the data types on the server (can be nil, in which cause handled based on nativeTypes). nativeTypes is array of NSNumbers containing the nativeDataType constants for what each value is, and values are those values. If a nativeType is zero, the matching value is treated as a literal string to use (such as a subquery). If a value is NSNull, then a null is inserted. Raises exception if fails.
- (id <RTSQLResultSet>)performQuery:(NSString*)query onDatabase:(id <RTSQLDatabase>)db
Performs query, returning back a result set. Raises an exception if the query fails.
- (void)performUpdate:(id <RTSQLTable>)table forColumns:(NSArray *)columnNames ofTypes:(NSArray*)dataTypes withNativeTypes:(NSArray*)nativeTypes usingValues:(NSArray*)values forRows:(NSString*)whereClause
Updates a row in a table. All arrays should have the same number of elements. columnNames are the names of the columns to update, dataTypes are the data types on the server (can be nil, in which cause handled based on nativeTypes). nativeTypes is array of NSNumbers containing the nativeDataType constants for what each value is, and values are those values. If a nativeType is zero, the matching value is treated as a literal string to use (such as a subquery). If a value is NSNull, then a null is inserted. whereClause is a textual where clause, including the WHERE. Raises exception if fails.
- (id <RTSQLPlugin>)plugin
Returns the plugin that created this session.
- (UInt16)port
Returns the port number this session is connected to, or zero if unknown or not-applicable.
- (BOOL)requiresDatabaseSelection
Returns YES if the session requires database selection (such as MySQL does).
- (BOOL)requiresSchemaQualifiers
No method description.
- (NSArray*)resultSets
Returns an array of open RTSQLResultSet objects.
- (void)rollback
Performs a Rollback on the current transaction, reenabling auto-commit.
- (void)selectDatabase:(id <RTSQLDatabase>)database
Selects database as the current default database, if database selection is supported. Otherwise, has no effect.
- (NSArray*)sqlKeywords
Returns an array of keywords for this database. Returns nil if the keywords are unknown.
- (BOOL)supportsConstraints
Returns YES if constraints are supported.
- (BOOL)supportsDatabaseSelection
Returns YES if the session supports database selection (such as MySQL does).
- (BOOL)supportsLimit
Returns YES if the remote server supports a LIMIT clause on SELECT queries.
- (BOOL)supportsPerformInsert
If NO, performInsert:forColumns:ofTypes:withNativeTypes:usingValues: will raise an exception because it isn't implemented for this database plugin.
- (BOOL)supportsPerformUpdate
If NO, performUpdate:forColumns:ofTypes:withNativeTypes:usingValues:forRows: will raise an exception because it isn't implemented for this database plugin.
- (BOOL)supportsTransactions
Returns YES if transactions are supported.
- (BOOL)transactionInProgress
Returns YES if a transaction is in progress.
- (BOOL)tryLockSession
Attempts to lock the session's lock and returns if successful. Does not block. If returns YES, -unlockSession must be called to release the lock.
- (void)unlockSession
Unlocks the session's lock. Should be called for each call to -lockSession and every call to -tryLockSession that returned YES.
- (NSString*)userid
Returns the userid this session used when connecting.
- (id)valueForKeyPath:(NSString *)keyPath
part of NSKeyValueCoding informal protocol. Allows finding a table by "database.table" syntax.
RTSQLSession objects can post the following notifications to interested observers.
This notification object contains the RTSQLSession as the notification object. It is posted when the schema has likely changed and should be updated. (Such as when an CREATE TABLE statement has been executed.
This notification object contains the RTSQLSession as the notification object. It is posted when the session is in the process of closing (its retain count has reached zero.
This notification object contains the RTSQLSession as the notification object. The userInfo dictionary contains an NSNumber(BOOL) value under the key "Success". If YES, a commit was successful. If no, a rollback was performed.