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