summaryrefslogtreecommitdiff
path: root/offapi/com/sun/star/sdb/ErrorCondition.idl
blob: 4618c7475d77d0b4542cd8d69114f41fa76e0a19 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
/* -*- 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_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 (com::sun::star::sdbc::SQLException::ErrorCode)
    wherever 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
    ErrorCondition 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>

    @code{.java}
    catch ( SQLException e )
    {
        if (e.Message.startsWith( "[OOoBase]" ))
            if (e.ErrorCode + ErrorCondition.SOME_ERROR_CONDITION == 0)
                handleSomeErrorCondition();
    }
    @endcode
 */
constants ErrorCondition
{
    // = section ROW_SET - css.sdb.RowSet related error conditions

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

        <p>This error condition results in raising a RowSetVetoException.</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
        query1 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 <i>MyProfile</i>,  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"</code> 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 ungraceful failing.</p>
    */
    const long DATA_CANNOT_SELECT_UNFILTERED = 550;
};


}; }; }; };


#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */