inc/FIoSqlStatementBuilder.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file        FIoSqlStatementBuilder.h
  19  * @brief       This is the header file for the %SqlStatementBuilder class.
  20  *
  21  * This header file contains the declarations of the %SqlStatementBuilder class.
  22  */
  23
  24 #ifndef _FIO_SQL_STATEMENT_BUILDER_H_
  25 #define _FIO_SQL_STATEMENT_BUILDER_H_
  26
  27 #include <FOspConfig.h>
  28
  29 namespace Tizen { namespace Base
  30 {
  31 class String;
  32 namespace Collection
  33 {
  34 class IList;
  35 class IMap;
  36 }
  37 }}
  38
  39 namespace Tizen { namespace Io
  40 {
  41
  42 /**
  43  * @class       SqlStatementBuilder
  44  * @brief       This class provides methods for building an SQL statement.
  45  *
  46  * @since       2.0
  47  *
  48  * @final       This class is not intended for extension.
  49  *
  50  * The %SqlStatementBuilder class provides methods for building an SQL statement.
  51  */
  52 class _OSP_EXPORT_ SqlStatementBuilder
  53         : public Tizen::Base::Object
  54 {
  55
  56 public:
  57         /**
  58         * Creates an SQL SELECT statement.
  59         *
  60         * @since                2.0
  61         *
  62         * @return               The SQL SELECT statement, @n
  63         *                               else an empty string in case of failure
  64         * @param[in]    table                           The table name to query from
  65         * @param[in]    pColumnList                     The list of column names to query @n
  66         *                                                                       The type of objects contained in the specified @c pColumnList must be
  67         *                                                                       Tizen::Base::String class.
  68         *                                                                       If it is @c null, all columns are returned in result set.
  69         * @param[in]    pWhere                          The filter to select the desired rows to query @n
  70         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
  71         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
  72         * @param[in]    pOrder                          The sorting order of rows to query @n
  73         *                                                                       It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
  74         * @param[in]    pLimit                          The limit of the number of rows to query @n
  75         *                                                                       It is the SQL 'LIMIT' clause excluding the 'LIMIT' itself.
  76         * @param[in]    pGroup                          The filter to select a column grouping rows to query @n
  77         *                                                                       It is the SQL 'GROUP BY' clause excluding the 'GROUP BY' itself.
  78         * @param[in]    pHaving                         The filter for the group @n
  79         *                                                                       It is the SQL 'HAVING' clause excluding the 'HAVING' itself.
  80         * @exception    E_SUCCESS                       The method is successful.
  81         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
  82         *                                                                       - The specified @c pColumnList is empty.
  83         *                                                                       - The specified @c pOrder is @c null and @c pLimit is not @c null.
  84         *                                                                       - The specified @c pGroup is @c null and @c pHaving is not @c null.
  85         * @exception    E_SYSTEM                        A system error has occurred.
  86         * @remarks
  87         *                               - The specific error code can be accessed using the GetLastResult() method.
  88         *                               - If the value specified in the @c pWhere is string, the value must be wrapped in
  89         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
  90         *                               For more information on the SQL statement, see SQLite SQL documents.
  91         */
  92         static Tizen::Base::String CreateSelectStatement(const Tizen::Base::String& table, const Tizen::Base::Collection::IList* pColumnList,
  93                         const Tizen::Base::String* pWhere, const Tizen::Base::String* pOrder = null, const Tizen::Base::String* pLimit = null,
  94                         const Tizen::Base::String* pGroup = null, const Tizen::Base::String* pHaving = null);
  95
  96         /**
  97         * Creates an SQL INSERT statement.
  98         *
  99         * @since                2.0
 100         *
 101         * @return               The SQL INSERT statement, @n
 102         *                               else an empty string in case of failure @n
 103         * @param[in]    table                           The table name to insert
 104         * @param[in]    insertMap                       The column-value pairs to insert @n
 105         *                                                                       The type of objects contained in the specified @c insertMap must be
 106         *                                                                       Tizen::Base::String class.
 107         * @exception    E_SUCCESS                       The method is successful.
 108         * @exception    E_INVALID_ARG           The specified @c insertMap is empty.
 109         * @exception    E_SYSTEM                        A system error has occurred.
 110         * @remarks
 111         *                               - The specific error code can be accessed using the GetLastResult() method.
 112         *                               - If the value specified in the @c insertMap is string, the value must be wrapped in
 113         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 114         *                               For more information on the SQL statement, see SQLite SQL documents.
 115         */
 116         static Tizen::Base::String CreateInsertStatement(const Tizen::Base::String& table, const Tizen::Base::Collection::IMap& insertMap);
 117
 118         /**
 119         * Creates an SQL UPDATE statement.
 120         *
 121         * @since                2.0
 122         *
 123         * @return               The SQL UPDATE statement, @n
 124         *                               else an empty string in case of failure @n
 125         * @param[in]    table                           The table name to update
 126         * @param[in]    updateMap                       The column-value pairs to update @n
 127         *                                                                       The type of objects contained in the specified @c updateMap must be
 128         *                                                                       Tizen::Base::String class.
 129         * @param[in]    pWhere                          The filter to select desired rows to update @n
 130         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 131         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 132         * @exception    E_SUCCESS                       The method is successful.
 133         * @exception    E_INVALID_ARG           The specified @c updateMap is empty.
 134         * @exception    E_SYSTEM                        A system error has occurred.
 135         * @remarks
 136         *                               - The specific error code can be accessed using the GetLastResult() method.
 137         *                               - If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
 138         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 139         *                               For more information on the SQL statement, see SQLITE SQL documents.
 140         */
 141         static Tizen::Base::String CreateUpdateStatement(const Tizen::Base::String& table, const Tizen::Base::Collection::IMap& updateMap,
 142                         const Tizen::Base::String* pWhere);
 143
 144         /**
 145         * Creates an SQL DELETE statement.
 146         *
 147         * @since                2.0
 148         *
 149         * @return               The SQL DELETE statement, @n
 150         *                               else an empty string in case of failure @n
 151         * @param[in]    table                           The table name to query
 152         * @param[in]    pWhere                          The filter to select desired rows to delete @n
 153         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 154         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 155         *                                                                       If it is @c null, all rows are deleted.
 156         * @exception    E_SUCCESS                       The method is successful.
 157         * @exception    E_INVALID_ARG           A specified parameter is invalid.
 158         * @exception    E_SYSTEM                        A system error has occurred.
 159         * @remarks
 160         *                               - The specific error code can be accessed using the GetLastResult() method.
 161         *                               - If the value specified in the @c pWhere is string, the value must be wrapped in
 162         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 163         *                               For more information on the SQL statement, see SQLITE SQL documents.
 164         */
 165         static Tizen::Base::String CreateDeleteStatement(const Tizen::Base::String& table, const Tizen::Base::String* pWhere);
 166
 167 private:
 168         /**
 169         * This default constructor is intentionally declared as private because this class cannot be constructed.
 170         *
 171         * @since        2.0
 172         */
 173         SqlStatementBuilder(void);
 174
 175         /**
 176         * This destructor is intentionally declared as private because this class cannot be constructed.
 177         *
 178         * @since        2.0
 179         */
 180         virtual ~SqlStatementBuilder(void);
 181
 182         /**
 183         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 184         *
 185         * @since        2.0
 186         * @remarks      This constructor is hidden.
 187         */
 188         SqlStatementBuilder(const SqlStatementBuilder& rhs);
 189
 190         /**
 191         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 192         *
 193         * @since        2.0
 194         * @remarks      This operator is hidden.
 195         */
 196         SqlStatementBuilder& operator =(const SqlStatementBuilder& rhs);
 197
 198         class _SqlStatementBuilderImpl* __pSqlStatementBuilderImpl;
 199
 200 }; // SqlStatementBuilder
 201
 202 }} // Tizen::Io
 203
 204 #endif // _FIO_SQL_STATEMENT_BUILDER_H_
 205