Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.util.InterruptStatus

Static methods to save and retrieve information about a (session) thread's interrupt status flag. If during operation we notice an interrupt, Derby will either:

immediately throw an exception to cut execution short, also resurrecting the thread's interrupted status flag. This does not require use of this class.
just note the fact using this class (noteAndClearInterrupt, or (setInterrupted)), and retry whatever got interrupted, continuing execution. To achieve this, Derby will always temporarily clear the interrupted status flag. Later, depending on the type of SQL statement, we may wish to interrupt execution by throwing an SQLException at a safe place, say, after a statement in a batch is complete (throwIf), or just let the execution run to completion, and then just prior to returning to the appliction, the thread's interrupted status flag will resurrected (restoreIntrFlagIfSeen)

Normally, the information is saved away in the session's LanguageConnectionContext, if available. If not, we save it in a thread local variable.

Field Summary

Modifier and Type	Field and Description
private static final ThreadLocal<Exception>	exception Use thread local variable to store interrupt status flag only if we don't have lcc, e.g. during database creation, shutdown etc.
public static final int	INTERRUPT_RETRY_SLEEP
public static final int	MAX_INTERRUPT_RETRIES Constants used by code that retries file operations after seeing the NIO file channel closed due to interrupts.

Constructor Summary

Access	Constructor and Description
public	InterruptStatus()

Method Summary

Modifier and Type	Method and Description
private static Context	getContextOrNull(final String contextID) Must be private so that user code can't call this entry point.
public static boolean	Returns: true if the thread's interrupt status flag was set noteAndClearInterrupt(String (debug info) whence s, int (debug info) number of threads inside the NIO code concurrently threadsInPageIO, int (debug info) container id hashCode) Checks if the thread has been interrupted in NIO, presumably because we saw an exception indicating this.
public static void	restoreIntrFlagIfSeen() Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution.
public static void	restoreIntrFlagIfSeen(LanguageConnectionContext the language connection context for this session lcc) Same purpose as `restoreIntrFlagIfSeen()`.
public static void	saveInfoFromLcc(LanguageConnectionContext lcc) Use when lcc is dying to save info in thread local instead.
public static void	setInterrupted() Make a note that this thread saw an interrupt.
public static void	throwIf(LanguageConnectionContext the language connection context for this session lcc) Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution, or if the interrupt status flag is set now.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

exception	back to summary
private static final ThreadLocal<Exception> exception Use thread local variable to store interrupt status flag only if we don't have lcc, e.g. during database creation, shutdown etc.

INTERRUPT_RETRY_SLEEP	back to summary
public static final int INTERRUPT_RETRY_SLEEP

MAX_INTERRUPT_RETRIES	back to summary
public static final int MAX_INTERRUPT_RETRIES Constants used by code that retries file operations after seeing the NIO file channel closed due to interrupts.

Constructor Detail

InterruptStatus	back to summary
public InterruptStatus()

Method Detail

getContextOrNull	back to summary
private static Context getContextOrNull(final String contextID) Must be private so that user code can't call this entry point.

noteAndClearInterrupt back to summary

noteAndClearInterrupt	back to summary
public static boolean noteAndClearInterrupt(String s, int threadsInPageIO, int hashCode) Checks if the thread has been interrupted in NIO, presumably because we saw an exception indicating this. Make a note of this and clear the thread's interrupt status flag (NIO doesn't clear it when throwing) so we can retry whatever we are doing. It will be set back ON before control is transferred back to the application, cf. `restoreIntrFlagIfSeen`. The note that we saw an interrupt is stored in the lcc if available, if not, in thread local `exception`. Parameters s:String (debug info) whence threadsInPageIO:int (debug info) number of threads inside the NIO code concurrently hashCode:int (debug info) container id Returns:boolean true if the thread's interrupt status flag was set

public static boolean noteAndClearInterrupt(String s, int threadsInPageIO, int hashCode)

Checks if the thread has been interrupted in NIO, presumably because we saw an exception indicating this. Make a note of this and clear the thread's interrupt status flag (NIO doesn't clear it when throwing) so we can retry whatever we are doing. It will be set back ON before control is transferred back to the application, cf. restoreIntrFlagIfSeen.

The note that we saw an interrupt is stored in the lcc if available, if not, in thread local exception.

Parameters

s:String: (debug info) whence
threadsInPageIO:int: (debug info) number of threads inside the NIO code concurrently
hashCode:int: (debug info) container id

Returns:boolean

true if the thread's interrupt status flag was set

restoreIntrFlagIfSeen back to summary

restoreIntrFlagIfSeen	back to summary
public static void restoreIntrFlagIfSeen() Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution. Called from JDBC API methods before returning control to user application. Typically, this happens just prior to return in methods that catch `Throwable` and invoke `handleException` (directly or indirectly) on it, e.g. : InterruptStatus.restoreIntrFlagIfSeen(); return ...; } catch (Throwable t) { throw handleException(t); } `handleException` does its own calls to `restoreIntrFlagIfSeen`. If `setupContextStack` has been called consider using the overloaded variant of `restoreIntrFlagIfSeen` with an lcc argument. If an interrupt status flag was seen, we set it back on here.

public static void restoreIntrFlagIfSeen()

Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution. Called from JDBC API methods before returning control to user application. Typically, this happens just prior to return in methods that catch Throwable and invoke handleException (directly or indirectly) on it, e.g.

      :
      InterruptStatus.restoreIntrFlagIfSeen();
      return ...;
   } catch (Throwable t) {
      throw handleException(t);
   }

handleException does its own calls to restoreIntrFlagIfSeen. If setupContextStack has been called consider using the overloaded variant of restoreIntrFlagIfSeen with an lcc argument.

If an interrupt status flag was seen, we set it back on here.

restoreIntrFlagIfSeen back to summary

restoreIntrFlagIfSeen	back to summary
public static void restoreIntrFlagIfSeen(LanguageConnectionContext lcc) Same purpose as `restoreIntrFlagIfSeen()`. This variant presumes we are sure we have a `lcc != null`, i.e. `setupContextStack` has been called and not yet restored. Note that we cannot merge this code with `restoreContextStack`, since that is typically called in a `finally` block, at which point in time, the `lcc` may be gone due to errors of severity `SESSION_SEVERITY` or `DATABASE_SEVERITY`. If no `lcc` is available, use the zero-arg variant. We only need this variant for performance reasons. Parameters lcc:LanguageConnectionContext the language connection context for this session

public static void restoreIntrFlagIfSeen(LanguageConnectionContext lcc)

Same purpose as restoreIntrFlagIfSeen(). This variant presumes we are sure we have a lcc != null, i.e. setupContextStack has been called and not yet restored. Note that we cannot merge this code with restoreContextStack, since that is typically called in a finally block, at which point in time, the lcc may be gone due to errors of severity SESSION_SEVERITY or DATABASE_SEVERITY.

If no lcc is available, use the zero-arg variant. We only need this variant for performance reasons.

Parameters

lcc:LanguageConnectionContext: the language connection context for this session

saveInfoFromLcc	back to summary
public static void saveInfoFromLcc(LanguageConnectionContext lcc) Use when lcc is dying to save info in thread local instead. Useful under shutdown.

setInterrupted	back to summary
public static void setInterrupted() Make a note that this thread saw an interrupt. Thread's intr status flag is presumably off already, but we reset it here also. Use lcc if available, else thread local variable.

throwIf	back to summary
public static void throwIf(LanguageConnectionContext lcc) throws StandardException Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution, or if the interrupt status flag is set now. Called when operations want to be prematurely terminated due to interrupt. If an interrupt status flag was seen, but temporarily switched off, we set it back ON here. Parameters lcc:LanguageConnectionContext the language connection context for this session Exceptions StandardException: (session level SQLState.CONN_INTERRUPT) if interrupt seen

throwIf

back to summary

public static void throwIf(LanguageConnectionContext lcc) throws StandardException

Check if the we ever noticed and reset the thread's interrupt status flag to allow safe operation during execution, or if the interrupt status flag is set now. Called when operations want to be prematurely terminated due to interrupt.

If an interrupt status flag was seen, but temporarily switched off, we set it back ON here.

Parameters

lcc:LanguageConnectionContext: the language connection context for this session

Exceptions

StandardException:: (session level SQLState.CONN_INTERRUPT) if interrupt seen

public Class InterruptStatus

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail