From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001
From: Daniel Baumann Most of the functionality provided here is meaningful only relative to
+ a given database connection. For instance, for quoting table names, you need
+ the meta data instance of the connection. Thus, the entry point for obtaining
+ a XConnectionTools instance is the
+ com::sun::star::sdb::Connection service. Note that nearly all functionality provided by this interface is also
+ available by other means, it's only provided here for convenience purposes. The returned object is guaranteed to not be `NULL`. The returned object is guaranteed to not be `NULL`. A command descriptor here means:
+
+
FROM
+ part of a SELECT
statement.
+ */
+ boolean supportsQueriesInFrom() raises ( com::sun::star::sdbc::SQLException );
+};
+
+}; }; }; }; };
+
+#endif
+
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/offapi/com/sun/star/sdb/tools/XIndexAlteration.idl b/offapi/com/sun/star/sdb/tools/XIndexAlteration.idl
new file mode 100644
index 000000000..7cd7b240f
--- /dev/null
+++ b/offapi/com/sun/star/sdb/tools/XIndexAlteration.idl
@@ -0,0 +1,75 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * 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 .
+ */
+
+#ifndef __com_sun_star_sdb_tools_XIndexAlteration_idl__
+#define __com_sun_star_sdb_tools_XIndexAlteration_idl__
+
+#include 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 specialties.
+ +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 SELECT
+ statement's FROM
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.
All of the functionality present in this interface depends on a connection, + thus it entry point for obtaining it is a com::sun::star::sdb::Connection + service.
+ +The component itself does not have life-time control mechanisms, i.e. you
+ cannot explicitly dispose it (com::sun::star::lang::XComponent::dispose()),
+ and you cannot be notified when it dies.
+ However, if your try to access any of its methods or attributes, after the
+ connection which was used to create it was closed, a com::sun::star::lang::DisposedException
+ will be thrown.
If in the database, tables and queries share a common namespace, this will be respected + by this function.
+ +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 unique anymore, if + another process or thread created a query or table with this name.
+ +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.
+ + @param CommandType + specifies the com::sun::star::sdb::CommandType of the object for which + a unique name is to be generated. Must be either com::sun::star::sdb::CommandType::TABLE + or com::sun::star::sdb::CommandType::QUERY. + + @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 CommandType specifies an invalid command type. + */ + string suggestName( [in] long CommandType, [in] string BaseName ) + raises ( com::sun::star::lang::IllegalArgumentException, + com::sun::star::sdbc::SQLException ); + + /** converts the given object name to a name which is valid in the database. + +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 (_).
+ + @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. + +If in the database, tables and queries share a common namespace, this will be respected + by this function.
+ +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.
+ + @param CommandType + specifies the com::sun::star::sdb::CommandType of the object whose + name should be checked. Must be either com::sun::star::sdb::CommandType::TABLE + or com::sun::star::sdb::CommandType::QUERY. + + @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 CommandType specifies an invalid command type. + + @see checkNameIsUsed + */ + boolean isNameUsed( [in] long CommandType, [in] string Name ) + raises ( com::sun::star::lang::IllegalArgumentException, + com::sun::star::sdbc::SQLException ); + + /** checks whether a given name is valid as table or query name + +For tables, the name must consist of characters allowed by the SQL-92 standard, + plus characters allowed by the connection as extra name characters.
+ +For queries, names are nearly arbitrary, except that usual quoting characters + must not be part of the name.
+ + @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. + +This method basically does the same checks as isNameUsed() and + isNameValid(). 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.
+ + @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 + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ diff --git a/offapi/com/sun/star/sdb/tools/XTableAlteration.idl b/offapi/com/sun/star/sdb/tools/XTableAlteration.idl new file mode 100644 index 000000000..76ea4d5cf --- /dev/null +++ b/offapi/com/sun/star/sdb/tools/XTableAlteration.idl @@ -0,0 +1,94 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * 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 . + */ + +#ifndef __com_sun_star_sdb_tools_XTableAlteration_idl__ +#define __com_sun_star_sdb_tools_XTableAlteration_idl__ + +#includeWhen, in a database application, dealing with table names, there's many degrees
+ of freedom to deal with. For instance, suppose you want to have the full name of a
+ table object, as it should be used in a SELECT
statement's FROM
+ part. This requires you to evaluate whether or not the table has a catalog and/or schema
+ name, to combine the catalog, the schema, and the basic table name into one name, respecting
+ the database's quoting character, and the order in which all those parts should be combined.
+ Additionally, you have to respect the client-side settings which tell OpenOffice.org
+ to use or not use catalogs and schemas in SELECT
at all.
The XTableName interface eases this and other, similar tasks around table + names.
+ +The component itself does not have life-time control mechanisms, i.e. you
+ cannot explicitly dispose it (com::sun::star::lang::XComponent::dispose()),
+ and you cannot be notified when it dies.
+ However, if your try to access any of its methods or attributes, after the
+ connection which was used to create it was closed, a com::sun::star::lang::DisposedException
+ will be thrown.
SELECT
statement.
+
+ On a per-data-source basis, OpenOffice.org allows to override database meta
+ data information in that you can specify to not use catalog and or schema names
+ in SELECT
statements. Using this attribute, you can generate a table
+ name which respects those settings.
Retrieving this attribute is equivalent to obtaining the tables + container from the connection (via com::sun::star::sdbcx::XTablesSupplier), + and calling its com::sun::star::container::XNameAccess::getByName() + method with the ComposedName.
+ + @throws com::sun::star::container::NoSuchElementException + if, upon getting the attribute value, the current composed table name + represented by this instance does not denote an existing table in the database. + @throws com::sun::star::lang::IllegalArgumentException + if you try to set an object which does not denote a table from the underlying + database. + */ + [attribute] ::com::sun::star::beans::XPropertySet Table + { + get raises ( com::sun::star::container::NoSuchElementException ); + set raises ( com::sun::star::lang::IllegalArgumentException ); + }; +}; + +}; }; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ diff --git a/offapi/com/sun/star/sdb/tools/XTableRename.idl b/offapi/com/sun/star/sdb/tools/XTableRename.idl new file mode 100644 index 000000000..d6e955581 --- /dev/null +++ b/offapi/com/sun/star/sdb/tools/XTableRename.idl @@ -0,0 +1,57 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * 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 . + */ + +#ifndef __com_sun_star_sdb_tools_XTableRename_idl__ +#define __com_sun_star_sdb_tools_XTableRename_idl__ + +#include