hunt.database.base.SqlConnection source code

1 /*
2  * Copyright (C) 2019, HuntLabs
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  */
17 
18 module hunt.database.base.SqlConnection;
19 
20 import hunt.database.base.AsyncResult;
21 import hunt.database.base.Common;
22 import hunt.database.base.PreparedQuery;
23 import hunt.database.base.RowSet;
24 import hunt.database.base.SqlClient;
25 import hunt.database.base.Transaction;
26 import hunt.database.base.Tuple;
27 
28 import hunt.collection.List;
29 import hunt.concurrency.Future;
30 
31 alias AsyncSqlConnectionHandler = AsyncResultHandler!SqlConnection;
32 alias SqlConnectionAsyncResult = AsyncResult!SqlConnection;
33 
34 
35 /**
36  * A connection to database server.
37  *
38  * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
39  * @author <a href="mailto:emad.albloushi@gmail.com">Emad Alblueshi</a>
40  */
41 interface SqlConnection : SqlClient {
42 
43     /**
44      * Set an handler called with connection errors.
45      *
46      * @param handler the handler
47      * @return a reference to this, so the API can be used fluently
48      */
49     SqlConnection exceptionHandler(ExceptionHandler handler);
50 
51     /**
52      * Set an handler called when the connection is closed.
53      *
54      * @param handler the handler
55      * @return a reference to this, so the API can be used fluently
56      */
57     SqlConnection closeHandler(VoidHandler handler);
58 
59     /**
60      * Begin a transaction and returns a {@link Transaction} for controlling and tracking
61      * this transaction.
62      * <p/>
63      * When the connection is explicitely closed, any inflight transaction is rollbacked.
64      *
65      * @return the transaction instance
66      */
67     Transaction begin();
68 
69     Transaction begin(bool closeOnEnd);
70 
71     /**
72      * @return whether the connection uses SSL
73      */
74     bool isSSL();
75 
76     bool isConnected();
77 
78     /**
79      * Close the current connection after all the pending commands have been processed.
80      */
81     void close();
82 
83     // override
84     // <R> SqlConnection preparedQuery(string sql, Collector<Row, ?, R> collector, Handler!(AsyncResult!(SqlResult!(R))) handler);
85 
86     // override
87     SqlConnection query(string sql, RowSetHandler handler);
88 
89     alias query = SqlClient.query;
90 
91     // override
92     // <R> SqlConnection query(string sql, Collector<Row, ?, R> collector, Handler!(AsyncResult!(SqlResult!(R))) handler);
93 
94     /**
95      * Create a prepared query.
96      *
97      * @param sql the sql
98      * @param handler the handler notified with the prepared query asynchronously
99      */
100     SqlConnection prepare(string sql, PreparedQueryHandler handler);
101 
102     Future!PreparedQuery prepareAsync(string sql);
103 
104     PreparedQuery prepare(string sql);
105 
106     /**
107      * 
108      */
109     SqlConnection preparedQuery(string sql, RowSetHandler handler);
110 
111     override
112     SqlConnection preparedQuery(string sql, Tuple arguments, RowSetHandler handler);
113 
114     /**
115      * 
116      */
117     Future!NamedQuery prepareNamedQueryAsync(string sql);
118 
119     NamedQuery prepareNamedQuery(string sql);
120 
121 
122 
123     // override
124     // <R> SqlConnection preparedQuery(string sql, Tuple arguments, Collector<Row, ?, R> collector, Handler!(AsyncResult!(SqlResult!(R))) handler);
125 
126     // override
127     // SqlConnection preparedBatch(string sql, List!(Tuple) batch, RowSetHandler handler);
128 
129     // override
130     // <R> SqlConnection preparedBatch(string sql, List!(Tuple) batch, Collector<Row, ?, R> collector, Handler!(AsyncResult!(SqlResult!(R))) handler);
131 
132 
133     /**
134      * Return the given string suitably quoted to be used as an identifier in an SQL statement string.
135      * Quotes are added only if necessary (i.e., if the string contains non-identifier characters or
136      * would be case-folded). Embedded quotes are properly doubled.
137      *
138      * @param identifier input identifier
139      * @return the escaped identifier
140      * @throws SQLException if something goes wrong
141      */
142     string escapeIdentifier(string identifier);
143 
144     /**
145      * Return the given string suitably quoted to be used as a string literal in an SQL statement
146      * string. Embedded single-quotes and backslashes are properly doubled. Note that quote_literal
147      * returns null on null input.
148      *
149      * @param literal input literal
150      * @return the quoted literal
151      * @throws SQLException if something goes wrong
152      * 
153      * See_Also:
154      *    https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html
155      */
156     string escapeLiteral(string literal);
157 }