java/engine/org/apache/derby/vti/DeferModification.java - derby - Git at Google

 /*

    Derby - Class org.apache.derby.vti.DeferModification

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

  */

 package org.apache.derby.vti;

 import java.sql.SQLException;

 /**
  * This interface is implemented by a read/write VTI class that wants to control when
  * modifications to the VTI are deferred, or to be notified that a it is to be modified.
  * Consider the following statement:<br>
  * UPDATE NEW myVTI(...)
  *  SET cost = cost + 10
  *  WHERE cost &lt; 15
  *<p>
  * Updating a column that is used in the WHERE clause might or might not give the VTI implementation trouble;
  * the update might cause the same row to be selected more than once. This problem can be solved by building the
  * complete list of rows to be updated and the new column values before updating any rows. The updates are applied
  * after the list is built. This process is called "deferred update".
  *<p>
  * By default, updates on a VTI are deferred when the VTI ResultSet
  * is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and one or more of the following is true.
  *<ol>
  *<li>One or more of the columns in the SET clause is also used in the WHERE
  * clause and the VTI ResultSet is sensitive. We do not defer updates
  * when the ResultSet is TYPE_SCROLL_INSENSITIVE because it is not necessary.
  *<li>The where clause contains a subselect on a VTI from the same class as the
  * target VTI. We do not look at the VTI parameters, just the VTI class name.
  *</ol>
  *<p>
  * By default, deletes on a VTI are deferred in a similar situation: when the VTI ResultSet
  * is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and
  * the where clause contains a subselect on a VTI from the same class as the
  * target VTI. We do not look at the VTI parameters, just the VTI class name.
  *<p>
  * By default, inserts into a VTI are deferred when the same VTI class is used as both
  * the source and target. It does not depend on the scrollability of the
  * VTI ResultSet because inserts can be deferred without scrolling the ResultSet.
  *<p>
  * If these defaults are not appropriate then the class implementing the VTI should also implement
  * this interface (org.apache.derby.vti.DeferModification).
  *<p>
  * (A read/write VTI is implemented by a class that implements the java.sql.PreparedStatement interface,
  * often by extending the UpdatableVTITemplate interface. @see UpdatableVTITemplate).
  *<p>
  * Update and delete statement deferral is implemented by scrolling the VTI's ResultSet. Therefore,
  * updates and deletes on a VTI are never deferred unless the VTI's ResultSets are scrollable, even
  * if the DeferModification interface methods return <b>true</b>.
  * Therefore for an update or delete to be deferred the VTI getResultSetType() method must return
  * ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE and the VTI must produce scrollable
  * java.sql.ResultSets that implement the getRow() and absolute() methods. If your VTI is implemented as
  * an extension to UpdatableVTITemplate then you must override the getResultSetMethod:
  * UpdatableVTITemplate.getResultSetType()
  * throws an exception. If your VTI's ResultSets are implemented as extensions to VTITemplate then you must
  * override the getRow() and absolute() methods: VTITemplate.getRow() and absolute() throw exceptions.
  *<p>
  * This interface is not used when the VTI is referenced only in a subselect; it is only used when a
  * VTI appears as the target of an INSERT, UPDATE, or DELETE statement.
  */
 public interface DeferModification
 {

     public static final int INSERT_STATEMENT = 1;
     public static final int UPDATE_STATEMENT = 2;
     public static final int DELETE_STATEMENT = 3;

     /**
      * This method is called during preparation of an insert, update, or delete statement with this VTI
      * as the target. It indicates whether the statement should be deferred irregardless of the other clauses
      * in the statement. If alwaysDefer returns <b>true</b> then the other methods in this interface
      * are not called. (At least not for this statement type).
      *
      * @param statementType One of INSERT_STATEMENT, UPDATE_STATEMENT, DELETE_STATEMENT.
      *
      * @return <b>true</b> if the statement type should always be deferred on this VTI,
      *         <b>false</b> other criteria (see below) should be examined to determine
      *         whether to defer the modification.
      *
      * @exception SQLException on an unexpected condition.
      */
     public boolean alwaysDefer( int statementType)
         throws SQLException;

     /**
      * This method is called during preparation of an update or delete statement on the virtual
      * table if getResultSetType() returns ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_SENSITIVE and
      * alwaysDefer( statementType) returns <b>false</b>.
      * ColumnRequiresDefer is called once for each column that is being updated,
      * or each column in a DELETE where clause until
      * it returns <b>true</b> or until all the columns have been exhausted.
      *
      * @param statementType UPDATE_STATEMENT or DELETE_STATEMENT.
      * @param columnName the name of one of the columns being updated
      * @param inWhereClause indicates whether the column also appears in the where clause
      *
      * @return <b>true</b> if the update must be deferred
      *         <b>false</b> if this column does not require a deferred update
      *
      * @exception SQLException a parameter is invalid or there is another unexpected failure.
      */
     public boolean columnRequiresDefer( int statementType,
                                         String columnName,
                                         boolean inWhereClause)
         throws SQLException;

     /**
      * This method is called during preparation of an insert, update, or delete statement that has this virtual
      * table as its target and that has a sub-select. It is invoked once for each regular table in a sub-select,
      * if it has not already been determined that the statement should be deferred or that the VTI does not support
      * deferral.
      *
      * @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
      * @param schemaName the schema of the table in the sub-select.
      * @param tableName the name of the table in the sub-select.
      *
      * @return <b>true</b> if the modification must be deferred
      *         <b>false</b> if this source table does not necessitate a deferred modification
      *
      * @exception SQLException a parameter is invalid or there is another unexpected failure.
      */
     public boolean subselectRequiresDefer( int statementType,
                                            String schemaName,
                                            String tableName)
         throws SQLException;

     /**
      * This method is called during preparation of an insert, update, or delete statement that has this virtual
      * table as its target and that has a sub-select. It is invoked once for each virtual table in the sub-select,
      * if it has not already been determined that the statement should be deferred or that the VTI does not support
      * deferral.
      *
      * @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
      * @param VTIClassName the name of the class implementing the VTI in the sub-select.
      *
      * @return <b>true</b> if the modification must be deferred
      *         <b>false</b> if this source table does not necessitate a deferred modification
      *
      * @exception SQLException a parameter is invalid or there is another unexpected failure.
      */
     public boolean subselectRequiresDefer( int statementType,
                                            String VTIClassName)
         throws SQLException;

     /**
      * This VTI method is called by Derby when a VTI modification (insert, update, or delete)
      * is executed. It is called after the VTI has been instantiated but before any rows are read,
      * inserted, updated, or deleted.
      *
      * @param statementType one of INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT
      * @param deferred <b>true</b> if the modification will be deferred, <b>false</b> if not.
      *
      * @exception SQLException thrown on an unexpected failure
      */
     public void modificationNotify( int statementType,
                                     boolean deferred)
         throws SQLException;
 }
	/*

	Derby - Class org.apache.derby.vti.DeferModification

	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

	*/

	package org.apache.derby.vti;

	import java.sql.SQLException;

	/**
	* This interface is implemented by a read/write VTI class that wants to control when
	* modifications to the VTI are deferred, or to be notified that a it is to be modified.
	* Consider the following statement:<br>
	* UPDATE NEW myVTI(...)
	* SET cost = cost + 10
	* WHERE cost < 15
	*<p>
	* Updating a column that is used in the WHERE clause might or might not give the VTI implementation trouble;
	* the update might cause the same row to be selected more than once. This problem can be solved by building the
	* complete list of rows to be updated and the new column values before updating any rows. The updates are applied
	* after the list is built. This process is called "deferred update".
	*<p>
	* By default, updates on a VTI are deferred when the VTI ResultSet
	* is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and one or more of the following is true.
	*<ol>
	*<li>One or more of the columns in the SET clause is also used in the WHERE
	* clause and the VTI ResultSet is sensitive. We do not defer updates
	* when the ResultSet is TYPE_SCROLL_INSENSITIVE because it is not necessary.
	*<li>The where clause contains a subselect on a VTI from the same class as the
	* target VTI. We do not look at the VTI parameters, just the VTI class name.
	*</ol>
	*<p>
	* By default, deletes on a VTI are deferred in a similar situation: when the VTI ResultSet
	* is scrollable (ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE), and
	* the where clause contains a subselect on a VTI from the same class as the
	* target VTI. We do not look at the VTI parameters, just the VTI class name.
	*<p>
	* By default, inserts into a VTI are deferred when the same VTI class is used as both
	* the source and target. It does not depend on the scrollability of the
	* VTI ResultSet because inserts can be deferred without scrolling the ResultSet.
	*<p>
	* If these defaults are not appropriate then the class implementing the VTI should also implement
	* this interface (org.apache.derby.vti.DeferModification).
	*<p>
	* (A read/write VTI is implemented by a class that implements the java.sql.PreparedStatement interface,
	* often by extending the UpdatableVTITemplate interface. @see UpdatableVTITemplate).
	*<p>
	* Update and delete statement deferral is implemented by scrolling the VTI's ResultSet. Therefore,
	* updates and deletes on a VTI are never deferred unless the VTI's ResultSets are scrollable, even
	* if the DeferModification interface methods return <b>true</b>.
	* Therefore for an update or delete to be deferred the VTI getResultSetType() method must return
	* ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_INSENSITIVE and the VTI must produce scrollable
	* java.sql.ResultSets that implement the getRow() and absolute() methods. If your VTI is implemented as
	* an extension to UpdatableVTITemplate then you must override the getResultSetMethod:
	* UpdatableVTITemplate.getResultSetType()
	* throws an exception. If your VTI's ResultSets are implemented as extensions to VTITemplate then you must
	* override the getRow() and absolute() methods: VTITemplate.getRow() and absolute() throw exceptions.
	*<p>
	* This interface is not used when the VTI is referenced only in a subselect; it is only used when a
	* VTI appears as the target of an INSERT, UPDATE, or DELETE statement.
	*/
	public interface DeferModification
	{

	public static final int INSERT_STATEMENT = 1;
	public static final int UPDATE_STATEMENT = 2;
	public static final int DELETE_STATEMENT = 3;

	/**
	* This method is called during preparation of an insert, update, or delete statement with this VTI
	* as the target. It indicates whether the statement should be deferred irregardless of the other clauses
	* in the statement. If alwaysDefer returns <b>true</b> then the other methods in this interface
	* are not called. (At least not for this statement type).
	*
	* @param statementType One of INSERT_STATEMENT, UPDATE_STATEMENT, DELETE_STATEMENT.
	*
	* @return <b>true</b> if the statement type should always be deferred on this VTI,
	* <b>false</b> other criteria (see below) should be examined to determine
	* whether to defer the modification.
	*
	* @exception SQLException on an unexpected condition.
	*/
	public boolean alwaysDefer( int statementType)
	throws SQLException;

	/**
	* This method is called during preparation of an update or delete statement on the virtual
	* table if getResultSetType() returns ResultSet.TYPE_SCROLL_SENSITIVE or TYPE_SCROLL_SENSITIVE and
	* alwaysDefer( statementType) returns <b>false</b>.
	* ColumnRequiresDefer is called once for each column that is being updated,
	* or each column in a DELETE where clause until
	* it returns <b>true</b> or until all the columns have been exhausted.
	*
	* @param statementType UPDATE_STATEMENT or DELETE_STATEMENT.
	* @param columnName the name of one of the columns being updated
	* @param inWhereClause indicates whether the column also appears in the where clause
	*
	* @return <b>true</b> if the update must be deferred
	* <b>false</b> if this column does not require a deferred update
	*
	* @exception SQLException a parameter is invalid or there is another unexpected failure.
	*/
	public boolean columnRequiresDefer( int statementType,
	String columnName,
	boolean inWhereClause)
	throws SQLException;

	/**
	* This method is called during preparation of an insert, update, or delete statement that has this virtual
	* table as its target and that has a sub-select. It is invoked once for each regular table in a sub-select,
	* if it has not already been determined that the statement should be deferred or that the VTI does not support
	* deferral.
	*
	* @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
	* @param schemaName the schema of the table in the sub-select.
	* @param tableName the name of the table in the sub-select.
	*
	* @return <b>true</b> if the modification must be deferred
	* <b>false</b> if this source table does not necessitate a deferred modification
	*
	* @exception SQLException a parameter is invalid or there is another unexpected failure.
	*/
	public boolean subselectRequiresDefer( int statementType,
	String schemaName,
	String tableName)
	throws SQLException;

	/**
	* This method is called during preparation of an insert, update, or delete statement that has this virtual
	* table as its target and that has a sub-select. It is invoked once for each virtual table in the sub-select,
	* if it has not already been determined that the statement should be deferred or that the VTI does not support
	* deferral.
	*
	* @param statementType the statement type: INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT.
	* @param VTIClassName the name of the class implementing the VTI in the sub-select.
	*
	* @return <b>true</b> if the modification must be deferred
	* <b>false</b> if this source table does not necessitate a deferred modification
	*
	* @exception SQLException a parameter is invalid or there is another unexpected failure.
	*/
	public boolean subselectRequiresDefer( int statementType,
	String VTIClassName)
	throws SQLException;

	/**
	* This VTI method is called by Derby when a VTI modification (insert, update, or delete)
	* is executed. It is called after the VTI has been instantiated but before any rows are read,
	* inserted, updated, or deleted.
	*
	* @param statementType one of INSERT_STATEMENT, UPDATE_STATEMENT, or DELETE_STATEMENT
	* @param deferred <b>true</b> if the modification will be deferred, <b>false</b> if not.
	*
	* @exception SQLException thrown on an unexpected failure
	*/
	public void modificationNotify( int statementType,
	boolean deferred)
	throws SQLException;
	}