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