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

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