1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_sdb_tools_XObjectNames_idl__
25#define __com_sun_star_sdb_tools_XObjectNames_idl__
26
27#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
28#include <com/sun/star/lang/IllegalArgumentException.idl>
29#endif
30
31#ifndef __com_sun_star_sdbc_SQLException_idl__
32#include <com/sun/star/sdbc/SQLException.idl>
33#endif
34
35//=============================================================================
36module com {  module sun {  module star {  module sdb { module tools {
37//=============================================================================
38
39//-----------------------------------------------------------------------------
40/** encapsulates functionality which you might find useful when writing a
41    database application which deals with query and table names.
42
43    <p>The most important task fulfilled by this instance is that it hides
44    different naming restrictions from you, which are caused by server-side
45    or client side specialities.</p>
46
47    <p>For instance, it can validate names against
48    the characters allowed in the object names of a connection. Also, it
49    relieves you from caring whether a database supports queries in a <code>SELECT</code>
50    statment's <code>FROM</code> part (known as "queries in queries"). In such
51    databases, query and table names share a common namespace, thus they must be
52    unique. Using this interface, you can easily ensure this uniqueness.</p>
53
54    <p>All of the functionality present in this interface depends on a connection,
55    thus it entry point for obtaining it is a <type scope="com::sun::star::sdb">Connection</type>
56    service.</p>
57
58    <p>The component itself does not have life-time control mechanimns, i.e. you
59    cannot explicitly dispose it (<member scope="com::sun::star::lang">XComponent::dispose</member>),
60    and you cannot be notified when it dies.<br/>
61    However, if your try to access any of its methods or attributes, after the
62    connection which was used to create it was closed, a <type scope="com::sun::star::lang">DisposedException</type>
63    will be thrown.</p>
64
65    @see XConnectionTools
66
67    @since OpenOffice 2.0.4
68*/
69published interface XObjectNames
70{
71    /** suggests a (unique) table or query name
72
73        <p>If in the database, tables and queries share a common namespace, this will be respected
74        by this function.</p>
75
76        <p>Note that in an multi-threaded environment, the name you obtain here is not absolutely
77        guaranteed to be unique. It is unique at the very moment the function returns to you.
78        But already when you evaluate the returned value, it might not be uniquey anymore, if
79        another process or thread created a query or table with this name.</p>
80
81        <p>This implies that you cannot rely on the name's uniqueness, but you can use it as
82        first guess to present to the user. In most cases, it will still be sufficient when
83        you are actually creating the table respectively query.</p>
84
85        @param CommandType
86            specifies the <type scope="com::sun::star::sdb">CommandType</type> of the object for which
87            a unique name is to be generated. Must be either <member scope="com::sun::star::sdb">CommandType::TABLE</member>
88            or <member scope="com::sun::star::sdb">CommandType::QUERY</member>.
89
90        @param BaseName
91            specifies the base of the to-be-created object name. If empty, a default
92            base name will be used.
93
94        @throws com::sun::star::lang::IllegalArgumentException
95            if <arg>CommandType</arg> specifies an invalid command type.
96    */
97    string  suggestName( [in] long CommandType, [in] string BaseName )
98        raises ( com::sun::star::lang::IllegalArgumentException );
99
100    /** converts the given object name to a name which is valid in the database.
101
102        <p>The conversion takes place by converting every character which is neither
103        allowed by the SQL-92 standard, nor part of the special characters supported
104        by the database, with an underscore character (_).</p>
105
106        @see com::sun::star::sdbc::XDatabaseMetaData::getExtraNameCharacters
107    */
108    string  convertToSQLName( [in] string Name );
109
110    /** checks whether a given name is used as table respectively query name in the database.
111
112        <p>If in the database, tables and queries share a common namespace, this will be respected
113        by this function.</p>
114
115        <p>As before, the information you obtain by calling this method might be obsolete
116        in the very moment you evaluate this, in case another process or thread interferes.
117        However, it's usually sufficiently up-to-date for purpose of using it in a database
118        application driven by user interactions.</p>
119
120        @param CommandType
121            specifies the <type scope="com::sun::star::sdb">CommandType</type> of the object whose
122            name should be checked. Must be either <member scope="com::sun::star::sdb">CommandType::TABLE</member>
123            or <member scope="com::sun::star::sdb">CommandType::QUERY</member>.
124
125        @param Name
126            specifies the to-be-checked name of the object.
127
128        @return
129            <TRUE/> if and only if the given name is legitimate as table respectively query name
130            to be used in the database.
131
132        @throws com::sun::star::lang::IllegalArgumentException
133            if <arg>CommandType</arg> specifies an invalid command type.
134
135        @see checkNameIsUsed
136    */
137    boolean isNameUsed( [in] long CommandType, [in] string Name )
138        raises ( com::sun::star::lang::IllegalArgumentException );
139
140    /** checks whether a given name is valid as table or query name
141
142        <p>For tables, the name must consist of characters allowed by the SQL-92 standard,
143        plus characters allowed by the connection as extra name characters.</p>
144
145        <p>For queries, names are nearly arbitrary, except that usual quoting characters
146        must not be part of the name.</p>
147
148        @see com::sun::star::sdbc::XDatabaseMetaData::getExtraNameCharacters
149    */
150    boolean isNameValid( [in] long CommandType, [in] string Name )
151        raises ( com::sun::star::lang::IllegalArgumentException );
152
153    /** checks whether a given name is allowed for a to-be-created table or query in the
154        database.
155
156        <p>This method basically does the same checks as <member>isNameUsed</member> and
157        <member>isNameValid</member>. In case the given name is not allowed, it throws an
158        exception. This error can be presented to the user, to give it a common experience
159        in all cases where he's required to enter an object name.</p>
160
161        @see isNameUsed
162        @see isNameValid
163        @see com::sun::star::sdb::ErrorMessageDialog
164        @see com::sun::star::sdb::InteractionHandler
165    */
166    void    checkNameForCreate( [in] long CommandType, [in] string Name )
167            raises ( com::sun::star::sdbc::SQLException );
168};
169
170//=============================================================================
171}; }; }; }; };
172//=============================================================================
173
174#endif
175
176