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_sdb_XSingleSelectQueryAnalyzer_idl__
28#define __com_sun_star_sdb_XSingleSelectQueryAnalyzer_idl__
29
30#ifndef __com_sun_star_beans_XPropertySet_idl__
31#include <com/sun/star/beans/XPropertySet.idl>
32#endif
33
34#ifndef __com_sun_star_beans_PropertyValue_idl__
35#include <com/sun/star/beans/PropertyValue.idl>
36#endif
37
38#ifndef __com_sun_star_sdbc_SQLException_idl__
39#include <com/sun/star/sdbc/SQLException.idl>
40#endif
41
42module com {  module sun {  module star {  module container {
43published interface XIndexAccess;
44};};};};
45//=============================================================================
46
47 module com {  module sun {  module star {  module sdb {
48
49//=============================================================================
50
51/** simplifies the analyzing of single select statements.
52
53    <p>
54    The interface can be used for analyzing single SELECT statements without knowing the
55    structure of the used query.
56    </p>
57 */
58published interface XSingleSelectQueryAnalyzer : com::sun::star::uno::XInterface
59{
60
61    /** returns the query.
62        @returns
63            the query
64     */
65    string getQuery();
66    //-------------------------------------------------------------------------
67
68    /** sets a new query for the composer, which may be expanded by filters, group by, having
69        and sort criteria.
70        @param command
71            the single select statement to set
72        @throws com::sun::star::sdbc::SQLException
73            if a database access error occurs
74            or the statement isn't a single select statement
75            or the statement isn't valid
76            or the statement can not be parsed.
77     */
78    void setQuery([in] string command )
79            raises (com::sun::star::sdbc::SQLException);
80    //-------------------------------------------------------------------------
81    // FILTER
82    //-------------------------------------------------------------------------
83
84    /** returns the used filter.
85        <p>
86        The filter criteria returned is part of the where condition of the
87        select command, but it does not contain the where token.
88        </p>
89        @returns
90            the filter
91     */
92    string getFilter();
93    //-------------------------------------------------------------------------
94
95    /** returns the currently used filter.
96             <p>
97             The filter criteria is split into levels. Each level represents the
98             OR criterias. Within each level, the filters are provided as an AND criteria
99             with the name of the column and the filter condition. The filter condition
100             is of type string. The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
101             </p>
102        @returns
103            the structured filter
104     */
105    sequence< sequence<com::sun::star::beans::PropertyValue> >
106        getStructuredFilter();
107
108    //-------------------------------------------------------------------------
109    // GROUP BY
110    //-------------------------------------------------------------------------
111
112    /** returns the currently used GROUP BY.
113        <p>
114        The group criteria returned is part of the GROUP BY clause of the
115        select command, but it does not contain the GROUP BY keyword .
116        </p>
117        @returns
118            the group
119     */
120    string getGroup();
121
122    //-------------------------------------------------------------------------
123    /** returns the currently used group.
124        <p>
125        The columns returned form the GROUP BY clause.
126        </p>
127        @returns
128            a collection of <type scope="com::sun::star::sdb">GroupColumn</type> which form the GROUP BY.
129     */
130    com::sun::star::container::XIndexAccess getGroupColumns();
131
132    //-------------------------------------------------------------------------
133    // HAVING
134    //-------------------------------------------------------------------------
135
136    /** returns the used HAVING filter.
137        <p>
138        The HAVING filter criteria returned is part of the HAVING condition of the
139        select command, but it does not contain the HAVING token.
140        </p>
141        @returns
142            the filter
143     */
144    string getHavingClause();
145    //-------------------------------------------------------------------------
146
147    /** returns the currently used HAVING filter.
148             <p>
149             The HAVING filter criteria is split into levels. Each level represents the
150             OR criterias. Within each level, the filters are provided as an AND criteria
151             with the name of the column and the filter condition. The filter condition
152             is of type string. The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
153             </p>
154        @returns
155            the structured HAVING filter
156     */
157    sequence< sequence<com::sun::star::beans::PropertyValue> >
158        getStructuredHavingClause();
159
160    //-------------------------------------------------------------------------
161    // ORDER BY
162    //-------------------------------------------------------------------------
163    /** returns the currently used sort order.
164        <p>
165        The order criteria returned is part of the ORDER BY clause of the
166        select command, but it does not contain the ORDER BY keyword .
167        </p>
168        @returns
169            the order
170     */
171    string getOrder();
172
173    //-------------------------------------------------------------------------
174    /** returns the currently used sort order.
175        <p>
176        The order criteria returned is part of the ORDER BY clause of the
177        select command, but it does not contain the ORDER BY keyword .
178        </p>
179        @returns
180            a collection of <type scope="com::sun::star::sdb">OrderColumn</type> which form the ORDER BY.
181     */
182    com::sun::star::container::XIndexAccess getOrderColumns();
183
184    //-------------------------------------------------------------------------
185    /** returns the query previously set at the analyzer, with all application-level
186        features being substituted by their database-level counterparts.
187
188        <p>The <type>XSingleSelectQueryAnalyzer</type> is an application-level component,
189        which in some respect understands SQL features usually not present at the database
190        level. As a prominent example, you might pass a <code>SELECT</code> statement to the analyzer
191        which is based on another query.</p>
192
193        <p>While all other methods will handle those additional features transparently - e.g.
194        the query in the <code>FROM</code> part of a <code>SELECT</code> statement will be handled
195        as if it really is a table -, <code>getQueryWithSubstitution</code> gives you the SQL statement
196        where all those features have been stripped, and replaced with appropriate standard SQL.</p>
197
198        <p>For example, consider a database document which contains a client-side query named <code>All Orders</code>.
199        This query is not known to the underlying database, so an SQL statement like
200        <code>SELECT * from "All Orders"</code> would be rejected by the database. However, instantiating
201        a <type>SingleSelectQueryAnalyzer</type> at the <type>Connection</type> object, and passing it the above query,
202        you can then use <code>getQueryWithSubstitution</code> to retrieve a statement where <code>"All Orders"</code>
203        has been replaced with the <code>SELECT</code> statement which actually constitutes the <code>"All Orders"</code>
204        query.</p>
205
206        @throws com::sun::star::sdbc::SQLException
207            if the query represented cannot be completely substituted. A usual case for this is a recursion in
208            the sub queries: Consider a query named <code>foo</code>, which is defined as <code>SELECT * FROM "bar"</code>.
209            Now assume that <code>bar</code> is a query defined as <code>SELECT * FROM "foo"</code>. Passing either
210            of those statements to an analyzer, and calling <member>getQueryWithSubstitution</member>, would result
211            in an exception being thrown, since it's impossible to substitute the sub queries with their
212            constituting statements.
213
214        @see Connection
215        @see XQueriesSupplier
216        @see DatabaseDocument
217
218        @since OOo 2.0.4
219    */
220    string getQueryWithSubstitution()
221        raises (com::sun::star::sdbc::SQLException);
222
223    /** sets a new query for the composer, which may be expanded by filters, group by, having
224        and sort criteria.
225        @param Command
226            is the command which should be executed, the type of command depends
227            on the CommandType.
228
229            <p>In case of a <member>CommandType</member> of <member>CommandType::COMMAND</member>,
230            means in case the <member>Command</member> specifies an SQL statement, the inherited
231            <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
232            becomes relevant:<br/>
233            It then can be to used to specify whether the SQL statement should be analyzed on the
234            client side before sending it to the database server.<br/>
235            The default value for <member scope="com::sun::star::sdbc">RowSet::EscapeProcessing</member>
236            is <TRUE/>. By switching it to <FALSE/>, you can pass backend-specific SQL statements,
237            which are not standard SQL, to your database.</p>
238
239            @see com::sun::star::sdb::CommandType
240            @see com::sun::star::sdbc::RowSet::EscapeProcessing
241        @param  CommandType
242            is the type of the command.
243            @see com::sun::star::sdb::CommandType
244        @throws com::sun::star::sdbc::SQLException
245            if a database access error occurs
246            or the statement isn't a single select statement
247            or the statement isn't valid
248            or the statement can not be parsed.
249     */
250    void setCommand([in] string Command ,[in] long CommandType)
251            raises (com::sun::star::sdbc::SQLException);
252};
253
254//=============================================================================
255
256}; }; }; };
257
258/*=============================================================================
259
260=============================================================================*/
261#endif
262
263