Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 164 insertions, 0 deletions

diff --git a/offapi/com/sun/star/sdb/tools/XObjectNames.idl b/offapi/com/sun/star/sdb/tools/XObjectNames.idl
new file mode 100644
index 000000000..a82bd59a8
--- /dev/null
+++ b/offapi/com/sun/star/sdb/tools/XObjectNames.idl
@@ -0,0 +1,164 @@
+/* -*- 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_XObjectNames_idl__
+#define __com_sun_star_sdb_tools_XObjectNames_idl__
+
+#include <com/sun/star/lang/IllegalArgumentException.idl>
+#include <com/sun/star/sdbc/SQLException.idl>
+
+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 specialties.</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>
+    statement'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 com::sun::star::sdb::Connection
+    service.</p>
+
+    <p>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.<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 com::sun::star::lang::DisposedException
+    will be thrown.</p>
+
+    @see XConnectionTools
+
+    @since OOo 2.0.4
+*/
+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 unique 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 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.
+
+        <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 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
+
+        <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 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.</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
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */