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