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