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