| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| |
| #ifndef __com_sun_star_sdb_tools_XObjectNames_idl__ |
| #define __com_sun_star_sdb_tools_XObjectNames_idl__ |
| |
| #ifndef __com_sun_star_lang_IllegalArgumentException_idl__ |
| #include <com/sun/star/lang/IllegalArgumentException.idl> |
| #endif |
| |
| #ifndef __com_sun_star_sdbc_SQLException_idl__ |
| #include <com/sun/star/sdbc/SQLException.idl> |
| #endif |
| |
| //============================================================================= |
| module com { module sun { module star { module sdb { module tools { |
| //============================================================================= |
| |
| //----------------------------------------------------------------------------- |
| /** encapsulates functionality which you might find useful when writing a |
| database application which deals with query and table names. |
| |
| <p>The most important task fulfilled by this instance is that it hides |
| different naming restrictions from you, which are caused by server-side |
| or client side specialities.</p> |
| |
| <p>For instance, it can validate names against |
| the characters allowed in the object names of a connection. Also, it |
| relieves you from caring whether a database supports queries in a <code>SELECT</code> |
| statment's <code>FROM</code> part (known as "queries in queries"). In such |
| databases, query and table names share a common namespace, thus they must be |
| unique. Using this interface, you can easily ensure this uniqueness.</p> |
| |
| <p>All of the functionality present in this interface depends on a connection, |
| thus it entry point for obtaining it is a <type scope="com::sun::star::sdb">Connection</type> |
| service.</p> |
| |
| <p>The component itself does not have life-time control mechanimns, i.e. you |
| cannot explicitly dispose it (<member scope="com::sun::star::lang">XComponent::dispose</member>), |
| and you cannot be notified when it dies.<br/> |
| However, if your try to access any of its methods or attributes, after the |
| connection which was used to create it was closed, a <type scope="com::sun::star::lang">DisposedException</type> |
| will be thrown.</p> |
| |
| @see XConnectionTools |
| |
| @since OpenOffice 2.0.4 |
| */ |
| published interface XObjectNames |
| { |
| /** suggests a (unique) table or query name |
| |
| <p>If in the database, tables and queries share a common namespace, this will be respected |
| by this function.</p> |
| |
| <p>Note that in an multi-threaded environment, the name you obtain here is not absolutely |
| guaranteed to be unique. It is unique at the very moment the function returns to you. |
| But already when you evaluate the returned value, it might not be uniquey anymore, if |
| another process or thread created a query or table with this name.</p> |
| |
| <p>This implies that you cannot rely on the name's uniqueness, but you can use it as |
| first guess to present to the user. In most cases, it will still be sufficient when |
| you are actually creating the table respectively query.</p> |
| |
| @param CommandType |
| specifies the <type scope="com::sun::star::sdb">CommandType</type> of the object for which |
| a unique name is to be generated. Must be either <member scope="com::sun::star::sdb">CommandType::TABLE</member> |
| or <member scope="com::sun::star::sdb">CommandType::QUERY</member>. |
| |
| @param BaseName |
| specifies the base of the to-be-created object name. If empty, a default |
| base name will be used. |
| |
| @throws com::sun::star::lang::IllegalArgumentException |
| if <arg>CommandType</arg> specifies an invalid command type. |
| */ |
| string suggestName( [in] long CommandType, [in] string BaseName ) |
| raises ( com::sun::star::lang::IllegalArgumentException ); |
| |
| /** converts the given object name to a name which is valid in the database. |
| |
| <p>The conversion takes place by converting every character which is neither |
| allowed by the SQL-92 standard, nor part of the special characters supported |
| by the database, with an underscore character (_).</p> |
| |
| @see com::sun::star::sdbc::XDatabaseMetaData::getExtraNameCharacters |
| */ |
| string convertToSQLName( [in] string Name ); |
| |
| /** checks whether a given name is used as table respectively query name in the database. |
| |
| <p>If in the database, tables and queries share a common namespace, this will be respected |
| by this function.</p> |
| |
| <p>As before, the information you obtain by calling this method might be obsolete |
| in the very moment you evaluate this, in case another process or thread interferes. |
| However, it's usually sufficiently up-to-date for purpose of using it in a database |
| application driven by user interactions.</p> |
| |
| @param CommandType |
| specifies the <type scope="com::sun::star::sdb">CommandType</type> of the object whose |
| name should be checked. Must be either <member scope="com::sun::star::sdb">CommandType::TABLE</member> |
| or <member scope="com::sun::star::sdb">CommandType::QUERY</member>. |
| |
| @param Name |
| specifies the to-be-checked name of the object. |
| |
| @return |
| <TRUE/> if and only if the given name is legitimate as table respectively query name |
| to be used in the database. |
| |
| @throws com::sun::star::lang::IllegalArgumentException |
| if <arg>CommandType</arg> specifies an invalid command type. |
| |
| @see checkNameIsUsed |
| */ |
| boolean isNameUsed( [in] long CommandType, [in] string Name ) |
| raises ( com::sun::star::lang::IllegalArgumentException ); |
| |
| /** checks whether a given name is valid as table or query name |
| |
| <p>For tables, the name must consist of characters allowed by the SQL-92 standard, |
| plus characters allowed by the connection as extra name characters.</p> |
| |
| <p>For queries, names are nearly arbitrary, except that usual quoting characters |
| must not be part of the name.</p> |
| |
| @see com::sun::star::sdbc::XDatabaseMetaData::getExtraNameCharacters |
| */ |
| boolean isNameValid( [in] long CommandType, [in] string Name ) |
| raises ( com::sun::star::lang::IllegalArgumentException ); |
| |
| /** checks whether a given name is allowed for a to-be-created table or query in the |
| database. |
| |
| <p>This method basically does the same checks as <member>isNameUsed</member> and |
| <member>isNameValid</member>. In case the given name is not allowed, it throws an |
| exception. This error can be presented to the user, to give it a common experience |
| in all cases where he's required to enter an object name.</p> |
| |
| @see isNameUsed |
| @see isNameValid |
| @see com::sun::star::sdb::ErrorMessageDialog |
| @see com::sun::star::sdb::InteractionHandler |
| */ |
| void checkNameForCreate( [in] long CommandType, [in] string Name ) |
| raises ( com::sun::star::sdbc::SQLException ); |
| }; |
| |
| //============================================================================= |
| }; }; }; }; }; |
| //============================================================================= |
| |
| #endif |
| |