KDb

KDbTableSchemaChangeListener.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2017 JarosÅ‚aw Staniek <[email protected]>
3 
4  This program is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License as published by the Free Software Foundation; either
7  version 2 of the License, or (at your option) any later version.
8 
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  Library General Public License for more details.
13 
14  You should have received a copy of the GNU Library General Public License
15  along with this program; see the file COPYING. If not, write to
16  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18 */
19 
20 #ifndef KDB_KDBTABLESCHEMACHANGELISTENER_H
21 
22 #include <kdb_export.h>
23 #include <KDbTristate>
24 
25 class KDbConnection;
26 class KDbQuerySchema;
27 class KDbTableSchema;
28 class KDbTableSchemaChangeListenerPrivate;
29 
30 //! @short An interface allowing to listen for table schema changes
31 /**
32  * The KDbTableSchemaChangeListener class can be used to listen for changes in table schema.
33  * For example query designer window that uses given table schema can be informed about
34  * planned changes and it can be decided about closing the window prior to changes in the schema.
35  */
37 {
38 public:
41 
42  /**
43  * Closes listening object so it will be deleted and thus no longer use a conflicting
44  * table schema. For example if the listening object is a query designer in Kexi
45  * application, the designer window will be closed.
46  * This method can be used to avoid conflicts altering table schema or deleting it.
47  */
48  virtual tristate closeListener() = 0;
49 
50  /**
51  * @return translated string that clearly identifies object that listens for changes
52  * in a given table schema.
53  *
54  * For example it can be a query that uses the table, see KexiQueryPart in Kexi application
55  * and the translated name can be "Query \"abc\"". This friendly identifier can be then
56  * displayed by the application to inform users about objects depending on the table
57  * so users can decide whether to approve schema changes or close the depending windows
58  * to avoid conflicts.
59  *
60  * By default the name string is empty.
61  */
62  QString name() const;
63 
64  /**
65  * @return translated string that clearly identifies object that listens for changes
66  * in a given table schema.
67  *
68  * @see name()
69  */
70  void setName(const QString &name);
71 
72  /** Registers @a listener for receiving (listening) information about changes in table schema
73  * @a table and all tables related to lookup fields. Changes can be related to altering and
74  * removing.
75  */
76  static void registerForChanges(KDbConnection *conn,
78  const KDbTableSchema* table);
79 
80  /**
81  * Registers @a listener for receiving (listening) information about changes in query schema
82  * @a query and all tables that the query uses.
83  *
84  * All tables related to lookup fields of these tables are also checked.
85  * Changes can be related to table altering and removing.
86  */
87  static void registerForChanges(KDbConnection *conn,
89  const KDbQuerySchema* query);
90 
91  /**
92  * Unregisters @a listener for receiving (listening) information about changes
93  * in table schema @a table.
94  */
95  static void unregisterForChanges(KDbConnection *conn,
97  const KDbTableSchema* table);
98 
99  /**
100  * Unregisters all listeners for receiving (listening) information about changes
101  * in table schema @a table.
102  */
103  static void unregisterForChanges(KDbConnection *conn,
104  const KDbTableSchema* table);
105 
106  /**
107  * Unregisters @a listener for receiving (listening) information about changes
108  * in any table or query schema.
109  */
110  static void unregisterForChanges(KDbConnection *conn,
111  KDbTableSchemaChangeListener* listener);
112 
113  /**
114  * Unregisters @a listener for receiving (listening) information about changes
115  * in query schema @a query.
116  */
117  static void unregisterForChanges(KDbConnection *conn,
119  const KDbQuerySchema* query);
120 
121  /**
122  * Unregisters all listeners for receiving (listening) information about changes
123  * in query schema @a query.
124  */
125  static void unregisterForChanges(KDbConnection *conn,
126  const KDbQuerySchema* query);
127 
128  /**
129  * @return list of all table schema listeners registered for receiving (listening)
130  * information about changes in table schema @a table and other tables or queries depending
131  * on @a table.
132  */
134  const KDbTableSchema *table);
135 
136  /**
137  * @return list of all table schema listeners registered for receiving (listening)
138  * information about changes in query @a query and other tables or queries depending on @a query.
139  */
141  const KDbQuerySchema *query);
142 
143  /**
144  * Closes all table schema listeners for table schema @a table except for the ones from
145  * the @a except list.
146  *
147  * See KDbTableSchemaChangeListener::closeListener() for explanation of the operation
148  * of closing listener.
149  *
150  * @return true if all listenters for the table schema @a table have been successfully closed
151  * (returned true) or @c false or @c cancelled if at least one listener returned
152  * @c false or @c cancelled, respectively.
153  * Regardless of returned value, closeListener() is called on all listeners for @a table.
154  */
155  static tristate closeListeners(KDbConnection *conn, const KDbTableSchema* table,
158 
159  /**
160  * Closes all table schema listeners for query schema @a query except for the ones from
161  * the @a except list.
162  *
163  * See KDbTableSchemaChangeListener::closeListener() for explanation of the operation
164  * of closing listener.
165  *
166  * @return true if all listenters for the table schema @a table have been successfully closed
167  * (returned true) or @c false or @c cancelled if at least one listener returned
168  * @c false or @c cancelled, respectively.
169  * Regardless of returned value, closeListener() is called on all listeners for @a table.
170  */
171  static tristate closeListeners(KDbConnection *conn, const KDbQuerySchema* query,
174 
175 private:
176  Q_DISABLE_COPY(KDbTableSchemaChangeListener)
177  KDbTableSchemaChangeListenerPrivate * const d;
178 };
179 
180 #endif
An interface allowing to listen for table schema changes.
3-state logical type with three values: true, false and cancelled and convenient operators.
Definition: KDbTristate.h:100
KDbQuerySchema provides information about database query.
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.