Package com.intellij.openapi.application

Class TransactionGuard

java.lang.Object

com.intellij.openapi.application.TransactionGuard

Direct Known Subclasses:

TransactionGuardImpl

public abstract class TransactionGuard
extends java.lang.Object

A service managing write-safe contexts, ensuring that no one will be able to perform an unexpected model change using SwingUtilities.invokeLater(java.lang.Runnable) or analogs while a dialog is shown. See more details in ModalityState documentation.

Write actions that modify model are only allowed inside write-safe contexts. These are:

• Direct user activity processing (key/mouse presses, actions) in non-modal state
• User activity processing in a modality state that was started (e.g. by showing a dialog or progress) in a write-safe context
• Application.invokeLater(Runnable, ModalityState) calls with a modality state that's either non-modal or was started inside a write-safe context

All other contexts are considered write-unsafe, and model modifications are not allowed from them. This includes Swing invokeLater, action update, renderers etc. Even if user activity happens in such context (e.g. someone clicks a button in a dialog shown from SwingUtilities.invokeLater(Runnable)), this will result in an exception. If you've got "Model changes are allowed from write-safe contexts only" or "Cannot run synchronous submitTransactionAndWait" exception, then you're likely inside a Swing's "invokeLater" or "invokeAndWait"-like call.

• Consider simplifying the code. For example, if the outer code is known to be run on EDT, "invokeLater(AndWait)IfNeeded" call can be removed. If it's in a pooled thread, the "IfNeeded" part can be removed. "invokeAndWaitIfNeeded" can be safely unwrapped, if already on EDT.
• Consider making the code synchronous. "invokeLater" from EDT rarely makes sense and can often be replaced with synchronous execution (which will likely be inside a user activity: a write-safe context).
• If you get the assertion from synchronous document commit or VFS refresh, consider making them asynchronous. For documents, use PsiDocumentManager.performLaterWhenAllCommitted(Runnable). You can also try to get rid of them at all, by making your code work only with VFS and PSI and assuming they're refreshed/committed often enough by some other code.
• If you still have "invokeAndWaitIfNeeded" call with model-changing activity inside, replace it with Application.invokeAndWait(java.lang.Runnable, com.intellij.openapi.application.ModalityState). You might still get assertions after that, that would mean that some caller down the stack is also using "invokeLater"-like call and needs to be fixed as well.
• If you still absolutely need "invokeLater", use Application.invokeLater(java.lang.Runnable) or GuiUtils.invokeLaterIfNeeded(java.lang.Runnable, com.intellij.openapi.application.ModalityState)), and pass a modality state that appeared in a write-safe context (e.g. a background progress started in an action). Most likely ModalityState.defaultModalityState() will do. Don't forget to check inside the "later" runnable that it's still actual, that the model haven't been changed by someone else since its scheduling.

See Also:

ModalityState

Constructor Summary

Constructors

Constructor and Description
TransactionGuard()

Method Summary

Modifier and Type	Method and Description
abstract void	assertWriteSafeContext(ModalityState modality) Logs an error if the given modality state was created in a write-unsafe context.
abstract TransactionId	getContextTransaction() Deprecated. replace with ModalityState.defaultModalityState() and use the result for "invokeLater" when replacing "submitTransaction" calls.
static TransactionGuard	getInstance()
abstract boolean	isWriteSafeModality(ModalityState state) Checks whether a given modality is write-safe.
abstract boolean	isWritingAllowed() Checks whether the current state allows for writing the model.
static void	submitTransaction(Disposable parentDisposable, java.lang.Runnable transaction) Deprecated. in a definitely write-safe context, just replace this call with transaction contents. Otherwise, replace with Application.invokeLater(java.lang.Runnable) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.
abstract void	submitTransaction(Disposable parentDisposable, TransactionId expectedContext, java.lang.Runnable transaction) Deprecated. see submitTransaction(Disposable, Runnable).
abstract void	submitTransactionAndWait(java.lang.Runnable transaction) Deprecated. if called on Swing thread, just replace this call with transaction contents. Otherwise, replace with Application.invokeAndWait(java.lang.Runnable, com.intellij.openapi.application.ModalityState) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.
abstract void	submitTransactionLater(Disposable parentDisposable, java.lang.Runnable transaction) Deprecated. Replace with Application.invokeLater(java.lang.Runnable) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransactionGuard

public TransactionGuard()

Method Detail

getInstance

public static TransactionGuard getInstance()

submitTransaction

@Deprecated
public static void submitTransaction(Disposable parentDisposable,
                                     java.lang.Runnable transaction)

Deprecated. in a definitely write-safe context, just replace this call with transaction contents. Otherwise, replace with Application.invokeLater(java.lang.Runnable) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.

assertWriteSafeContext

public abstract void assertWriteSafeContext(ModalityState modality)

Logs an error if the given modality state was created in a write-unsafe context. For modalities created in write-safe contexts, Application.invokeLater(Runnable, ModalityState) and similar calls will be guaranteed to also run in a write-safe context. ModalityState.NON_MODAL is always write-safe, ModalityState.any() is always write-unsafe.

isWritingAllowed

public abstract boolean isWritingAllowed()

Checks whether the current state allows for writing the model. Must be called from write thread.

Returns:

true is current context is write-safe, false otherwise

isWriteSafeModality

public abstract boolean isWriteSafeModality(ModalityState state)

Checks whether a given modality is write-safe.

Parameters:

state - modality to check

Returns:

true if a given modality is write-safe, false otherwise

submitTransactionLater

@Deprecated
public abstract void submitTransactionLater(Disposable parentDisposable,
                                            java.lang.Runnable transaction)

Deprecated. Replace with Application.invokeLater(java.lang.Runnable) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.

submitTransactionAndWait

@Deprecated
public abstract void submitTransactionAndWait(java.lang.Runnable transaction)
                                       throws ProcessCanceledException

Deprecated. if called on Swing thread, just replace this call with transaction contents. Otherwise, replace with Application.invokeAndWait(java.lang.Runnable, com.intellij.openapi.application.ModalityState) and take care that the default or explicitly passed modality state is write-safe. When in doubt, use ModalityState.NON_MODAL.

Throws:

ProcessCanceledException

submitTransaction

@Deprecated
public abstract void submitTransaction(Disposable parentDisposable,
                                       TransactionId expectedContext,
                                       java.lang.Runnable transaction)

Deprecated. see submitTransaction(Disposable, Runnable).

getContextTransaction

@Deprecated
public abstract TransactionId getContextTransaction()

Deprecated. replace with ModalityState.defaultModalityState() and use the result for "invokeLater" when replacing "submitTransaction" calls.