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