
1 // 2 // Copyright (c) 2007, Brian Frank and Andy Frank 3 // Licensed under the Academic Free License version 3.0 4 // 5 // History: 6 // 30 Jun 07 Brian Frank Creation 7 // 8 9 ** 10 ** Connection manages a logical connection to an SQL database. 11 ** 12 ** Refer to the [Sql docs]`docLib::Sql` for more details. 13 ** 14 class Connection 15 { 16 17 ////////////////////////////////////////////////////////////////////////// 18 // Lifecycle 19 ////////////////////////////////////////////////////////////////////////// 20 21 ** 22 ** Open a connection to a SQL database. Throw 'Err' on failure. 23 ** 24 ** In a Java platform, the connection is opened using JDBC. The 25 ** database Str specifies the 'java.sql.Connection' URL. The JDBC 26 ** driver class should be preloaded - the simplest mechanism is to 27 ** add it to "sys.props". 28 ** 29 static native Connection open(Str database, Str username, Str password) 30 31 ** 32 ** Internal constructor. 33 ** 34 internal new make() {} 35 36 ** 37 ** Return if this connection has been closed. 38 ** 39 native Bool isClosed() 40 41 ** 42 ** Close the connection. This method is guaranteed to never throw 43 ** an 'Err'. Return true if the connection was closed successfully 44 ** or 'false' if closed abnormally. 45 ** 46 native Bool close() 47 48 ////////////////////////////////////////////////////////////////////////// 49 // Database metadata 50 ////////////////////////////////////////////////////////////////////////// 51 52 ** 53 ** List the tables in the database. Returns a list of the 54 ** table names. 55 ** 56 native Str[] tables() 57 58 ** 59 ** Get a default row instance for the specified table. The 60 ** result has a field for each table column. 61 ** 62 native Obj tableRow(Str tableName) 63 64 ////////////////////////////////////////////////////////////////////////// 65 // Statements 66 ////////////////////////////////////////////////////////////////////////// 67 68 ** 69 ** Execute an SQL query which returns a relational table as a 70 ** result. If 'of' is 'null', the result is returned as a 'List' 71 ** of 'Rows'. The 'Cols' are available from 'List.of.fields' or 72 ** on 'type.fields' of each row instance. If 'of' is specified, 73 ** then the result is returned as a 'List' of that type. Columns 74 ** are mapped to the type's fields. If a column cannot be mapped 75 ** to a field, then an 'SqlErr' is thrown. 76 ** 77 native Obj[] query(Str sql, Type of := null) 78 79 ** 80 ** Execute an SQL query. For each row in the result, invoke 81 ** the specified function 'c'. If 'of' is null, the 'Obj' 82 ** passed to the 'each' function will be of type 'Row'. 83 ** Otherwise the 'of' type specifies the row type passed 84 ** to the 'each' function. 85 ** 86 native Void queryEach(Str sql, Type of, |Obj row| each) 87 88 ** 89 ** Execute a SQL statement and if applicable return 90 ** the number of rows modified. 91 ** 92 native Int execute(Str sql) 93 94 ** 95 ** Prepare a statement for use later with this connection. 96 ** 97 Statement prepare(Str sql) 98 { 99 return Statement.make(this, sql).prepare() 100 } 101 102 ////////////////////////////////////////////////////////////////////////// 103 // Transactions 104 ////////////////////////////////////////////////////////////////////////// 105 106 ** 107 ** If auto commit is 'true', then each statement is executed 108 ** immediately. Otherwise statements are executed inside a 109 ** transaction which is terminated by a call to 'commit' 110 ** or 'rollback'. Auto commit defaults to 'true'. 111 ** 112 Bool autoCommit 113 { 114 get { return getAutoCommit } 115 set { setAutoCommit(val) } 116 } 117 private native Bool getAutoCommit() 118 private native Void setAutoCommit(Bool b) 119 120 121 ** 122 ** Commit all the changes made inside the current transaction. 123 ** 124 native Void commit() 125 126 ** 127 ** Undo any changes made inside the current transaction. 128 ** 129 native Void rollback() 130 131 }