1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_sdbc_XConnection_idl__
24#define __com_sun_star_sdbc_XConnection_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30 module com {  module sun {  module star {  module container {
31 published interface XNameAccess;
32};};};};
33
34#ifndef __com_sun_star_sdbc_SQLException_idl__
35#include <com/sun/star/sdbc/SQLException.idl>
36#endif
37
38#ifndef __com_sun_star_sdbc_XCloseable_idl__
39#include <com/sun/star/sdbc/XCloseable.idl>
40#endif
41
42 module com {  module sun {  module star {  module sdbc {
43
44 published interface XStatement;
45 published interface XPreparedStatement;
46 published interface XDatabaseMetaData;
47
48
49/** represents a connection (session) with a specific
50	database. Within the context of a Connection, SQL statements are
51	executed and results are returned.
52
53
54	<p>
55	A Connection's database is able to provide information
56	describing its tables, its supported SQL grammar, its stored
57	procedures, and the capabilities of this connection. This
58	information is obtained with the
59	<member scope="com::sun::star::sdbc">XDatabaseMetaData::getMetaData()</member>
60	method.
61
62	</p>
63	@see com::sun::star::sdbc::XDriverManager
64	@see com::sun::star::sdbc::XStatement
65	@see com::sun::star::sdbc::XDatabaseMetaData
66 */
67published interface XConnection: com::sun::star::sdbc::XCloseable
68{
69
70	/** creates a new
71		<type scope="com::sun::star::sdbc">Statement</type>
72		object for sending SQL statements to the database.
73
74
75		<p>
76		SQL statements without parameters are normally
77		executed using Statement objects. If the same SQL statement
78		is executed many times, it is more efficient to use a
79		<type scope="com::sun::star::sdbc">PreparedStatement</type>
80		.
81		</p>
82		<p>
83		Result sets created using the returned Statement will have
84		forward-only type, and read-only concurrency, by default.
85		</p>
86		<p>
87		Escape processing for the SQL-Statement is enabled, by default.
88		</p>
89
90		@returns
91			a new Statement object
92		@throws SQLException
93			if a database access error occurs.
94	 */
95	XStatement createStatement() raises (SQLException);
96	//-------------------------------------------------------------------------
97
98	/** creates a
99		<type scope="com::sun::star::sdbc">PreparedStatement</type>
100		object for sending parameterized SQL statements to the database.
101
102
103		<p>
104		A SQL statement with or without IN parameters can be
105		pre-compiled and stored in a PreparedStatement object. This
106		object can then be used to efficiently execute this statement
107		multiple times.
108
109		</p>
110		<p>
111		<b>
112		Note:
113		</b>
114		This method is optimized for handling
115		parametric SQL statements that benefit from precompilation. If
116		the driver supports precompilation,
117		the method
118		<code>prepareStatement</code>
119		will send
120		the statement to the database for precompilation. Some drivers
121		may not support precompilation. In this case, the statement may
122		not be sent to the database until the
123		<type scope="com::sun::star::sdbc">PreparedStatement</type>
124		is executed.  This has no direct effect on users; however, it does
125		affect which method throws certain SQLExceptions.
126		</p>
127		<p>
128		Result sets created using the returned PreparedStatement will have
129		forward-only type and read-only concurrency, by default.
130		</p>
131		<p>
132		Escape processing for the SQL-Statement is enabled, by default.
133		</p>
134
135		@param sql
136			a SQL statement that may contain one or more '?' IN parameter placeholders
137		@returns
138			a new PreparedStatement object containing the pre-compiled statement
139		@throws SQLException
140			if a database access error occurs.
141	 */
142	XPreparedStatement prepareStatement([in]string sql) raises (SQLException);
143    //-------------------------------------------------------------------------
144
145	/** creates a
146		<type scope="com::sun::star::sdbc">CallableStatement</type>
147		object for calling
148		database stored procedures.
149
150
151		<p>
152		The CallableStatement provides methods for setting up its IN and OUT
153		parameters, and methods for executing the call to a stored procedure.
154		</p>
155		<p>
156		<b>
157		Note:
158		</b>
159		This method is optimized for handling stored
160		procedure call statements. Some drivers may send the call
161		statement to the database when the method
162		<code>prepareCall</code>
163		is done;
164		<br/>
165		others may wait until the CallableStatement is executed. This has no
166		direct effect on users; however, it does affect which method
167		throws certain SQLExceptions.
168		Result sets created using the returned CallableStatement will have
169		forward-only type and read-only concurrency, by default.
170		</p>
171
172		@param sql
173			a SQL statement that may contain one or more '?' IN parameter placeholders
174		@returns
175			a new PreparedStatement object containing the pre-compiled statement
176		@throws SQLException
177			if a database access error occurs.
178	 */
179	XPreparedStatement prepareCall([in]string sql) raises (SQLException);
180	//-------------------------------------------------------------------------
181
182	/** converts the given SQL statement into the system's native SQL grammar.
183		A driver may convert the JDBC SQL grammar into its system's
184		native SQL grammar prior to sending it; this method returns the
185		native form of the statement that the driver would have sent.
186
187		@param sql
188			a SQL statement that may contain one or more '?' parameter placeholders
189		@returns
190			the native form of this statement
191		@throws SQLException
192			if a database access error occurs.
193	 */
194	string nativeSQL([in]string sql) raises (SQLException);
195    //-------------------------------------------------------------------------
196
197	/** sets this connection's auto-commit mode.
198
199
200		<p>
201		If a connection is in auto-commit mode, then all its SQL
202		statements will be executed and committed as individual
203		transactions. Otherwise, its SQL statements are grouped into
204		transactions that are terminated by a call to either
205		the method
206		<member scope="com::sun::star::sdbc">XConnection::commit()</member>
207		or the method
208		<member scope="com::sun::star::sdbc">XConnection::rollback()</member>
209		.
210		By default, new connections are in auto-commit mode.
211		</p>
212		<p>
213		The commit occurs when the statement completes or the next
214		execute occurs, whichever comes first. In the case of
215		statements returning a ResultSet, the statement completes when
216		the last row of the ResultSet has been retrieved or the
217		ResultSet has been closed. In advanced cases, a single
218		statement may return multiple results as well as output
219		parameter values. In these cases the commit occurs when all results and
220		output parameter values have been retrieved.
221		</p>
222
223		@param autoCommit
224			<TRUE/> enables auto-commit; <FALSE/> disables auto-commit.
225		@throws SQLException
226			if a database access error occurs.
227	 */
228	void setAutoCommit([in] boolean autoCommit) raises (SQLException);
229    //-------------------------------------------------------------------------
230
231	/** gets the current auto-commit state.
232
233		@returns
234			the current state of auto-commit mode.
235		@throws SQLException
236			if a database access error occurs.
237
238		@see setAutoCommit
239	 */
240	boolean getAutoCommit() raises (SQLException);
241    //-------------------------------------------------------------------------
242
243	/** makes all changes made since the previous commit/rollback
244		permanent and releases any database locks currently held
245		by the Connection. This method should be
246		used only when auto-commit mode has been disabled.
247
248		@throws SQLException
249			if a database access error occurs.
250
251		@see setAutoCommit
252	 */
253	void commit() raises (SQLException);
254    //-------------------------------------------------------------------------
255
256	/** drops all changes made since the previous
257		commit/rollback and releases any database locks currently held
258		by this Connection. This method should be used only when auto-commit has been disabled.
259
260		@throws SQLException
261			if a database access error occurs.
262
263		@see setAutoCommit
264	 */
265	void rollback() raises (SQLException);
266    //-------------------------------------------------------------------------
267
268	/** tests to see if a connection is closed.
269
270
271		<p>
272		<b>
273		Note:
274		</b>
275		A Connection is automatically closed if no one references it
276		anymore. Certain fatal errors also result in a closed Connection.
277		</p>
278
279		@returns
280			<TRUE/> if the connection is closed; <FALSE/> if it's still open.
281		@throws SQLException
282			if a database access error occurs.
283	 */
284	boolean isClosed() raises (SQLException);
285	//-------------------------------------------------------------------------
286
287	/** gets the metadata regarding this connection's database.
288
289
290		<p>
291		A Connection's database is able to provide information
292		describing its tables, its supported SQL grammar, its stored
293		procedures, the capabilities of this connection, and so on. This
294		information is made available through a DatabaseMetaData
295		object.
296		</p>
297
298		@returns
299			a DatabaseMetaData object for this Connection.
300		@throws SQLException
301			if a database access error occurs.
302	 */
303	XDatabaseMetaData getMetaData() raises (SQLException);
304    //-------------------------------------------------------------------------
305
306	/** puts this connection in read-only mode as a hint to enable
307		database optimizations.
308
309
310		<p>
311		<b>
312		Note:
313		</b>
314		This method cannot be called while in the
315		middle of a transaction. Calling setReadOnly with
316		<TRUE/>
317		does not
318		necessarily cause writes to be prohibited.
319		</p>
320
321		@param readONly
322			<TRUE/> enables read-only mode; <FALSE/> disables read-only mode.
323		@throws SQLException
324			if a database access error occurs.
325	 */
326	void setReadOnly([in]boolean readOnly) raises (SQLException);
327    //-------------------------------------------------------------------------
328
329	/** tests to see if the connection is in read-only mode.
330		@returns
331			<TRUE/> if connection is read-only and <FALSE/> otherwise.
332		@throws SQLException
333			if a database access error occurs.
334	 */
335	boolean isReadOnly() raises (SQLException);
336    //-------------------------------------------------------------------------
337
338	/** sets a catalog name in order to select
339		a subspace of this Connection's database in which to work.
340		If the driver does not support catalogs, it will
341		silently ignore this request.
342		@param catalog
343			the name of the catalog.
344		@throws SQLException
345			if a database access error occurs.
346	 */
347	void setCatalog([in]string catalog) raises (SQLException);
348    //-------------------------------------------------------------------------
349
350	/** returns the Connection's current catalog name.
351		@returns
352			the current catalog name or an empty string.
353		@throws SQLException
354			if a database access error occurs.
355	 */
356	string getCatalog() raises (SQLException);
357	//-------------------------------------------------------------------------
358
359	/** attempts to change the transaction isolation level to the one given.
360
361
362		<p>
363		The constants defined in
364		<type scope="com::sun::star::sdbc">TransactionIsolation</type>
365		are the possible transaction isolation levels.
366		</p>
367		<p>
368		<b>
369		Note:
370		</b>
371		This method cannot be called while
372		in the middle of a transaction.
373		</p>
374		@param level
375			one of the TransactionIsolation values with the exception of NONE; some databases may not support other values.
376		@throws SQLException
377			if a database access error occurs.
378
379		@see com::sun::star::sdbc::XDatabaseMetaData::supportsTransactionIsolationLevel()
380	 */
381	void setTransactionIsolation([in]long level) raises (SQLException);
382    //-------------------------------------------------------------------------
383
384	/** gets this Connection's current transaction isolation level.
385		@returns
386			the current TransactionIsolation mode value.
387		@throws SQLException
388			if a database access error occurs.
389	 */
390	long getTransactionIsolation() raises (SQLException);
391	//-------------------------------------------------------------------------
392
393	/** gets the type map object associated with this connection. Only drivers
394		which implement the custom type mapping facility will return an object otherwise
395		NULL could be returned.
396
397		<p>
398		Unless the application has added an entry to the type map, the map
399		returned will be empty.
400		</p>
401		@returns
402		    the XNameAccess object associated with this Connection object.
403
404		@throws SQLException
405			if a database access error occurs.
406	 */
407	com::sun::star::container::XNameAccess getTypeMap() raises (SQLException);
408    //-------------------------------------------------------------------------
409
410	/** installs the given type map as the type map for this connection.
411		The type map will be used for the custom mapping of SQL structured types
412		and distinct types.
413
414
415		<p>
416		Only if the driver supports custom type mapping is the setting of a map allowed.
417		</p>
418
419		@param typeMap
420			set the XNameAccess object associated with this Connection object.
421		@throws SQLException
422			if a database access error occurs.
423	 */
424	void setTypeMap([in]com::sun::star::container::XNameAccess typeMap)
425		raises (SQLException);
426};
427
428//=============================================================================
429
430}; }; }; };
431
432/*===========================================================================
433===========================================================================*/
434#endif
435