DeferModification


1   /*
2   
3      Derby - Class org.apache.derby.vti.DeferModification
4   
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
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
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.
19  
20   */
21  
22  package org.apache.derby.vti;
23  
24  import java.sql.SQLException  ;
25  
26  /**
27   * This interface is implemented by a read/write VTI class that wants to control when
28   * modifications to the VTI are deferred, or to be notified that a it is to be modified.
29   * Consider the following statement:<br>
30   * UPDATE NEW myVTI(...)
31   *  SET cost = cost + 10
32   *  WHERE cost < 15
33   *<p>
34   * Updating a column that is used in the WHERE clause might or might not give the VTI implementation trouble;
35   * the update might cause the same row to be selected more than once. This problem can be solved by building the
36   * complete list of rows to be updated and the new column values before updating any rows. The updates are applied
37   * after the list is built. This process is called "deferred update".
38   *<p>
39   * By default, updates on a VTI are deferred when the VTI ResultSet
40   * is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and one or more of the following is true.
41   *<ol>
42   *<li>One or more of the columns in the SET clause is also used in the WHERE
43   * clause and the VTI ResultSet is sensitive. We do not defer updates
44   * when the ResultSet is TYPE_SCROLL_INSENSITIVE because it is not necessary.
45   *<li>The where clause contains a subselect on a VTI from the same class as the
46   * target VTI. We do not look at the VTI parameters, just the VTI class name.
47   *</ol>
48   *<p>
49   * By default, deletes on a VTI are deferred in a similar situation: when the VTI ResultSet
50   * is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and
51   * the where clause contains a subselect on a VTI from the same class as the
52   * target VTI. We do not look at the VTI parameters, just the VTI class name.
53   *<p>
54   * By default, inserts into a VTI are deferred when the same VTI class is used as both
55   * the source and target. It does not depend on the scrollability of the
56   * VTI ResultSet because inserts can be deferred without scrolling the ResultSet.
57   *<p>
58   * If these defaults are not appropriate then the class implementing the VTI should also implement
59   * this interface (org.apache.derby.vti.DeferModification).
60   *<p>
61   * (A read/write VTI is implemented by a class that implements the java.sql.PreparedStatement interface,
62   * often by extending the UpdatableVTITemplate interface. @see UpdatableVTITemplate).
63   *<p>
64   * Update and delete statement deferral is implemented by scrolling the VTI's ResultSet. Therefore,
65   * updates and deletes on a VTI are never deferred unless the VTI's ResultSets are scrollable, even
66   * if the DeferModification interface methods return <b>true</b>.
67   * Therefore for an update or delete to be deferred the VTI getResultSetType() method must return
68   * ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE and the VTI must produce scrollable
69   * java.sql.ResultSets that implement the getRow() and absolute() methods. If your VTI is implemented as
70   * an extension to UpdatableVTITemplate then you must override the getResultSetMethod:
71   * UpdatableVTITemplate.getResultSetType()
72   * throws an exception. If your VTI's ResultSets are implemented as extensions to VTITemplate then you must
73   * override the getRow() and absolute() methods: VTITemplate.getRow() and absolute() throw exceptions.
74   *<p>
75   * This interface is not used when the VTI is referenced only in a subselect; it is only used when a
76   * VTI appears as the target of an INSERT, UPDATE, or DELETE statement.
77   */
78  public interface DeferModification
79  {
80  
81      public static final int INSERT_STATEMENT = 1;
82      public static final int UPDATE_STATEMENT = 2;
83      public static final int DELETE_STATEMENT = 3;
84  
85      /**
86       * This method is called during preparation of an insert, update, or delete statement with this VTI
87       * as the target. It indicates whether the statement should be deferred irregardless of the other clauses
88       * in the statement. If alwaysDefer returns <b>true</b> then the other methods in this interface
89       * are not called. (At least not for this statement type).
90       *
91       * @param statementType One of INSERT_STATEMENT, UPDATE_STATEMENT, DELETE_STATEMENT.
92       *
93       * @return <b>true</b> if the statement type should always be deferred on this VTI,
94       *         <b>false</b> other criteria (see below) should be examined to determine
95       *         whether to defer the modification.
96       *
97       * @exception SQLException on an unexpected condition.
98       */
99      public boolean alwaysDefer( int statementType)
100         throws SQLException  ;
101 
102     /**
103      * This method is called during preparation of an update or delete statement on the virtual
104      * table if getResultSetType() returns ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_SENSITIVE and
105      * alwaysDefer( statementType) returns <b>false</b>.
106      * ColumnRequiresDefer is called once for each column that is being updated,
107      * or each column in a DELETE where clause until
108      * it returns <b>true</b> or until all the columns have been exhausted.
109      *
110      * @param statementType UPDATE_STATEMENT or DELETE_STATEMENT.
111      * @param columnName the name of one of the columns being updated
112      * @param inWhereClause indicates whether the column also appears in the where clause
113      *
114      * @return <b>true</b> if the update must be deferred
115      *         <b>false</b> if this column does not require a deferred update
116      *
117      * @exception SQLException a parameter is invalid or there is another unexpected failure.
118      */
119     public boolean columnRequiresDefer( int statementType,
120                                         String   columnName,
121                                         boolean inWhereClause)
122         throws SQLException  ;
123 
124     /**
125      * This method is called during preparation of an insert, update, or delete statement that has this virtual
126      * table as its target and that has a sub-select. It is invoked once for each regular table in a sub-select,
127      * if it has not already been determined that the statement should be deferred or that the VTI does not support
128      * deferral.
129      *
130      * @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
131      * @param schemaName the schema of the table in the sub-select.
132      * @param tableName the name of the table in the sub-select.
133      *
134      * @return <b>true</b> if the modification must be deferred
135      *         <b>false</b> if this source table does not necessitate a deferred modification
136      *
137      * @exception SQLException a parameter is invalid or there is another unexpected failure.
138      */
139     public boolean subselectRequiresDefer( int statementType,
140                                            String   schemaName,
141                                            String   tableName)
142         throws SQLException  ;
143 
144     /**
145      * This method is called during preparation of an insert, update, or delete statement that has this virtual
146      * table as its target and that has a sub-select. It is invoked once for each virtual table in the sub-select,
147      * if it has not already been determined that the statement should be deferred or that the VTI does not support
148      * deferral.
149      *
150      * @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
151      * @param VTIClassName the name of the class implementing the VTI in the sub-select.
152      *
153      * @return <b>true</b> if the modification must be deferred
154      *         <b>false</b> if this source table does not necessitate a deferred modification
155      *
156      * @exception SQLException a parameter is invalid or there is another unexpected failure.
157      */
158     public boolean subselectRequiresDefer( int statementType,
159                                            String   VTIClassName)
160         throws SQLException  ;
161 
162     /**
163      * This VTI method is called by Cloudscape when a VTI modification (insert, update, or delete)
164      * is executed. It is called after the VTI has been instantiated but before any rows are read,
165      * inserted, updated, or deleted.
166      *
167      * @param statementType one of INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT
168      * @param deferred <b>true</b> if the modification will be deferred, <b>false</b> if not.
169      *
170      * @exception SQLException thrown on an unexpected failure
171      */
172     public void modificationNotify( int statementType,
173                                     boolean deferred)
174         throws SQLException  ;
175 }
176
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags