File indexing completed on 2024-03-24 16:11:22

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org>
0003 
0004    This program is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This program is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this program; see the file COPYING.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KDB_KDBTABLESCHEMACHANGELISTENER_H
0021 
0022 #include <kdb_export.h>
0023 #include <KDbTristate>
0024 
0025 class KDbConnection;
0026 class KDbQuerySchema;
0027 class KDbTableSchema;
0028 class KDbTableSchemaChangeListenerPrivate;
0029 
0030 //! @short An interface allowing to listen for table schema changes
0031 /**
0032  * The KDbTableSchemaChangeListener class can be used to listen for changes in table schema.
0033  * For example query designer window that uses given table schema can be informed about
0034  * planned changes and it can be decided about closing the window prior to changes in the schema.
0035  */
0036 class KDB_EXPORT KDbTableSchemaChangeListener
0037 {
0038 public:
0039     KDbTableSchemaChangeListener();
0040     virtual ~KDbTableSchemaChangeListener();
0041 
0042     /**
0043      * Closes listening object so it will be deleted and thus no longer use a conflicting
0044      * table schema. For example if the listening object is a query designer in Kexi
0045      * application, the designer window will be closed.
0046      * This method can be used to avoid conflicts altering table schema or deleting it.
0047      */
0048     virtual tristate closeListener() = 0;
0049 
0050     /**
0051      * @return translated string that clearly identifies object that listens for changes
0052      * in a given table schema.
0053      *
0054      * For example it can be a query that uses the table, see KexiQueryPart in Kexi application
0055      * and the translated name can be "Query \"abc\"". This friendly identifier can be then
0056      * displayed by the application to inform users about objects depending on the table
0057      * so users can decide whether to approve schema changes or close the depending windows
0058      * to avoid conflicts.
0059      *
0060      * By default the name string is empty.
0061      */
0062     QString name() const;
0063 
0064     /**
0065      * @return translated string that clearly identifies object that listens for changes
0066      * in a given table schema.
0067      *
0068      * @see name()
0069      */
0070     void setName(const QString &name);
0071 
0072     /** Registers @a listener for receiving (listening) information about changes in table schema
0073      * @a table and all tables related to lookup fields. Changes can be related to altering and
0074      * removing.
0075      */
0076     static void registerForChanges(KDbConnection *conn,
0077                                    KDbTableSchemaChangeListener* listener,
0078                                    const KDbTableSchema* table);
0079 
0080     /**
0081      * Registers @a listener for receiving (listening) information about changes in query schema
0082      * @a query and all tables that the query uses.
0083      *
0084      * All tables related to lookup fields of these tables are also checked.
0085      * Changes can be related to table altering and removing.
0086      */
0087     static void registerForChanges(KDbConnection *conn,
0088                                    KDbTableSchemaChangeListener* listener,
0089                                    const KDbQuerySchema* query);
0090 
0091     /**
0092      * Unregisters @a listener for receiving (listening) information about changes
0093      * in table schema @a table.
0094      */
0095     static void unregisterForChanges(KDbConnection *conn,
0096                                      KDbTableSchemaChangeListener* listener,
0097                                      const KDbTableSchema* table);
0098 
0099     /**
0100      * Unregisters all listeners for receiving (listening) information about changes
0101      * in table schema @a table.
0102      */
0103     static void unregisterForChanges(KDbConnection *conn,
0104                                      const KDbTableSchema* table);
0105 
0106     /**
0107      * Unregisters @a listener for receiving (listening) information about changes
0108      * in any table or query schema.
0109      */
0110     static void unregisterForChanges(KDbConnection *conn,
0111                                      KDbTableSchemaChangeListener* listener);
0112 
0113     /**
0114      * Unregisters @a listener for receiving (listening) information about changes
0115      * in query schema @a query.
0116      */
0117     static void unregisterForChanges(KDbConnection *conn,
0118                                      KDbTableSchemaChangeListener* listener,
0119                                      const KDbQuerySchema* query);
0120 
0121     /**
0122      * Unregisters all listeners for receiving (listening) information about changes
0123      * in query schema @a query.
0124      */
0125     static void unregisterForChanges(KDbConnection *conn,
0126                                      const KDbQuerySchema* query);
0127 
0128     /**
0129      * @return list of all table schema listeners registered for receiving (listening)
0130      * information about changes in table schema @a table and other tables or queries depending
0131      * on @a table.
0132      */
0133     static QList<KDbTableSchemaChangeListener *> listeners(KDbConnection *conn,
0134                                                            const KDbTableSchema *table);
0135 
0136     /**
0137      * @return list of all table schema listeners registered for receiving (listening)
0138      * information about changes in query @a query and other tables or queries depending on @a query.
0139      */
0140     static QList<KDbTableSchemaChangeListener *> listeners(KDbConnection *conn,
0141                                                            const KDbQuerySchema *query);
0142 
0143     /**
0144      * Closes all table schema listeners for table schema @a table except for the ones from
0145      * the @a except list.
0146      *
0147      * See KDbTableSchemaChangeListener::closeListener() for explanation of the operation
0148      * of closing listener.
0149      *
0150      * @return true if all listenters for the table schema @a table have been successfully closed
0151      * (returned true) or @c false or @c cancelled if at least one listener returned
0152      * @c false or @c cancelled, respectively.
0153      * Regardless of returned value, closeListener() is called on all listeners for @a table.
0154      */
0155     static tristate closeListeners(KDbConnection *conn, const KDbTableSchema* table,
0156                                    const QList<KDbTableSchemaChangeListener*> &except
0157                                        = QList<KDbTableSchemaChangeListener*>());
0158 
0159     /**
0160      * Closes all table schema listeners for query schema @a query except for the ones from
0161      * the @a except list.
0162      *
0163      * See KDbTableSchemaChangeListener::closeListener() for explanation of the operation
0164      * of closing listener.
0165      *
0166      * @return true if all listenters for the table schema @a table have been successfully closed
0167      * (returned true) or @c false or @c cancelled if at least one listener returned
0168      * @c false or @c cancelled, respectively.
0169      * Regardless of returned value, closeListener() is called on all listeners for @a table.
0170      */
0171     static tristate closeListeners(KDbConnection *conn, const KDbQuerySchema* query,
0172                                    const QList<KDbTableSchemaChangeListener*> &except
0173                                        = QList<KDbTableSchemaChangeListener*>());
0174 
0175 private:
0176     Q_DISABLE_COPY(KDbTableSchemaChangeListener)
0177     KDbTableSchemaChangeListenerPrivate * const d;
0178 };
0179 
0180 #endif