in preparation of #i84012#:

introduced a dedicated interface (css.sdb.XDatabaseRegistrations) for dealing with data source registrations, this way
hiding the concrete configuration details.

8 files changed, 312 insertions, 107 deletions

diff --git a/offapi/com/sun/star/sdb/DatabaseContext.idl b/offapi/com/sun/star/sdb/DatabaseContext.idl
index e82cce64de3d..9197057ff01a 100644
--- a/offapi/com/sun/star/sdb/DatabaseContext.idl
+++ b/offapi/com/sun/star/sdb/DatabaseContext.idl
@@ -52,6 +52,8 @@
 
  module com {  module sun {  module star {  module sdb {
 
+published interface XDataSourceRegistrations;
+
 /** is the context for accessing datasource.
 
     <p>
@@ -65,12 +67,10 @@
  */
 published service DatabaseContext
 {
-
     /** Enumeration on all registered data sources.
      */
     interface com::sun::star::container::XEnumerationAccess;
 
-
     /** NameAccess on all registered data sources.
         <p>One exception is the <method "com.sun.star.container.XNameAccess">getByName</method>, this method also allows to ask
         for a <member "DataAccessDescriptor">DatabaseLocation</member>.
@@ -89,6 +89,19 @@ published service DatabaseContext
     /** Interface for creation of new datasources.
     */
     interface com::sun::star::lang::XSingleServiceFactory;
+
+    /** allows to access and modify the configuration data for registered data source.
+
+        <p>The main purpose of this interface is to allow you to register data sources which you know
+        by URL only, and have not yet loaded.</p>
+
+        <p>Also, it hides the details of the configuration data where the data source registrations
+        are maintained, so if possible at all, you should use this interface, instead of modifying or
+        querying the configuration data directly.</p>
+
+        @since OpenOffice.org 3.3
+    */
+    [optional] interface XDataSourceRegistrations;
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/sdb/DatabaseRegistrationEvent.idl b/offapi/com/sun/star/sdb/DatabaseRegistrationEvent.idl
new file mode 100644
index 000000000000..3f2a82aa13cb
--- /dev/null
+++ b/offapi/com/sun/star/sdb/DatabaseRegistrationEvent.idl
@@ -0,0 +1,60 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* OpenOffice.org - a multi-platform office productivity suite
+*
+* This file is part of OpenOffice.org.
+*
+* OpenOffice.org is free software: you can redistribute it and/or modify
+* it under the terms of the GNU Lesser General Public License version 3
+* only, as published by the Free Software Foundation.
+*
+* OpenOffice.org is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU Lesser General Public License version 3 for more details
+* (a copy is included in the LICENSE file that accompanied this code).
+*
+* You should have received a copy of the GNU Lesser General Public License
+* version 3 along with OpenOffice.org.  If not, see
+* <http://www.openoffice.org/license.html>
+* for a copy of the LGPLv3 License.
+************************************************************************/
+
+#ifndef __com_sun_star_sdb_DatabaseRegistrationEvent_idl__
+#define __com_sun_star_sdb_DatabaseRegistrationEvent_idl__
+
+#include <com/sun/star/lang/EventObject.idl>
+
+//=============================================================================
+
+module com { module sun { module star { module sdb {
+
+//=============================================================================
+
+/** describes a change in a database registration
+
+    @see XDatabaseRegistrations
+    @see XDatabaseRegistrationsListener
+
+    @since  OpenOffice.org 3.3
+ */
+struct DatabaseRegistrationEvent : ::com::sun::star::lang::EventObject
+{
+    /// is the name of the database registration affected by the event
+    string  Name;
+    /// is the old location of the database which is affected by the event
+    string  OldLocation;
+    /// is the new location of the database which is affected by the event
+    string  NewLocation;
+};
+
+//=============================================================================
+
+}; }; }; };
+
+//=============================================================================
+
+#endif
diff --git a/offapi/com/sun/star/sdb/XDatabaseAccess.idl b/offapi/com/sun/star/sdb/XDatabaseAccess.idl
index a9091be56ce5..61667e73a1af 100644
--- a/offapi/com/sun/star/sdb/XDatabaseAccess.idl
+++ b/offapi/com/sun/star/sdb/XDatabaseAccess.idl
@@ -54,60 +54,17 @@
 
 //=============================================================================
 
-/** is used to connect to a data access bean. A data access bean represents a
-    database connection and provides additional information related to the connection
-    such as forms, reports, or queries.
+/** is not to be used anymore
+    @deprecated
  */
 published interface XDatabaseAccess: com::sun::star::sdbc::XDataSource
 {
-
-    /** indicates that connections already exist.
-        @returns
-            <TRUE/> if so
-     */
     boolean hasConnections();
-    //-------------------------------------------------------------------------
-
-    /** attempts to establish a database connection, that can not be shared with
-        other components. This should be used for transaction processing.
-        @param user
-            the user name
-        @param password
-            the password
-        @returns
-            an isolated connection object
-        @throws com::sun::star::sdbc::SQLException
-            if a database access error occurs.
-        @see com::sun::star::sdbc::XConnection
-     */
     com::sun::star::sdbc::XConnection getIsolatedConnection([in]string user, [in]string password)
       raises (com::sun::star::sdbc::SQLException);
-    //-------------------------------------------------------------------------
-
-    /** closes the all connections to database. This request could be aborted by
-        listeners of the component.
-        @throws com::sun::star::sdbc::SQLException
-            if a database access error occurs.
-     */
     boolean suspendConnections() raises (com::sun::star::sdbc::SQLException);
-    //-------------------------------------------------------------------------
-
-    /** adds the specified listener to receive the events "connectionChanged",
-        "approveConnectionClose", and "connectionClosing".
-        @param  listener
-            the listener to append
-        @see com::sun::star::sdb::XDatabaseAccessListener
-     */
     [oneway] void addDatabaseAccessListener([in]XDatabaseAccessListener listener);
-    //-------------------------------------------------------------------------
-
-    /** removes the specified listener.
-        @param  listener
-            the listener to append
-        @see com::sun::star::sdb::XDatabaseAccessListener
-     */
-    [oneway] void removeDatabaseAccessListener(
-            [in]XDatabaseAccessListener listener);
+    [oneway] void removeDatabaseAccessListener([in]XDatabaseAccessListener listener);
 };
 
 //=============================================================================
diff --git a/offapi/com/sun/star/sdb/XDatabaseAccessListener.idl b/offapi/com/sun/star/sdb/XDatabaseAccessListener.idl
index 1c9361f9da09..2a502f632d86 100644
--- a/offapi/com/sun/star/sdb/XDatabaseAccessListener.idl
+++ b/offapi/com/sun/star/sdb/XDatabaseAccessListener.idl
@@ -37,44 +37,13 @@
  module com {  module sun {  module star {  module sdb {
 
 
-/** is used for receiving "connectionChanged", "approveConnectionClose", and
-    "connectionClosing" events posted by a database access bean.
-
-
-    <p>
-    A database access bean setting may be changed to connect to a different database.
-    In that case, the connection of the bean must be closed and a new connection must
-    be established. The could affect the current data processing on the bean, as it
-    could be shared by a number of components. To prevent the bean from closing it's
-    connection, a DatabaseAccessListener could abort the closing.
-    </p>
+/** is not to be used anymore
+    @deprecated
  */
 published interface XDatabaseAccessListener: com::sun::star::lang::XEventListener
 {
-
-    /** indicates that a new connection for the bean has been established.
-        @param evenet
-            the event happend
-     */
     [oneway] void connectionChanged([in]com::sun::star::lang::EventObject event);
-    //-------------------------------------------------------------------------
-
-    /** indicates that the connection of the bean will be closed. If there are pending
-        actions on the connection of the bean, "approveConnectionClosing" should return
-        <FALSE/>.
-
-        @param evenet
-            the event happend
-        @returns
-            <TRUE/> when approved, otherwise <FALSE/>
-     */
     boolean approveConnectionClosing([in]com::sun::star::lang::EventObject event);
-    //-------------------------------------------------------------------------
-
-    /** indicates that the connection will definitely be closed.
-        @param evenet
-            the event happend
-     */
     [oneway] void connectionClosing([in]com::sun::star::lang::EventObject event);
 };
 
diff --git a/offapi/com/sun/star/sdb/XDatabaseEnvironment.idl b/offapi/com/sun/star/sdb/XDatabaseEnvironment.idl
index 2e7f9b46200c..5cb3aa4832fd 100644
--- a/offapi/com/sun/star/sdb/XDatabaseEnvironment.idl
+++ b/offapi/com/sun/star/sdb/XDatabaseEnvironment.idl
@@ -54,39 +54,14 @@
 
 //=============================================================================
 
-/** specifies the root of the data access beans. It provides the possiblity
-    to open a data access bean, which contains tables, queries, forms, and
-    report documents, or to open a connection to a database.
+/** is not to be used anymore.
 
     @deprecated
  */
 published interface XDatabaseEnvironment: com::sun::star::sdbc::XDriverManager
 {
-    //-------------------------------------------------------------------------
-
-    /** returns an existing DatabaseAccess bean specified by it's URL.
-
-
-        <p>Database Access beans are always shared, so if there's a second request
-        for the same bean, the same instance of the bean will be returned, if it is still alive.
-        </p>
-        @param URL
-            a database url of the form sdbc:subprotocol:subname
-        @returns
-            the database access object for this url
-     */
     XDatabaseAccess getDatabaseAccess([in]string URL)
         raises (com::sun::star::sdbc::SQLException);
-    //-------------------------------------------------------------------------
-
-    /** creates a new DatabaseAccess bean specified by it's URL.
-        @param URL
-            a database url of the form sdbc:subprotocol:subname
-        @param title
-            the title of the database access
-        @returns
-            the new created database access object for this url
-     */
     XDatabaseAccess createDatabaseAccess([in]string URL, [in]string title)
         raises (com::sun::star::sdbc::SQLException);
 };
diff --git a/offapi/com/sun/star/sdb/XDatabaseRegistrations.idl b/offapi/com/sun/star/sdb/XDatabaseRegistrations.idl
new file mode 100644
index 000000000000..ce8e54b8d359
--- /dev/null
+++ b/offapi/com/sun/star/sdb/XDatabaseRegistrations.idl
@@ -0,0 +1,158 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* OpenOffice.org - a multi-platform office productivity suite
+*
+* This file is part of OpenOffice.org.
+*
+* OpenOffice.org is free software: you can redistribute it and/or modify
+* it under the terms of the GNU Lesser General Public License version 3
+* only, as published by the Free Software Foundation.
+*
+* OpenOffice.org is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU Lesser General Public License version 3 for more details
+* (a copy is included in the LICENSE file that accompanied this code).
+*
+* You should have received a copy of the GNU Lesser General Public License
+* version 3 along with OpenOffice.org.  If not, see
+* <http://www.openoffice.org/license.html>
+* for a copy of the LGPLv3 License.
+************************************************************************/
+
+#ifndef __com_sun_star_sdb_XDatabaseRegistrations_idl__
+#define __com_sun_star_sdb_XDatabaseRegistrations_idl__
+
+#include <com/sun/star/container/NoSuchElementException.idl>
+#include <com/sun/star/container/ElementExistException.idl>
+#include <com/sun/star/lang/IllegalArgumentException.idl>
+#include <com/sun/star/lang/IllegalAccessException.idl>
+
+//=============================================================================
+
+module com { module sun { module star { module sdb {
+
+interface XDatabaseRegistrationsListener;
+
+//=============================================================================
+
+/** provides access to the application-wide registered databases.
+
+    <p>This interface provides a mere wrapper around the respective configuration data,
+    this way hiding the concrete configuration structure from its clients. You should,
+    if possible at all, use this interface, instead of modifying or querying the configuration
+    data directly.</p>
+
+    @since OpenOffice.org 3.3
+ */
+interface XDatabaseRegistrations
+{
+    /** determines whether a database is registered under the given name.
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty
+    */
+    boolean hasRegisteredDatabase( [in] string Name )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                );
+
+    /** returns the names of all registered databases
+    */
+    sequence< string >
+            getRegistrationNames();
+
+    /** returns the location of the database registered under the given name
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty
+
+        @throws ::com::sun::star::container::NoSuchElementException
+            if there is no database registered under this name
+    */
+    string  getDatabaseLocation( [in] string Name )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                ,   ::com::sun::star::container::NoSuchElementException
+                );
+
+    /** registers a database, given by location, under a given name
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty, or the given location is invalid.
+
+        @throws ::com::sun::star::container::ElementExistException
+            if there already is a databases registered under the given name.
+    */
+    void    registerDatabaseLocation( [in] string Name, [in] string Location )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                ,   ::com::sun::star::container::ElementExistException
+                );
+
+    /** revokes the registration of a database, given by name
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty
+
+        @throws ::com::sun::star::container::NoSuchElementException
+            if there is no database registered under this name
+
+        @throws ::com::sun::star::lang::IllegalAccessException
+            if the registration data for this database is read-only
+    */
+    void    revokeDatabaseLocation( [in] string Name )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                ,   ::com::sun::star::container::NoSuchElementException
+                ,   ::com::sun::star::lang::IllegalAccessException
+                );
+
+    /** changes the location of a given database registration
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty, or the given location is invalid.
+
+        @throws ::com::sun::star::container::NoSuchElementException
+            if there is no database registered under this name
+
+        @throws ::com::sun::star::lang::IllegalAccessException
+            if the registration data for this database is read-only
+    */
+    void    changeDatabaseLocation( [in] string Name, [in] string NewLocation )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                ,   ::com::sun::star::container::NoSuchElementException
+                ,   ::com::sun::star::lang::IllegalAccessException
+                );
+
+    /** determines whether the registration data for a database given by name is
+        read-only.
+
+        <p>In this case, attempts to revoke this registration will fail.</p>
+
+        @throws ::com::sun::star::lang::IllegalArgumentException
+            if the given name is empty
+
+        @throws ::com::sun::star::container::NoSuchElementException
+            if there is no database registered under this name
+    */
+    boolean isDatabaseRegistrationReadOnly( [in] string Name )
+        raises  (   ::com::sun::star::lang::IllegalArgumentException
+                ,   ::com::sun::star::container::NoSuchElementException
+                );
+
+    /** registers a listener which is notified of changes in the registered databases
+    */
+    void    addDatabaseRegistrationsListener( [in] XDatabaseRegistrationsListener Listener );
+
+    /** revokes a previously registered listener
+    */
+    void    removeDatabaseRegistrationsListener( [in] XDatabaseRegistrationsListener Listener );
+};
+
+//=============================================================================
+
+}; }; }; };
+
+//=============================================================================
+
+#endif
diff --git a/offapi/com/sun/star/sdb/XDatabaseRegistrationsListener.idl b/offapi/com/sun/star/sdb/XDatabaseRegistrationsListener.idl
new file mode 100644
index 000000000000..f5fc65513d6e
--- /dev/null
+++ b/offapi/com/sun/star/sdb/XDatabaseRegistrationsListener.idl
@@ -0,0 +1,70 @@
+/*************************************************************************
+* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+*
+* Copyright 2009 by Sun Microsystems, Inc.
+*
+* OpenOffice.org - a multi-platform office productivity suite
+*
+* This file is part of OpenOffice.org.
+*
+* OpenOffice.org is free software: you can redistribute it and/or modify
+* it under the terms of the GNU Lesser General Public License version 3
+* only, as published by the Free Software Foundation.
+*
+* OpenOffice.org is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU Lesser General Public License version 3 for more details
+* (a copy is included in the LICENSE file that accompanied this code).
+*
+* You should have received a copy of the GNU Lesser General Public License
+* version 3 along with OpenOffice.org.  If not, see
+* <http://www.openoffice.org/license.html>
+* for a copy of the LGPLv3 License.
+************************************************************************/
+
+#ifndef __com_sun_star_sdb_XDatabaseRegistrationsListener_idl__
+#define __com_sun_star_sdb_XDatabaseRegistrationsListener_idl__
+
+#include <com/sun/star/lang/XEventListener.idl>
+#include <com/sun/star/sdb/DatabaseRegistrationEvent.idl>
+
+//=============================================================================
+
+module com { module sun { module star { module sdb {
+
+//=============================================================================
+
+/** implemented by components which want to be notified of changes in the application-wide registered
+    databases.
+
+    @see XDatabaseRegistrations
+
+    @since OpenOffice.org 3.3
+ */
+interface XDatabaseRegistrationsListener : ::com::sun::star::lang::XEventListener
+{
+    /** called when a database has been registered
+    */
+    void    registeredDatabaseLocation( [in] DatabaseRegistrationEvent Event );
+
+    /** called when a database registration has been revoked
+    */
+    void    revokedDatabaseLocation( [in] DatabaseRegistrationEvent Event );
+
+    /** called when a the location of a registered database changed
+
+        <p>Note that this talks about registration data only. That is, if the actual file denoted by the database
+        registration is moved, this is in no way monitored or reported. Only (successful) calls to
+        <member>XDatabaseRegistrations::changeDatabaseLocation</member> are reported here.</p>
+    */
+    void    changedDatabaseLocation( [in] DatabaseRegistrationEvent Event );
+};
+
+//=============================================================================
+
+}; }; }; };
+
+//=============================================================================
+
+#endif
diff --git a/offapi/com/sun/star/sdb/makefile.mk b/offapi/com/sun/star/sdb/makefile.mk
index b535584fc4b8..3e76283ecf18 100644
--- a/offapi/com/sun/star/sdb/makefile.mk
+++ b/offapi/com/sun/star/sdb/makefile.mk
@@ -62,6 +62,7 @@ IDLFILES=\
     DatabaseContext.idl \
     DatabaseDocument.idl \
     DatabaseEnvironment.idl \
+    DatabaseRegistrationEvent.idl \
     DataColumn.idl \
     DataSettings.idl \
     DataSource.idl \
@@ -113,6 +114,8 @@ IDLFILES=\
     XDataAccessDescriptorFactory.idl \
     XDatabaseAccess.idl \
     XDatabaseAccessListener.idl \
+    XDatabaseRegistrations.idl \
+    XDatabaseRegistrationsListener.idl \
     XDatabaseEnvironment.idl \
     XDocumentDataSource.idl \
     XFormDocumentsSupplier.idl \