xref: /aoo4110/main/offapi/com/sun/star/sdb/ErrorCondition.idl (revision b1cdbd2c)

/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/



#ifndef __com_sun_star_sdb_ErrorCondition_idl__
#define __com_sun_star_sdb_ErrorCondition_idl__

//=============================================================================

module com { module sun { module star { module sdb {

//=============================================================================

/** defines error conditions for OpenOffice.org Base core components

    <p>Core components of OpenOffice.org will use those error conditions
    as error codes (<member scope="com::sun::star::sdbc">SQLException::ErrorCode</member>)
    whereever possible.<br/>
    That is, if an <code>SQLException</code> is raised by
    such a component, caused by an error condition which is included in the
    <type>ErrorCondition</type> group, then the respective <em>negative</em> value
    will be used as <code>ErrorCode</code>.</p>

    <p>This allows to determine specific error conditions in your client code, and
    to handle it appropriately.</p>

    <p>Note that before you examine the <code>ErrorCode</code> member of a caught
    <code>SQLException</code>, you need to make sure that the exception
    is really thrown by an OpenOffice.org Base core component. To do so, check
    whether the error message (<code>Exception::Message</code>) starts with the
    vendor string <code>[OOoBase]</code>.</p>

    <p>The list of defined error conditions, by nature, is expected to permanently grow,
    so never assume it being finalized.</p>

    @example Java
    <listing>
    catch ( SQLException e )
    {
    &nbsp;&nbsp;if ( e.Message.startsWith( "[OOoBase]" ) )
    &nbsp;&nbsp;&nbsp;&nbsp;if ( e.ErrorCode + ErrorCondition.SOME_ERROR_CONDITION == 0 )
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;handleSomeErrorCondition();
    }
    </listing>
 */
constants ErrorCondition
{
    // ========================================================================
    // = section ROW_SET - css.sdb.RowSet related error conditions

    /** is used by and <type>RowSet</type> to indicate that an operation has been vetoed
        by one of its approval listeners

        <p>This error condition results in raising a <type>RowSetVetoException</type>.</p>
        @see RowSet
        @see XRowSetApproveBroadcaster
        @see XRowSetApproveListener
    */
	const long ROW_SET_OPERATION_VETOED = 100;

    // ========================================================================
    // = section PARSER - parsing related error conditions

    /** indicates that while parsing an SQL statement, cyclic sub queries have been detected.

        <p>Imagine you have a client-side query <code>SELECT * FROM table</code>, which is
        saved as &quot;query1&quot;. Additionally, there is a query &quot;query2&quot; defined
        as <code>SELECT * FROM query1</code>. Now if you try to change the statement of
        <type>query1</type> to <code>SELECT * FROM query2</code>, this is prohibited, because
        it would lead to a cyclic sub query.
    */
    const long PARSER_CYCLIC_SUB_QUERIES = 200;

    // ========================================================================
    // = section DB - application-level error conditions
    // =
    // = next section should start with 500

    /** indicates that the name of a client side database object - a query, a form,
        or a report - contains one or more slashes, which is forbidden.
    */
    const long DB_OBJECT_NAME_WITH_SLASHES = 300;

    /** indicates that an identifier is not SQL conform.
    */
    const long DB_INVALID_SQL_NAME = 301;

    /** indicates that the name of a query contains quote characters.

        <p>This error condition is met when the user attempts to save a query
        with a name which contains one of the possible database quote characters.
        This is an error since query names can potentially be used in
        <code>SELECT</code> statements, where quote identifiers would render the statement invalid.</p>

        @see com::sun::star::sdb::tools::XDataSourceMetaData::supportsQueriesInFrom
    */
    const long DB_QUERY_NAME_WITH_QUOTES = 302;

    /** indicates that an attempt was made to save a database object under a name
        which is already used in the database.

        <p>In databases which support query names to appear in <code>SELECT</code>
        statements, this could mean that a table was attempted to be saved with the
        name of an existing query, or vice versa.</p>

        <p>Otherwise, it means an object was attempted to be saved with the
        name of an already existing object of the same type.</p>

        @see com::sun::star::sdb::application::DatabaseObject
        @see com::sun::star::sdb::tools::XDataSourceMetaData::supportsQueriesInFrom
    */
    const long DB_OBJECT_NAME_IS_USED = 303;

    /** indicates an operation was attempted which needs a connection to the
        database, which did not exist at that time.
    */
    const long DB_NOT_CONNECTED = 304;

    // ========================================================================
    // = section AB - address book access related error conditions
    // =
    // = next section should start with 550

    /** used by the component implementing address book access to indicate that a requested address book could
        not be accessed.

        <p>For instance, this error code is used when you try to access the address book
        in a Thunderbird profile named <q>MyProfile</q>,  but there does not exist a profile
        with this name.</p>
    */
    const long AB_ADDRESSBOOK_NOT_FOUND = 500;

    // ========================================================================
    // = section DATA - data retrieval related error conditions
    // =
    // = next section should start with 600

    /** used to indicate that a <code>SELECT</code> operation on a table needs a filter.

        <p>Some database drivers are not able to <code>SELECT</code> from a table if the
        statement does not contain a <code>WHERE</code> clause. In this case, a statement
        like <code>SELECT * FROM "table"</cdeo> with fail with the error code
        <code>DATA_CANNOT_SELECT_UNFILTERED</code>.</p>

        <p>It is also legitimate for the driver to report this error condition as warning, and provide
        an empty result set, instead of ungracefull failing.</p>
    */
    const long DATA_CANNOT_SELECT_UNFILTERED = 550;
};

//=============================================================================

}; }; }; };

//=============================================================================

#endif