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

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