xref: /trunk/main/offapi/com/sun/star/sdbc/XSQLInput.idl (revision cdf0e10c) 
1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_sdbc_XSQLInput_idl__
28#define __com_sun_star_sdbc_XSQLInput_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_util_Date_idl__
35#include <com/sun/star/util/Date.idl>
36#endif
37
38#ifndef __com_sun_star_util_DateTime_idl__
39#include <com/sun/star/util/DateTime.idl>
40#endif
41
42#ifndef __com_sun_star_util_Time_idl__
43#include <com/sun/star/util/Time.idl>
44#endif
45
46 module com {  module sun {  module star {  module io {
47 published interface XInputStream;
48};};};};
49
50#ifndef __com_sun_star_sdbc_SQLException_idl__
51#include <com/sun/star/sdbc/SQLException.idl>
52#endif
53
54 module com {  module sun {  module star {  module sdbc {
55
56 published interface XRef;
57 published interface XArray;
58 published interface XBlob;
59 published interface XClob;
60
61
62/** represents an input stream that contains a stream of values representing an
63	instance of a SQL structured or distinct type.
64
65
66	<p>
67	This interface, used only for custom mapping, is used by the driver
68	behind the scenes, and a programmer never directly invokes
69	<code>SQLInput</code>
70	methods.
71	</p>
72	<p>
73	When the method
74	<code>getObject</code>
75	is called with an object of a service implementing the interface
76	<code>SQLData</code>
77	, the SDBC driver calls the method
78	<member scope="com::sun::star::sdbc">XSQLData::getSQLType()</member>
79	to determine the SQL type of the user-defined type (UDT) being custom mapped.
80	The driver creates an instance of
81	<type scope="com::sun::star::sdbc">XSQLInput</type>
82	,
83	populating it with the attributes of the UDT. The driver then passes the input
84	stream to the method
85	<member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
86	, which in turn calls the
87	<code>XSQLInput.readXXX</code>
88	methods in its implementation for reading the attributes from the input stream.
89	</p>
90 */
91published interface XSQLInput: com::sun::star::uno::XInterface
92{
93
94	/** reads the next attribute in the stream as string.
95		@returns
96			the attribute; if the value is SQL NULL, return null.
97		@throws SQLException
98			if a database access error occurs.
99	 */
100	string readString() raises (SQLException);
101	//-------------------------------------------------------------------------
102
103	/** reads the next attribute in the stream as boolean.
104		@returns
105			the attribute; if the value is SQL NULL, return null.
106		@throws SQLException
107			if a database access error occurs.
108	 */
109	boolean readBoolean() raises (SQLException);
110	//-------------------------------------------------------------------------
111
112	/** reads the next attribute in the stream as byte.
113		@returns
114			the attribute; if the value is SQL NULL, return null.
115		@throws SQLException
116			if a database access error occurs.
117	 */
118	byte readByte() raises (SQLException);
119	//-------------------------------------------------------------------------
120
121	/** reads the next attribute in the stream as short.
122		@returns
123			the attribute; if the value is SQL NULL, return null.
124		@throws SQLException
125			if a database access error occurs.
126	 */
127	short readShort() raises (SQLException);
128	//-------------------------------------------------------------------------
129
130	/** reads the next attribute in the stream as long.
131		@returns
132			the attribute; if the value is SQL NULL, return null.
133		@throws SQLException
134			if a database access error occurs.
135	 */
136	long readInt() raises (SQLException);
137	//-------------------------------------------------------------------------
138
139	/** reads the next attribute in the stream as hyper.
140		@returns
141			the attribute; if the value is SQL NULL, return null.
142		@throws SQLException
143			if a database access error occurs.
144	 */
145	hyper readLong() raises (SQLException);
146	//-------------------------------------------------------------------------
147
148	/** reads the next attribute in the stream as float.
149		@returns
150			the attribute; if the value is SQL NULL, return null.
151		@throws SQLException
152			if a database access error occurs.
153	 */
154	float readFloat() raises (SQLException);
155	//-------------------------------------------------------------------------
156
157	/** reads the next attribute in the stream as double.
158		@returns
159			the attribute; if the value is SQL NULL, return null.
160		@throws SQLException
161			if a database access error occurs.
162	 */
163	double readDouble() raises (SQLException);
164	//-------------------------------------------------------------------------
165
166	/** reads the next attribute in the stream as sequence of bytes.
167		   	  @returns
168			the attribute; if the value is SQL NULL, return null.
169		@throws SQLException
170			if a database access error occurs.
171	 */
172	sequence<byte> readBytes() raises (SQLException);
173	//-------------------------------------------------------------------------
174
175	/** reads the next attribute in the stream as date.
176		@returns
177			the attribute; if the value is SQL NULL, return null.
178		@throws SQLException
179			if a database access error occurs.
180	 */
181	com::sun::star::util::Date readDate() raises (SQLException);
182	//-------------------------------------------------------------------------
183
184	/** reads the next attribute in the stream as time.
185		@returns
186			the attribute; if the value is SQL NULL, return null.
187		@throws SQLException
188			if a database access error occurs.
189	 */
190	com::sun::star::util::Time readTime() raises (SQLException);
191	//-------------------------------------------------------------------------
192
193	/** reads the next attribute in the stream as datetime.
194		@returns
195			the attribute; if the value is SQL NULL, return null.
196		@throws SQLException
197			if a database access error occurs.
198	 */
199	com::sun::star::util::DateTime readTimestamp() raises (SQLException);
200	//-------------------------------------------------------------------------
201
202	/** reads the next attribute in the stream as sequence of bytes.
203		@returns
204			the attribute; if the value is SQL NULL, return null.
205		@throws SQLException
206			if a database access error occurs.
207	 */
208	com::sun::star::io::XInputStream readBinaryStream() raises (SQLException);
209	//-------------------------------------------------------------------------
210
211	/** reads the next attribute in the stream as a unicode string.
212		@returns
213			the attribute; if the value is SQL NULL, return null.
214		@throws SQLException
215			if a database access error occurs.
216	 */
217	com::sun::star::io::XInputStream readCharacterStream() raises (SQLException);
218   	//-------------------------------------------------------------------------
219
220	/** returns the datum at the head of the stream as an any.
221
222
223		<p>
224		The actual type of the any returned is determined by the default
225		type mapping, and any customizations present in this stream's type map.
226
227		<br/>
228		A type map is registered with the stream by the SDBC driver before the
229		stream is passed to the application.
230
231		<br/>
232		When the datum at the head of the stream is a SQL NULL,
233		the method returns <void/>. If the datum is a SQL structured or distinct
234		type, it determines the SQL type of the datum at the head of the stream,
235		constructs an object of the appropriate service, and calls the method
236		<member scope="com::sun::star::sdbc">XSQLData::readSQL()</member>
237		on that object, which reads additional data
238		from the stream using the protocol described for that method.
239
240		</p>
241		@returns
242			the attribute; if the value is SQL NULL, return null.
243		@throws SQLException
244			if a database access error occurs.
245	 */
246	any readObject() raises (SQLException);
247  	//-------------------------------------------------------------------------
248
249	/** reads a REF(&amp;lt;structured-type&amp;gt;) from the stream.
250		@returns
251			the attribute; if the value is SQL NULL, return null.
252		@throws SQLException
253			if a database access error occurs.
254	 */
255	XRef readRef() raises (SQLException);
256  	//-------------------------------------------------------------------------
257
258	/** reads a BLOB from the stream.
259		@returns
260			the attribute; if the value is SQL NULL, return null.
261		@throws SQLException
262			if a database access error occurs.
263	 */
264	XBlob readBlob() raises (SQLException);
265  	//-------------------------------------------------------------------------
266
267	/** reads a CLOB from the stream.
268		@returns
269			the attribute; if the value is SQL NULL, return null.
270		@throws SQLException
271			if a database access error occurs.
272	 */
273	XClob readClob() raises (SQLException);
274  	//-------------------------------------------------------------------------
275
276	/** reads an array from the stream.
277		@returns
278			the attribute; if the value is SQL NULL, return null.
279		@throws SQLException
280			if a database access error occurs.
281	 */
282	XArray readArray() raises (SQLException);
283  	//-------------------------------------------------------------------------
284
285	/** determines whether the last value read was null.
286		@returns
287			<TRUE/> if the most recently gotten SQL value was null; otherwise, <FALSE/>
288		@throws SQLException
289			if a database access error occurs.
290	 */
291	boolean wasNull() raises (SQLException);
292};
293
294//=============================================================================
295
296}; }; }; };
297
298/*===========================================================================
299===========================================================================*/
300#endif
301