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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ErrorCondition.idl,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_sdb_ErrorCondition_idl__
  32 #define __com_sun_star_sdb_ErrorCondition_idl__
  33
  34 //=============================================================================
  35
  36 module com { module sun { module star { module sdb {
  37
  38 //=============================================================================
  39
  40 /** defines error conditions for OpenOffice.org Base core components
  41
  42     <p>Core components of OpenOffice.org will use those error conditions
  43     as error codes (<member scope="com::sun::star::sdbc">SQLException::ErrorCode</member>)
  44     whereever possible.<br/>
  45     That is, if an <code>SQLException</code> is raised by
  46     such a component, caused by an error condition which is included in the
  47     <type>ErrorCondition</type> group, then the respective <em>negative</em> value
  48     will be used as <code>ErrorCode</code>.</p>
  49
  50     <p>This allows to determine specific error conditions in your client code, and
  51     to handle it appropriately.</p>
  52
  53     <p>Note that before you examine the <code>ErrorCode</code> member of a caught
  54     <code>SQLException</code>, you need to make sure that the exception
  55     is really thrown by an OpenOffice.org Base core component. To do so, check
  56     whether the error message (<code>Exception::Message</code>) starts with the
  57     vendor string <code>[OOoBase]</code>.</p>
  58
  59     <p>The list of defined error conditions, by nature, is expected to permanently grow,
  60     so never assume it being finalized.</p>
  61
  62     @example Java
  63     <listing>
  64     catch ( SQLException e )
  65     {
  66     &nbsp;&nbsp;if ( e.Message.startsWith( "[OOoBase]" ) )
  67     &nbsp;&nbsp;&nbsp;&nbsp;if ( e.ErrorCode + ErrorCondition.SOME_ERROR_CONDITION == 0 )
  68     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;handleSomeErrorCondition();
  69     }
  70     </listing>
  71  */
  72 constants ErrorCondition
  73 {
  74     // ========================================================================
  75     // = section ROW_SET - css.sdb.RowSet related error conditions
  76
  77     /** is used by and <type>RowSet</type> to indicate that an operation has been vetoed
  78         by one of its approval listeners
  79
  80         <p>This error condition results in raising a <type>RowSetVetoException</type>.</p>
  81         @see RowSet
  82         @see XRowSetApproveBroadcaster
  83         @see XRowSetApproveListener
  84     */
  85     const long ROW_SET_OPERATION_VETOED = 100;
  86
  87     // ========================================================================
  88     // = section PARSER - parsing related error conditions
  89
  90     /** indicates that while parsing an SQL statement, cyclic sub queries have been detected.
  91
  92         <p>Imagine you have a client-side query <code>SELECT * FROM table</code>, which is
  93         saved as &quot;query1&quot;. Additionally, there is a query &quot;query2&quot; defined
  94         as <code>SELECT * FROM query1</code>. Now if you try to change the statement of
  95         <type>query1</type> to <code>SELECT * FROM query2</code>, this is prohibited, because
  96         it would lead to a cyclic sub query.
  97     */
  98     const long PARSER_CYCLIC_SUB_QUERIES = 200;
  99
 100     // ========================================================================
 101     // = section DB - application-level error conditions
 102     // =
 103     // = next section should start with 500
 104
 105     /** indicates that the name of a client side database object - a query, a form,
 106         or a report - contains one or more slashes, which is forbidden.
 107     */
 108     const long DB_OBJECT_NAME_WITH_SLASHES = 300;
 109
 110     /** indicates that an identifier is not SQL conform.
 111     */
 112     const long DB_INVALID_SQL_NAME = 301;
 113
 114     /** indicates that the name of a query contains quote characters.
 115
 116         <p>This error condition is met when the user attempts to save a query
 117         with a name which contains one of the possible database quote characters.
 118         This is an error since query names can potentially be used in
 119         <code>SELECT</code> statements, where quote identifiers would render the statement invalid.</p>
 120
 121         @see com::sun::star::sdb::tools::XDataSourceMetaData::supportsQueriesInFrom
 122     */
 123     const long DB_QUERY_NAME_WITH_QUOTES = 302;
 124
 125     /** indicates that an attempt was made to save a database object under a name
 126         which is already used in the database.
 127
 128         <p>In databases which support query names to appear in <code>SELECT</code>
 129         statements, this could mean that a table was attempted to be saved with the
 130         name of an existing query, or vice versa.</p>
 131
 132         <p>Otherwise, it means an object was attempted to be saved with the
 133         name of an already existing object of the same type.</p>
 134
 135         @see com::sun::star::sdb::application::DatabaseObject
 136         @see com::sun::star::sdb::tools::XDataSourceMetaData::supportsQueriesInFrom
 137     */
 138     const long DB_OBJECT_NAME_IS_USED = 303;
 139
 140     /** indicates an operation was attempted which needs a connection to the
 141         database, which did not exist at that time.
 142     */
 143     const long DB_NOT_CONNECTED = 304;
 144
 145     // ========================================================================
 146     // = section AB - address book access related error conditions
 147     // =
 148     // = next section should start with 550
 149
 150     /** used by the component implementing address book access to indicate that a requested address book could
 151         not be accessed.
 152
 153         <p>For instance, this error code is used when you try to access the address book
 154         in a Thunderbird profile named <q>MyProfile</q>,  but there does not exist a profile
 155         with this name.</p>
 156     */
 157     const long AB_ADDRESSBOOK_NOT_FOUND = 500;
 158
 159     // ========================================================================
 160     // = section DATA - data retrieval related error conditions
 161     // =
 162     // = next section should start with 600
 163
 164     /** used to indicate that a <code>SELECT</code> operation on a table needs a filter.
 165
 166         <p>Some database drivers are not able to <code>SELECT</code> from a table if the
 167         statement does not contain a <code>WHERE</code> clause. In this case, a statement
 168         like <code>SELECT * FROM "table"</cdeo> with fail with the error code
 169         <code>DATA_CANNOT_SELECT_UNFILTERED</code>.</p>
 170
 171         <p>It is also legitimate for the driver to report this error condition as warning, and provide
 172         an empty result set, instead of ungracefull failing.</p>
 173     */
 174     const long DATA_CANNOT_SELECT_UNFILTERED = 550;
 175 };
 176
 177 //=============================================================================
 178
 179 }; }; }; };
 180
 181 //=============================================================================
 182
 183 #endif