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