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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21  module com {  module sun {  module star {  module sdb {
  22
  23
  24 /** simplifies the composing of single select statements.
  25
  26     <p>
  27     The interface can be used for composing single SELECT statements without knowing the
  28     structure of the used query.
  29     </p>
  30
  31     @see com::sun::star::sdb::SingleSelectQueryComposer
  32  */
  33 interface XSingleSelectQueryComposer: XSingleSelectQueryAnalyzer
  34 {
  35     // FILTER
  36
  37     /** makes it possible to set a filter condition for the query.
  38         @param filter
  39             the filter to set
  40         @throws com::sun::star::sdbc::SQLException
  41             if a database access error occurs
  42             or the statement isn't valid
  43             or the statement isn't parsable.
  44      */
  45     void setFilter([in] string filter)
  46             raises (com::sun::star::sdbc::SQLException);
  47
  48     /** appends a new set of filter criteria which is split into levels.
  49         @param filter
  50             The filter criteria is split into levels. Each level represents the
  51             OR criteria. Within each level, the filters are provided as an AND criteria
  52             with the name of the column and the filter condition. The filter condition
  53             is of type string. The operator used, is defined by com::sun::star::sdb::SQLFilterOperator.
  54
  55         @throws com::sun::star::sdbc::SQLException
  56             if a database access error occurs.
  57      */
  58     void setStructuredFilter([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter)
  59         raises (com::sun::star::sdbc::SQLException,com::sun::star::lang::IllegalArgumentException);
  60
  61     /** appends a new filter condition by a
  62         com::sun::star::sdb::DataColumn
  63         providing the name and the value for the filter.
  64         The value property must be supported by the com::sun::star::sdb::DataColumn.
  65         @param column
  66             the column which is used to create a filter
  67         @param  andCriteria
  68             If `TRUE` the filter condition will be appended as an AND condition, otherwise
  69             the new filter condition will be appended as OR criteria.
  70             E.g. (xx AND bb AND cc) OR newCriteria
  71         @param  filterOperator
  72             The operator used, is defined by com::sun::star::sdb::SQLFilterOperator.
  73         @throws com::sun::star::sdbc::SQLException
  74             if a database access error occurs.
  75      */
  76     void appendFilterByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator)
  77             raises (com::sun::star::sdbc::SQLException, com::sun::star::lang::WrappedTargetException);
  78
  79     // GROUP BY
  80
  81
  82     /** makes it possible to set a group for the query.
  83         @param group
  84             the group part to set
  85         @throws com::sun::star::sdbc::SQLException
  86             if a database access error occurs
  87             or the statement isn't valid
  88             or the statement isn't parsable.
  89      */
  90     void setGroup([in] string group)
  91             raises (com::sun::star::sdbc::SQLException);
  92
  93
  94     /** appends an additional part to the group criteria of the select
  95         statement. The column must be a com::sun::star::sdbcx::Column.
  96         @param column
  97             the column which is used to create a group part
  98         @throws com::sun::star::sdbc::SQLException
  99             if a database access error occurs.
 100      */
 101     void appendGroupByColumn([in] com::sun::star::beans::XPropertySet column)
 102             raises (com::sun::star::sdbc::SQLException);
 103
 104     // HAVING
 105
 106     /** makes it possible to set a HAVING filter condition for the query.
 107         @param filter
 108             the filter to set
 109         @throws com::sun::star::sdbc::SQLException
 110             if a database access error occurs
 111             or the statement isn't valid
 112             or the statement isn't parsable.
 113      */
 114     void setHavingClause([in] string filter)
 115             raises (com::sun::star::sdbc::SQLException);
 116
 117
 118     /** appends a new set of HAVING filter criteria which is split into levels.
 119         @param filter
 120             The HAVING filter criteria is split into levels. Each level represents the
 121             OR criteria. Within each level, the filters are provided as an AND criteria
 122             with the name of the column and the filter condition. The filter condition
 123             is of type string. The operator used, is defined by com::sun::star::sdb::SQLFilterOperator.
 124
 125         @throws com::sun::star::sdbc::SQLException
 126             if a database access error occurs.
 127      */
 128     void setStructuredHavingClause([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter)
 129             raises (com::sun::star::sdbc::SQLException);
 130
 131     /** appends a new HAVING filter condition by a
 132         com::sun::star::sdb::DataColumn
 133         providing the name and the value for the filter.
 134         @param column
 135             the column which is used to create a filter
 136         @param  andCriteria
 137             If `TRUE` the filter condition will be appended as an AND condition, otherwise
 138             the new filter condition will be appended as OR criteria.
 139             E.g. (xx AND bb AND cc) OR newCriteria
 140         @param  filterOperator
 141             The operator used, is defined by com::sun::star::sdb::SQLFilterOperator.
 142         @throws com::sun::star::sdbc::SQLException
 143             if a database access error occurs.
 144      */
 145     void appendHavingClauseByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator)
 146             raises (com::sun::star::sdbc::SQLException, com::sun::star::lang::WrappedTargetException);
 147
 148     // ORDER BY
 149
 150     /** makes it possible to set a sort condition for the query.
 151         @param order
 152             the order part to set
 153         @throws com::sun::star::sdbc::SQLException
 154             if a database access error occurs
 155             or the order isn't valid
 156             or the statement isn't parsable.
 157      */
 158     void setOrder([in] string order)
 159             raises (com::sun::star::sdbc::SQLException);
 160
 161
 162     /** appends an additional part to the sort order criteria of the select
 163         statement. The column must be a com::sun::star::sdbcx::Column.
 164         @param column
 165             the column which is used to create an order part
 166         @param  ascending
 167             `TRUE` when the order should be ascending, otherwise if `FALSE` descending.
 168         @throws com::sun::star::sdbc::SQLException
 169             if a database access error occurs.
 170      */
 171     void appendOrderByColumn([in] com::sun::star::beans::XPropertySet column,
 172                              [in] boolean ascending)
 173             raises (com::sun::star::sdbc::SQLException);
 174
 175     // cumulative composing
 176
 177     /** sets a new elementary query for the composer
 178
 179         <p>An elementary query or statement is a (single select) statement whose parts are
 180         not covered by the various set and get methods of the composer. That is, if the
 181         elementary statement contains a filter clause, a call to
 182         XSingleSelectQueryAnalyzer::getFilter() will not return you this
 183         filter. Instead, only filters which have been set using for instance setFilter()
 184         are covered by the get methods.</p>
 185
 186         <p>The only methods which take all parts of the elementary statement into account are
 187         XSingleSelectQueryAnalyzer::getQuery() and
 188         XSingleSelectQueryAnalyzer::getQueryWithSubstitution(), which always returns
 189         the complete composed query.</p>
 190
 191         <p>As a result, you can use the composer to build cumulative filter expressions. That
 192         is, you can set #ElementaryQuery to a statement already containing
 193         filters, and then use setFilter() to append additional filters.</p>
 194
 195         <p>The very same holds for sort orders, <code>HAVING</code> and <code>GROUP BY</code>
 196         clauses.</p>
 197
 198         <p>There are various use cases for this. For instance, you might want to use the
 199         statement represented by a QueryDefinition, and extend it with additional
 200         filters or sort orders, while not touching the respective parts already present
 201         in QueryDefinition::Command. This can be achieved by setting the
 202         QueryDefinition::Command as #ElementaryQuery of a
 203         SingleSelectQueryComposer.</p>
 204
 205         <p>If, in such a scenario, you would be interested in the filter part of the
 206         QueryDefinition::Command, you would set it via
 207         XSingleSelectQueryAnalyzer::setQuery(), and retrieve the filter
 208         part via XSingleSelectQueryAnalyzer::getFilter().</p>
 209
 210         <p>If you'd be interested in the composed filter, you would set the
 211         QueryDefinition::Command as #ElementaryQuery, add your
 212         filter, and propagate the resulting query (XSingleSelectQueryAnalyzer::getQuery())
 213         to an SingleSelectQueryAnalyzer instance via
 214         XSingleSelectQueryAnalyzer::setQuery().</p>
 215     */
 216     [attribute] string ElementaryQuery
 217     {
 218         set raises (com::sun::star::sdbc::SQLException);
 219     };
 220 };
 221
 222
 223 }; }; }; };
 224
 225 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */