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_XSingleSelectQueryComposer_idl__
28#define __com_sun_star_sdb_XSingleSelectQueryComposer_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
42#ifndef __com_sun_star_sdb_XSingleSelectQueryAnalyzer_idl__
43#include <com/sun/star/sdb/XSingleSelectQueryAnalyzer.idl>
44#endif
45
46//=============================================================================
47
48 module com {  module sun {  module star {  module sdb {
49
50//=============================================================================
51
52/** simplifies the composing of single select statements.
53
54    <p>
55    The interface can be used for composing single SELECT statements without knowing the
56    structure of the used query.
57    </p>
58
59    @see com::sun::star::sdb::SingleSelectQueryComposer
60 */
61published interface XSingleSelectQueryComposer: XSingleSelectQueryAnalyzer
62{
63    //-------------------------------------------------------------------------
64    // FILTER
65    //-------------------------------------------------------------------------
66
67    /** makes it possible to set a filter condition	for the query.
68        @param filter
69            the filter to set
70        @throws com::sun::star::sdbc::SQLException
71            if a database access error occurs
72            or the statement isn't valid
73            or the statement isn't parseable.
74     */
75    void setFilter([in] string filter)
76            raises (com::sun::star::sdbc::SQLException);
77    //-------------------------------------------------------------------------
78
79    /** appends a new set of filter criteria which is split into levels.
80        @param filter
81            The filter criteria is split into levels. Each level represents the
82            OR criterias. Within each level, the filters are provided as an AND criteria
83            with the name of the column and the filter condition. The filter condition
84            is of type string. The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
85
86        @throws com::sun::star::sdbc::SQLException
87            if a database access error occurs.
88     */
89    void setStructuredFilter([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter)
90        raises (com::sun::star::sdbc::SQLException,com::sun::star::lang::IllegalArgumentException);
91    //-------------------------------------------------------------------------
92
93    /** appends a new filter condition by a
94        <type scope="com::sun::star::sdb">DataColumn</type>
95        providing the name and the value for the filter.
96        The value property must be supported by the <type scope="com::sun::star::sdb">DataColumn</type>.
97        @param column
98            the column which is used to create a filter
99        @param	andCriteria
100            If <TRUE/> the filter condition will be appended as an AND condition, otherwise
101            the new filter condition will be appended as OR criteria.
102            E.g. (xx AND bb AND cc) OR newCriteria
103        @param  filterOperator
104            The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
105        @throws com::sun::star::sdbc::SQLException
106            if a database access error occurs.
107     */
108    void appendFilterByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator)
109            raises (com::sun::star::sdbc::SQLException);
110
111    //-------------------------------------------------------------------------
112    // GROUP BY
113    //-------------------------------------------------------------------------
114
115
116    /** makes it possibile to set a group for the query.
117        @param group
118            the group part to set
119        @throws com::sun::star::sdbc::SQLException
120            if a database access error occurs
121            or the statement isn't valid
122            or the statement isn't parseable..
123     */
124    void setGroup([in] string group)
125            raises (com::sun::star::sdbc::SQLException);
126
127    //-------------------------------------------------------------------------
128
129    /** appends an additional part to the group criteria of the select
130        statement. The column must be a <type scope="com::sun::star::sdbcx">Column</type>.
131        @param column
132            the column which is used to create a group part
133        @throws com::sun::star::sdbc::SQLException
134            if a database access error occurs.
135     */
136    void appendGroupByColumn([in] com::sun::star::beans::XPropertySet column)
137            raises (com::sun::star::sdbc::SQLException);
138
139    //-------------------------------------------------------------------------
140    // HAVING
141    //-------------------------------------------------------------------------
142
143    /** makes it possible to set a HAVING filter condition for the query.
144        @param filter
145            the filter to set
146        @throws com::sun::star::sdbc::SQLException
147            if a database access error occurs
148            or the statement isn't valid
149            or the statement isn't parseable.
150     */
151    void setHavingClause([in] string filter)
152            raises (com::sun::star::sdbc::SQLException);
153
154    //-------------------------------------------------------------------------
155
156    /** appends a new set of HAVING filter criteria which is split into levels.
157        @param filter
158            The HAVING filter criteria is split into levels. Each level represents the
159            OR criterias. Within each level, the filters are provided as an AND criteria
160            with the name of the column and the filter condition. The filter condition
161            is of type string. The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
162
163        @throws com::sun::star::sdbc::SQLException
164            if a database access error occurs.
165     */
166    void setStructuredHavingClause([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter)
167            raises (com::sun::star::sdbc::SQLException);
168    //-------------------------------------------------------------------------
169
170    /** appends a new HAVING filter condition by a
171        <type scope="com::sun::star::sdb">DataColumn</type>
172        providing the name and the value for the filter.
173        @param column
174            the column which is used to create a filter
175        @param	andCriteria
176            If <TRUE/> the filter condition will be appended as an AND condition, otherwise
177            the new filter condition will be appended as OR criteria.
178            E.g. (xx AND bb AND cc) OR newCriteria
179        @param  filterOperator
180            The operator used, is defined by <type scope="com::sun::star::sdb">SQLFilterOperator</type>.
181        @throws com::sun::star::sdbc::SQLException
182            if a database access error occurs.
183     */
184    void appendHavingClauseByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator)
185            raises (com::sun::star::sdbc::SQLException);
186
187    //-------------------------------------------------------------------------
188    // ORDER BY
189    //-------------------------------------------------------------------------
190
191    /** makes it possibile to set a sort condition for the query.
192        @param order
193            the order part to set
194        @throws com::sun::star::sdbc::SQLException
195            if a database access error occurs
196            or the order isn't valid
197            or the statement isn't parseable.
198     */
199    void setOrder([in] string order)
200            raises (com::sun::star::sdbc::SQLException);
201
202    //-------------------------------------------------------------------------
203
204    /** appends an additional part to the sort order criteria of the select
205        statement. The column must be a <type scope="com::sun::star::sdbcx">Column</type>.
206        @param column
207            the column which is used to create a order part
208        @param	ascending
209            <TRUE/> when the order should be ascending, otherwise if <FALSE/> descending.
210        @throws com::sun::star::sdbc::SQLException
211            if a database access error occurs.
212     */
213    void appendOrderByColumn([in] com::sun::star::beans::XPropertySet column,
214                             [in] boolean ascending)
215            raises (com::sun::star::sdbc::SQLException);
216
217    //-------------------------------------------------------------------------
218    // culmulative composing
219    //-------------------------------------------------------------------------
220
221    /** sets a new elementary query for the composer
222
223        <p>An elementary query or statement is a (single select) statement whose parts are
224        not covered by the various set and get methods of the composer. That is, if the
225        elementary statement contains a filter clause, a call to
226        <member>XSingleSelectQueryAnalyzer::getFilter</member> will not return you this
227        filter. Instead, only filters which have been set using for instance <member>setFilter</member>
228        are covered by the get methods.</p>
229
230        <p>The only methods which take all parts of the elementary statement into account are
231        <member>XSingleSelectQueryAnalyzer::getQuery</member> and
232        <member>XSingleSelectQueryAnalyzer::getQueryWithSubstitution</member>, which always returns
233        the complete composed query.</p>
234
235        <p>As a result, you can use the composer to build culmulative filter expressions. That
236        is, you can set <member>ElementaryQuery</member> to a statement already containing
237        filters, and then use <member>setFilter</member> to append additional filters.</p>
238
239        <p>The very same holds for sort orders, <code>HAVING</code> and <code>GROUP BY</code>
240        clauses.</p>
241
242        <p>There are various use cases for this. For instance, you might want to use the
243        statement represented by a <type>QueryDefinition</type>, and extend it with additional
244        filters or sort orders, while not touching the respective parts already present
245        in <member>QueryDefinition::Command</member>. This can be achieved by setting the
246        <member>QueryDefinition::Command</member> as <member>ElementaryQuery</member> of a
247        <type>SingleSelectQueryComposer</type>.</p>
248
249        <p>If, in such a scenario, you would be interested in the filter part of the
250        <member>QueryDefinition::Command</member>, you would set it via
251        <member>XSingleSelectQueryAnalyzer::setQuery</member>, and retrieve the filter
252        part via <member>XSingleSelectQueryAnalyzer::getFilter</member>.</p>
253
254        <p>If you'd be interested in the composed filter, you would set the
255        <member>QueryDefinition::Command</member> as <member>ElementaryQuery</member>, add your
256        filter, and propagate the resulting query (<member>XSingleSelectQueryAnalyzer::getQuery</member>)
257        to an <type>SingleSelectQueryAnalyzer</type> instance via
258        <member>XSingleSelectQueryAnalyzer::setQuery</member>.</p>
259    */
260    [attribute] string ElementaryQuery
261    {
262        set raises (com::sun::star::sdbc::SQLException);
263    };
264};
265
266//=============================================================================
267
268}; }; }; };
269
270/*=============================================================================
271
272=============================================================================*/
273#endif
274
275