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