xref: /trunk/main/offapi/com/sun/star/sdbc/XArray.idl (revision d1766043)
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_XArray_idl__
24#define __com_sun_star_sdbc_XArray_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 module com {  module sun {  module star {  module sdbc {
39
40 published interface XResultSet;
41
42
43/** is used for mapping the SQL type
44	<member scope= "com::sun::star::sdbc">DataType::ARRAY</member>
45	.
46	By default, an
47	<code>Array</code>
48	is a transaction duration
49	reference to an SQL array. By default, an
50
51	<code>Array</code>
52
53	is implemented using a SQL LOCATOR(array) internally.
54 */
55published interface XArray: com::sun::star::uno::XInterface
56{
57
58	/** returns the SQL type name of the elements in
59		the array designated by this
60		<code>Array</code>
61		object.
62		<p>
63		If the elements are a built-in type, it returns
64		the database-specific type name of the elements.
65		If the elements are a user-defined type (UDT),
66		this method returns the fully-qualified SQL type name.
67		</p>
68		@returns
69			a String that is the database-specific name for a built-in base type or the fully-qualified SQL type name for a base type that is a UDT
70
71		@throws SQLException
72			if a database access error occurs.
73	 */
74	string getBaseTypeName() raises (SQLException);
75
76  	//-------------------------------------------------------------------------
77
78	/** returns the SDBC type of the elements in the array designated
79		by this
80		<code>Array</code>
81		object.
82		@returns
83			a constant from the SDBC types that is the type code for the elements in the array designated by this Array object.
84		@throws SQLException
85			if a database access error occurs.
86	 */
87	long getBaseType() raises (SQLException);
88
89	//-------------------------------------------------------------------------
90
91	/** retrieves the contents of the SQL array designated by this
92		   	 <code>Array</code>
93			 object, using the specified
94			 <code>typeMap</code>
95			 for type map customizations.
96			 <p>
97			 If the base type of the array does not match a user-defined type
98			 in
99			 <code>typeMap</code>
100			 , the standard mapping is used instead.
101
102		     @param typeMap
103				is a map object that contains mappings of SQL type names to
104				services. If the
105				<code>typeMap</code>
106				is
107				<NULL/>
108				, the type-map
109		   	 	associated with the connection for customizations of the type-mappings
110			 	is used.
111
112			 @returns
113				an sequence that contains the ordered elements
114				of the SQL array designated by this object.
115
116		     @throws SQLException
117				if an error occurs while attempting to access the array.
118	 */
119	sequence<any> getArray([in]com::sun::star::container::XNameAccess typeMap)
120		raises (SQLException);
121
122  	//-------------------------------------------------------------------------
123
124	/** returns an array containing a slice of the SQL array, beginning with the
125		   	 specified
126			 <code>index</code>
127			 and containing up to
128			 <code>count</code>
129		   	 successive elements of the SQL array.
130
131			 @param index
132				is the array index of the first element to retrieve;
133		        the first element is at index 1.
134		   	 @param count
135				is the number of successive SQL array elements to retrieve.
136			 @param typeMap
137				is a map object that contains mappings of SQL type names to
138				services. If the
139				<code>typeMap</code>
140				is
141				<NULL/>
142				, the type-map
143		   	    associated with the connection for customizations of the type-mappings
144				is used.
145		     @returns
146				an array containing up to
147				<code>count</code>
148				consecutive elements
149		   		of the SQL array, beginning with element
150				<code>index</code>
151				.
152		   	 @throws SQLException
153				if an error occurs while attempting to access the array.
154	 */
155	sequence<any> getArrayAtIndex([in]long index,
156								  [in]long count,
157								  [in]com::sun::star::container::XNameAccess
158								  									typeMap)
159			raises (SQLException);
160
161  	//-------------------------------------------------------------------------
162
163	/** returns a result set that contains the elements of the array
164		designated by this
165		<code>Array</code>
166		object and uses the given
167		<code>typeMap</code>
168		to map the array elements.  If the base
169		type of the array does not match a user-defined type in
170		<code>typeMap</code>
171		or the
172		<code>typeMap</code>
173		is
174		<NULL/>
175		,
176		the connection type mapping is used instead.
177
178
179		<p>
180		The result set contains one row for each array element, with
181		two columns in each row.  The second column stores the element
182		value; the first column stores the index into the array for
183		that element (with the first array element being at index 1).
184		The rows are in ascending order corresponding to
185		the order of the indices.
186		</p>
187
188		@param	typeMap
189			contains mapping of SQL user-defined types to classes in the UNO programming language
190		@returns
191			a ResultSet object containing one row for each of the elements in the array designated by this Array object,
192			with the rows in ascending order based on the indices.
193		@throws SQLException
194			if a database access error occurs.
195	 */
196	XResultSet getResultSet([in]com::sun::star::container::XNameAccess typeMap)
197		raises (SQLException);
198
199  	//-------------------------------------------------------------------------
200
201	/** returns a result set holding the elements of the subarray that
202		starts at index
203		<code>index</code>
204		and contains up to
205		<code>count</code>
206		successive elements. This method uses the given
207		<code>typeMap</code>
208		to map the array elements. If the base
209		type of the array does not match a user-defined type in
210		<code>typeMap</code>
211		or the
212		<code>typeMap</code>
213		is
214		<NULL/>
215		,
216		the connection type mapping is used instead.
217
218
219		<p>
220		The result set contains one row for each array element, with
221		two columns in each row.  The second column stores the element
222		value; the first column stores the index into the array for
223		that element (with the first array element being at index 1).
224		The rows are in ascending order corresponding to
225		the order of the indices.
226		</p>
227		@param index
228			the array index of the first element to retrieve; the first element is at index 1.
229		@param count
230			the number of successive SQL array elements to retrieve,
231		@param typeMap
232			the Map object that contains the mapping of SQL type names to classes in the UNO programming language.
233		@returns
234			a ResultSet object containing up to count consecutive elements of the SQL array
235			designated by this Array object, starting at index index.
236		@throws SQLException
237			if a database access error occurs.
238	 */
239	XResultSet getResultSetAtIndex([in]long index,
240								   [in]long count,
241								   [in]com::sun::star::container::XNameAccess typeMap)
242		raises (SQLException);
243};
244
245//=============================================================================
246
247}; }; }; };
248
249/*===========================================================================
250===========================================================================*/
251#endif
252