KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > sql > depend > DependencyManager

1 /*
3    Derby - Class org.apache.derby.iapi.sql.depend.DependencyManager
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
20  */

22 package org.apache.derby.iapi.sql.depend;
24 import;
26 import org.apache.derby.iapi.error.StandardException;
28 import org.apache.derby.iapi.sql.conn.LanguageConnectionContext;
30 import;
32 /**
33     Dependency Manager Interface
34     <p>
35     The dependency manager tracks needs that dependents have of providers. This
36     is a general purpose interface which is associated with a
37     DataDictinary object; infact the dependencymanager is really the
38     datadictionary keeping track of dependcies between objects that it handles
39     (descriptors) as well as prepared statements.
40     <p>
41     The primary example of this is a prepared statement's needs of
42     schema objects such as tables.
43     <p>
44     Dependencies are used so that we can determine when we
45     need to recompile a statement; compiled statements depend
46     on schema objects like tables and constraints, and may
47     no longer be executable when those tables or constraints are
48     altered. For example, consider an insert statement.
49     <p>
50     An insert statement is likely to have dependencies on the table it
51     inserts into, any tables it selects from (including
52     subqueries), the authorities it uses to do this,
53     and any constraints or triggers it needs to check.
54     <p>
55     A prepared insert statement has a dependency on the target table
56     of the insert. When it is compiled, that dependency is registered
57     from the prepared statement on the data dictionary entry for the
58     table. This dependency is added to the prepared statement's dependency
59     list, which is also accessible from an overall dependency pool.
60     <p>
61     A DDL statement will mark invalid any prepared statement that
62     depends on the schema object the DDL statement is altering or
63     dropping. We tend to want to track at the table level rather than
64     the column or constraint level, so that we are not overburdened
65     with dependencies. This does mean that we may invalidate when in
66     fact we do not need to; for example, adding a column to a table may
67     not actually cause an insert statement compiled for that table
68     to stop working; but our level of granularity may force us to
69     invalidate the insert because it has to invalidate all statements
70     that depend on the table due to some of them actually no longer
71     being valid.
73     It is up to the user of the dependency system at what granularity
74     to track dependencies, where to hang them, and how to identify when
75     objects become invalid. The dependency system is basically supplying
76     the ability to find out who is interested in knowing about
77     other, distinct operations. The primary user is the language system,
78     and its primary use is for invalidating prepared statements when
79     DDL occurs.
80     <p>
81     The insert will recompile itself when its next execution
82     is requested (not when it is invalidated). We don't want it to
83     recompile when the DDL is issued, as that would increase the time
84     of execution of the DDL command unacceptably. Note that the DDL
85     command is also allowed to proceed even if it would make the
86     statement no longer compilable. It can be useful to have a way
87     to recompile invalid statements during idle time in the system,
88     but our first implementation will simply recompile at the next
89     execution.
90     <p>
91     The start of a recompile will release the connection to
92     all dependencies when it releases the activation class and
93     generates a new one.
94     <p>
95     The Dependency Manager is capable of storing dependencies to
96     ensure that other D.M.s can see them and invalidate them
97     appropriately. The dependencies in memory only the current
98     D.M. can see; the stored dependencies are visible to other D.M.s
99     once the transaction in which they were stored is committed.
100     <p>
101     REVISIT: Given that statements are compiled in a separate top-transaction
102     from their execution, we may need/want some intermediate memory
103     storage that makes the dependencies visible to all D.M.s in the
104     system, without requiring that they be stored.
105     <p>
106     To ensure that dependencies are cleaned up when a statement is undone,
107     the compiler context needs to keep track of what dependent it was
108     creating dependencies for, and if it is informed of a statement
109     exception that causes it to throw out the statement it was compiling,
110     it should also call the dependency manager to have the
111     dependencies removed.
112     <p>
113     Several expansions of the basic interface may be desirable:
114     <ul>
115     <li> to note a type of dependency, and to invalidate or perform
116       an invalidation action based on dependency type
117     <li> to note a type of invalidation, so the revalidation could
118       actually take some action other than recompilation, such as
119       simply ensuring the provider objects still existed.
120     <li> to control the order of invalidation, so that if (for example)
121       the invalidation action actually includes the revalidation attempt,
122       revalidation is not attempted until all invalidations have occurred.
123     <li> to get a list of dependencies that a Dependent or
124       a Provider has (this is included in the above, although the
125       basic system does not need to expose the list).
126     <li> to find out which of the dependencies for a dependent were marked
127       invalid.
128     </ul>
129     <p>
130     To provide a simple interface that satisfies the basic need,
131     and yet supply more advanced functionality as well, we will present
132     the simple functionality as defaults and provide ways to specify the
133     more advanced functionality.
135     <pre>
136     interface Dependent {
137         boolean isValid();
138         InvalidType getInvalidType(); // returns what it sees
139                         // as the "most important"
140                         // of its invalid types.
141         void makeInvalid( );
142         void makeInvalid( DependencyType dt, InvalidType it );
143         void makeValid();
144     }
146     interface Provider() {
147     }
149     interface Dependency() {
150         Provider getProvider();
151         Dependent getDependent();
152         DependencyType getDependencyType();
153         boolean isValid();
154         InvalidType getInvalidType(); // returns what it sees
155                         // as the "most important"
156                         // of its invalid types.
157     }
159     interface DependencyManager() {
160         void addDependency(Dependent d, Provider p, ContextManager cm);
161         void invalidateFor(Provider p);
162         void invalidateFor(Provider p, DependencyType dt, InvalidType it);
163         void clearDependencies(Dependent d);
164         void clearDependencies(Dependent d, DependencyType dt);
165         Enumeration getProviders (Dependent d);
166         Enumeration getProviders (Dependent d, DependencyType dt);
167         Enumeration getInvalidDependencies (Dependent d,
168             DependencyType dt, InvalidType it);
169         Enumeration getDependents (Provider p);
170         Enumeration getDependents (Provider p, DependencyType dt);
171         Enumeration getInvalidDependencies (Provider p,
172             DependencyType dt, InvalidType it);
173     }
174     </pre>
175     <p>
176     The simplest things for DependencyType and InvalidType to be are
177     integer id's or strings, rather than complex objects.
178     <p>
179     In terms of ensuring that no makeInvalid calls are made until we have
180     identified all objects that could be, so that the calls will be made
181     from "leaf" invalid objects (those not in turn relied on by other
182     dependents) to dependent objects upon which others depend, the
183     dependency manager will need to maintain an internal queue of
184     dependencies and make the calls once it has completes its analysis
185     of the dependencies of which it is aware. Since it is much simpler
186     and potentially faster for makeInvalid calls to be made as soon
187     as the dependents are identified, separate implementations may be
188     called for, or separate interfaces to trigger the different
189     styles of invalidation.
190     <p>
191     In terms of separate interfaces, the DependencyManager might have
192     two methods,
193     <pre>
194         void makeInvalidImmediate();
195         void makeInvalidOrdered();
196     </pre>
197     or a flag on the makeInvalid method to choose the style to use.
198     <p>
199     In terms of separate implementations, the ImmediateInvalidate
200     manager might have simpler internal structures for
201     tracking dependencies than the OrderedInvalidate manager.
202     <p>
203     The language system doesn't tend to suffer from this ordering problem,
204     as it tends to handle the impact of invalidation by simply deferring
205     recompilation until the next execution. So, a prepared statement
206     might be invalidated several times by a transaction that contains
207     several DDL operations, and only recompiled once, at its next
208     execution. This is sufficient for the common use of a system, where
209     DDL changes tend to be infrequent and clustered.
210     <p>
211     There could be ways to push this "ordering problem" out of the
212     dependency system, but since it knows when it starts and when it
213     finished finding all of the invalidating actions, it is likely
214     the best home for this.
215     <p>
216     One other problem that could arise is multiple invalidations occurring
217     one after another. The above design of the dependency system can
218     really only react to each invalidation request as a unit, not
219     to multiple invalidation requests.
220     <p>
221     Another extension that might be desired is for the dependency manager
222     to provide for cascading invalidations -- that is, if it finds
223     and marks one Dependent object as invalid, if that object can also
224     be a provider, to look for its dependent objects and cascade the
225     dependency on to them. This can be a way to address the
226     multiple-invalidation request need, if it should arise. The simplest
227     way to do this is to always cascade the same invalidation type;
228     otherwise, dependents need to be able to say what a certain type
229     of invalidation type gets changed to when it is handed on.
230     <p>
231     The basic language system does not need support for cascaded
232     dependencies -- statements do not depend on other statements
233     in a way that involves the dependency system.
234     <p>
235     I do not know if it would be worthwhile to consider using the
236     dependency manager to aid in the implementation of the SQL DROP
237     statements or not. Past implementations
238     of database systems have not used the dependency system to implement
239     this functionality, but have instead hard-coded the lookups like so:
241     <pre>
242         in DropTable:
243             scan the TableAuthority table looking for authorities on
244         this table; drop any that are found.
245             scan the ColumnAuthority table looking for authorities on
246         this table; drop any that are found.
247             scan the View table looking for views on
248         this table; drop any that are found.
249             scan the Column table looking for rows for columns of
250         this table; drop any that are found.
251             scan the Constraint table looking for rows for constraints of
252         this table; drop any that are found.
253             scan the Index table looking for rows for indexes of
254         this table; drop the indexes, and any rows that are found.
255         drop the table's conglomerate
256         drop the table's row in the Table table.
257         </pre>
258     <p>
259     The direct approach such as that outlined in the example will
260     probably be quicker and is definitely "known technology" over
261     the use of a dependency system in this area.
262  */

264 public interface DependencyManager {
266     /* NOTE - every value in this group (actions) must have a matching
267      * String in the implementation of getActionString().
268      */

269     public static final int COMPILE_FAILED = 0;
270     public static final int DROP_TABLE = 1;
271     public static final int DROP_INDEX = 2;
272     public static final int CREATE_INDEX = 3;
273     public static final int ROLLBACK = 4;
274     public static final int CHANGED_CURSOR = 5;
275     public static final int DROP_METHOD_ALIAS = 6;
276     public static final int DROP_VIEW = 9;
277     public static final int CREATE_VIEW = 10;
278     public static final int PREPARED_STATEMENT_RELEASE = 11;
279     public static final int ALTER_TABLE = 12;
280     public static final int DROP_SPS = 13;
281     public static final int USER_RECOMPILE_REQUEST = 14;
282     public static final int BULK_INSERT = 15;
283     public static final int DROP_JAR = 17;
284     public static final int REPLACE_JAR = 18;
285     public static final int DROP_CONSTRAINT = 19;
286     public static final int SET_CONSTRAINTS_ENABLE = 20;
287     public static final int SET_CONSTRAINTS_DISABLE = 21;
288     public static final int CREATE_CONSTRAINT = 22;
289     public static final int INTERNAL_RECOMPILE_REQUEST = 23;
290     public static final int DROP_TRIGGER = 27;
291     public static final int CREATE_TRIGGER = 28;
292     public static final int SET_TRIGGERS_ENABLE = 29;
293     public static final int SET_TRIGGERS_DISABLE = 30;
294     public static final int MODIFY_COLUMN_DEFAULT = 31;
295     public static final int DROP_SCHEMA = 32;
296     public static final int COMPRESS_TABLE = 33;
297     //using same action for rename table/column
public static final int RENAME = 34;
299     public static final int DROP_COLUMN = 37;
300     public static final int DROP_STATISTICS = 39;
301     public static final int UPDATE_STATISTICS = 40;
302     //rename index dependency behavior is not as stringent as rename table and column and
//hence we need a different action for rename index. Rename index tries to imitate the
//drop index behavior for dependency which is not very strict.
public static final int RENAME_INDEX = 41;
307     public static final int TRUNCATE_TABLE = 42;
308     public static final int DROP_SYNONYM = 43;
309     //A generic revoke action for TRIGGER, REFERENCES, SELECT, INSERT,
// UPDATE and DELETE privileges. For all these privilege types,
// a revoke statement causes the dependents to drop
public static final int REVOKE_PRIVILEGE = 44;
314     //This special revoke action is for when revoke should fail if
// there are dependents on the privilege being revoked. When
// such an action type is received by any dependents, they
// should throw an exception. Such a form of revoke will succeed
// only if there are no dependents on the privilege being revoked.
//Currently, this is supported only for execute privilege on a
// routine. In Derby, at this point, execute privilege on a
// routine can be revoked only if there are no dependents on
// that privilege. So, when a revoke execute..,restrict is
// issued, this invalidation action will be sent to all
// it's dependents.
public static final int REVOKE_PRIVILEGE_RESTRICT = 45;
328     /**
329      * Extensions to this interface may use action codes > MAX_ACTION_CODE without fear of
330      * clashing with action codes in this base interface.
331      */

332     public static final int MAX_ACTION_CODE = 0XFFFF;
334     /**
335         adds a dependency from the dependent on the provider.
336         This will be considered to be the default type of
337         dependency, when dependency types show up.
338         <p>
339         Implementations of addDependency should be fast --
340         performing alot of extra actions to add a dependency would
341         be a detriment.
343         @param d the dependent
344         @param p the provider
345         @param cm Current ContextManager
347         @exception StandardException thrown if something goes wrong
348      */

349     void addDependency(Dependent d, Provider p, ContextManager cm) throws StandardException;
351     /**
352         mark all dependencies on the named provider as invalid.
353         When invalidation types show up, this will use the default
354         invalidation type. The dependencies will still exist once
355         they are marked invalid; clearDependencies should be used
356         to remove dependencies that a dependent has or provider gives.
357         <p>
358         Implementations of this can take a little time, but are not
359         really expected to recompile things against any changes
360         made to the provider that caused the invalidation. The
361         dependency system makes no guarantees about the state of
362         the provider -- implementations can call this before or
363         after actually changing the provider to its new state.
364         <p>
365         Implementations should throw DependencyStatementException
366         if the invalidation should be disallowed.
368         @param p the provider
369         @param action The action causing the invalidate
370         @param lcc The LanguageConnectionContext
372         @exception StandardException thrown if unable to make it invalid
373      */

374     void invalidateFor(Provider p, int action, LanguageConnectionContext lcc)
375         throws StandardException;
379     /**
380         Erases all of the dependencies the dependent has, be they
381         valid or invalid, of any dependency type. This action is
382         usually performed as the first step in revalidating a
383         dependent; it first erases all the old dependencies, then
384         revalidates itself generating a list of new dependencies,
385         and then marks itself valid if all its new dependencies are
386         valid.
387         <p>
388         There might be a future want to clear all dependencies for
389         a particular provider, e.g. when destroying the provider.
390         However, at present, they are assumed to stick around and
391         it is the responsibility of the dependent to erase them when
392         revalidating against the new version of the provider.
393         <p>
394         clearDependencies will delete dependencies if they are
395         stored; the delete is finalized at the next commit.
397         @param lcc Compiler state
398         @param d the dependent
399      *
400      * @exception StandardException Thrown on failure
401      */

402     void clearDependencies(LanguageConnectionContext lcc, Dependent d) throws StandardException;
404     /**
405      * Clear the specified in memory dependency.
406      * This is useful for clean-up when an exception occurs.
407      * (We clear all in-memory dependencies added in the current
408      * StatementContext.)
409        This method will handle Dependency's that have already been
410        removed from the DependencyManager.
411      */

412     public void clearInMemoryDependency(Dependency dy);
414     /**
415      * Get a new array of ProviderInfos representing all the persistent
416      * providers for the given dependent.
417      *
418      * @exception StandardException Thrown on error.
419      */

420     public ProviderInfo[] getPersistentProviderInfos(Dependent dependent)
421             throws StandardException;
423     /**
424      * Get a new array of ProviderInfos representing all the persistent
425      * providers from the given list of providers.
426      *
427      * @exception StandardException Thrown on error.
428      */

429     public ProviderInfo[] getPersistentProviderInfos(ProviderList pl)
430             throws StandardException;
432     /**
433      * Clear the in memory column bit map information in any table descriptor
434      * provider in a provider list. This function needs to be called before
435      * the table descriptor is reused as provider in column dependency. For
436      * example, this happens in "create publication" statement with target-only
437      * DDL where more than one views are defined and they all reference one
438      * table.
439      *
440      * @exception StandardException Thrown on error.
441      */

442     public void clearColumnInfoInProviders(ProviderList pl)
443             throws StandardException;
446     /**
447      * Copy dependencies from one dependent to another.
448      *
449      * @param copy_From the dependent to copy from
450      * @param copyTo the dependent to copy to
451      * @param persistentOnly only copy persistent dependencies
452      * @param cm Current ContextManager
453      *
454      * @exception StandardException Thrown on error.
455      */

456     public void copyDependencies(
457                                     Dependent copy_From,
458                                     Dependent copyTo,
459                                     boolean persistentOnly,
460                                     ContextManager cm)
461             throws StandardException;
463     /**
464      * Returns a string representation of the SQL action, hence no
465      * need to internationalize, which is causing the invokation
466      * of the Dependency Manager.
467      *
468      * @param action The action
469      *
470      * @return String The String representation
471      */

472     String JavaDoc getActionString(int action);
474     /**
475      * Count the number of active dependencies, both stored and in memory,
476      * in the system.
477      *
478      * @return int The number of active dependencies in the system.
480         @exception StandardException thrown if something goes wrong
481      */

482     public int countDependencies() throws StandardException;
484     /**
485      * Dump out debugging info on all of the dependencies currently
486      * within the system.
487      *
488      * @return String Debugging info on the dependencies.
489      * (null if SanityManger.DEBUG is false)
491         @exception StandardException thrown if something goes wrong
492         @exception java.sql.SQLException thrown if something goes wrong
493      */

494     public String JavaDoc dumpDependencies() throws StandardException, java.sql.SQLException JavaDoc;
496     /**
497         Erases all of the dependencies the dependent has, be they
498         valid or invalid, of any dependency type. This action is
499         usually performed as the first step in revalidating a
500         dependent; it first erases all the old dependencies, then
501         revalidates itself generating a list of new dependencies,
502         and then marks itself valid if all its new dependencies are
503         valid.
504         <p>
505         There might be a future want to clear all dependencies for
506         a particular provider, e.g. when destroying the provider.
507         However, at present, they are assumed to stick around and
508         it is the responsibility of the dependent to erase them when
509         revalidating against the new version of the provider.
510         <p>
511         clearDependencies will delete dependencies if they are
512         stored; the delete is finalized at the next commit.
514         @param lcc Compiler state
515         @param d the dependent
516         @param tc transaction controller
518         @exception StandardException Thrown on failure
519     */

520     public void clearDependencies(LanguageConnectionContext lcc,
521                                     Dependent d,
522                                     TransactionController tc)
523         throws StandardException;
526     /**
527      * Copy dependencies from one dependent to another.
528      *
529      * @param copy_From the dependent to copy from
530      * @param copyTo the dependent to copy to
531      * @param persistentOnly only copy persistent dependencies
532      * @param cm Current ContextManager
533      * @param tc Transaction Controller
534      *
535      * @exception StandardException Thrown on error.
536      */

537     public void copyDependencies(
538                                     Dependent copy_From,
539                                     Dependent copyTo,
540                                     boolean persistentOnly,
541                                     ContextManager cm,
542                                     TransactionController tc)
543             throws StandardException;
545 }
Popular Tags