diff options
Diffstat (limited to 'offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl')
| -rw-r--r-- | offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl b/offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl new file mode 100644 index 000000000..2a5369602 --- /dev/null +++ b/offapi/com/sun/star/sdb/XSingleSelectQueryComposer.idl @@ -0,0 +1,235 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_sdb_XSingleSelectQueryComposer_idl__ +#define __com_sun_star_sdb_XSingleSelectQueryComposer_idl__ + +#include <com/sun/star/beans/XPropertySet.idl> +#include <com/sun/star/beans/PropertyValue.idl> +#include <com/sun/star/lang/WrappedTargetException.idl> +#include <com/sun/star/sdbc/SQLException.idl> +#include <com/sun/star/sdb/XSingleSelectQueryAnalyzer.idl> + + + module com { module sun { module star { module sdb { + + +/** simplifies the composing of single select statements. + + <p> + The interface can be used for composing single SELECT statements without knowing the + structure of the used query. + </p> + + @see com::sun::star::sdb::SingleSelectQueryComposer + */ +interface XSingleSelectQueryComposer: XSingleSelectQueryAnalyzer +{ + // FILTER + + /** makes it possible to set a filter condition for the query. + @param filter + the filter to set + @throws com::sun::star::sdbc::SQLException + if a database access error occurs + or the statement isn't valid + or the statement isn't parsable. + */ + void setFilter([in] string filter) + raises (com::sun::star::sdbc::SQLException); + + /** appends a new set of filter criteria which is split into levels. + @param filter + The filter criteria is split into levels. Each level represents the + OR criteria. Within each level, the filters are provided as an AND criteria + with the name of the column and the filter condition. The filter condition + is of type string. The operator used, is defined by com::sun::star::sdb::SQLFilterOperator. + + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void setStructuredFilter([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter) + raises (com::sun::star::sdbc::SQLException,com::sun::star::lang::IllegalArgumentException); + + /** appends a new filter condition by a + com::sun::star::sdb::DataColumn + providing the name and the value for the filter. + The value property must be supported by the com::sun::star::sdb::DataColumn. + @param column + the column which is used to create a filter + @param andCriteria + If `TRUE` the filter condition will be appended as an AND condition, otherwise + the new filter condition will be appended as OR criteria. + E.g. (xx AND bb AND cc) OR newCriteria + @param filterOperator + The operator used, is defined by com::sun::star::sdb::SQLFilterOperator. + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void appendFilterByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator) + raises (com::sun::star::sdbc::SQLException, com::sun::star::lang::WrappedTargetException); + + // GROUP BY + + + /** makes it possible to set a group for the query. + @param group + the group part to set + @throws com::sun::star::sdbc::SQLException + if a database access error occurs + or the statement isn't valid + or the statement isn't parsable. + */ + void setGroup([in] string group) + raises (com::sun::star::sdbc::SQLException); + + + /** appends an additional part to the group criteria of the select + statement. The column must be a com::sun::star::sdbcx::Column. + @param column + the column which is used to create a group part + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void appendGroupByColumn([in] com::sun::star::beans::XPropertySet column) + raises (com::sun::star::sdbc::SQLException); + + // HAVING + + /** makes it possible to set a HAVING filter condition for the query. + @param filter + the filter to set + @throws com::sun::star::sdbc::SQLException + if a database access error occurs + or the statement isn't valid + or the statement isn't parsable. + */ + void setHavingClause([in] string filter) + raises (com::sun::star::sdbc::SQLException); + + + /** appends a new set of HAVING filter criteria which is split into levels. + @param filter + The HAVING filter criteria is split into levels. Each level represents the + OR criteria. Within each level, the filters are provided as an AND criteria + with the name of the column and the filter condition. The filter condition + is of type string. The operator used, is defined by com::sun::star::sdb::SQLFilterOperator. + + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void setStructuredHavingClause([in] sequence< sequence<com::sun::star::beans::PropertyValue> > filter) + raises (com::sun::star::sdbc::SQLException); + + /** appends a new HAVING filter condition by a + com::sun::star::sdb::DataColumn + providing the name and the value for the filter. + @param column + the column which is used to create a filter + @param andCriteria + If `TRUE` the filter condition will be appended as an AND condition, otherwise + the new filter condition will be appended as OR criteria. + E.g. (xx AND bb AND cc) OR newCriteria + @param filterOperator + The operator used, is defined by com::sun::star::sdb::SQLFilterOperator. + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void appendHavingClauseByColumn([in] com::sun::star::beans::XPropertySet column,[in] boolean andCriteria,[in] long filterOperator) + raises (com::sun::star::sdbc::SQLException, com::sun::star::lang::WrappedTargetException); + + // ORDER BY + + /** makes it possible to set a sort condition for the query. + @param order + the order part to set + @throws com::sun::star::sdbc::SQLException + if a database access error occurs + or the order isn't valid + or the statement isn't parsable. + */ + void setOrder([in] string order) + raises (com::sun::star::sdbc::SQLException); + + + /** appends an additional part to the sort order criteria of the select + statement. The column must be a com::sun::star::sdbcx::Column. + @param column + the column which is used to create an order part + @param ascending + `TRUE` when the order should be ascending, otherwise if `FALSE` descending. + @throws com::sun::star::sdbc::SQLException + if a database access error occurs. + */ + void appendOrderByColumn([in] com::sun::star::beans::XPropertySet column, + [in] boolean ascending) + raises (com::sun::star::sdbc::SQLException); + + // cumulative composing + + /** sets a new elementary query for the composer + + <p>An elementary query or statement is a (single select) statement whose parts are + not covered by the various set and get methods of the composer. That is, if the + elementary statement contains a filter clause, a call to + XSingleSelectQueryAnalyzer::getFilter() will not return you this + filter. Instead, only filters which have been set using for instance setFilter() + are covered by the get methods.</p> + + <p>The only methods which take all parts of the elementary statement into account are + XSingleSelectQueryAnalyzer::getQuery() and + XSingleSelectQueryAnalyzer::getQueryWithSubstitution(), which always returns + the complete composed query.</p> + + <p>As a result, you can use the composer to build cumulative filter expressions. That + is, you can set #ElementaryQuery to a statement already containing + filters, and then use setFilter() to append additional filters.</p> + + <p>The very same holds for sort orders, <code>HAVING</code> and <code>GROUP BY</code> + clauses.</p> + + <p>There are various use cases for this. For instance, you might want to use the + statement represented by a QueryDefinition, and extend it with additional + filters or sort orders, while not touching the respective parts already present + in QueryDefinition::Command. This can be achieved by setting the + QueryDefinition::Command as #ElementaryQuery of a + SingleSelectQueryComposer.</p> + + <p>If, in such a scenario, you would be interested in the filter part of the + QueryDefinition::Command, you would set it via + XSingleSelectQueryAnalyzer::setQuery(), and retrieve the filter + part via XSingleSelectQueryAnalyzer::getFilter().</p> + + <p>If you'd be interested in the composed filter, you would set the + QueryDefinition::Command as #ElementaryQuery, add your + filter, and propagate the resulting query (XSingleSelectQueryAnalyzer::getQuery()) + to an SingleSelectQueryAnalyzer instance via + XSingleSelectQueryAnalyzer::setQuery().</p> + */ + [attribute] string ElementaryQuery + { + set raises (com::sun::star::sdbc::SQLException); + }; +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |