offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl

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