001/* 002 * Copyright 2002-2018 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.transaction.support; 018 019import java.io.Flushable; 020 021/** 022 * Interface for transaction synchronization callbacks. 023 * Supported by AbstractPlatformTransactionManager. 024 * 025 * <p>TransactionSynchronization implementations can implement the Ordered interface 026 * to influence their execution order. A synchronization that does not implement the 027 * Ordered interface is appended to the end of the synchronization chain. 028 * 029 * <p>System synchronizations performed by Spring itself use specific order values, 030 * allowing for fine-grained interaction with their execution order (if necessary). 031 * 032 * @author Juergen Hoeller 033 * @since 02.06.2003 034 * @see TransactionSynchronizationManager 035 * @see AbstractPlatformTransactionManager 036 * @see org.springframework.jdbc.datasource.DataSourceUtils#CONNECTION_SYNCHRONIZATION_ORDER 037 */ 038public interface TransactionSynchronization extends Flushable { 039 040 /** Completion status in case of proper commit. */ 041 int STATUS_COMMITTED = 0; 042 043 /** Completion status in case of proper rollback. */ 044 int STATUS_ROLLED_BACK = 1; 045 046 /** Completion status in case of heuristic mixed completion or system errors. */ 047 int STATUS_UNKNOWN = 2; 048 049 050 /** 051 * Suspend this synchronization. 052 * Supposed to unbind resources from TransactionSynchronizationManager if managing any. 053 * @see TransactionSynchronizationManager#unbindResource 054 */ 055 default void suspend() { 056 } 057 058 /** 059 * Resume this synchronization. 060 * Supposed to rebind resources to TransactionSynchronizationManager if managing any. 061 * @see TransactionSynchronizationManager#bindResource 062 */ 063 default void resume() { 064 } 065 066 /** 067 * Flush the underlying session to the datastore, if applicable: 068 * for example, a Hibernate/JPA session. 069 * @see org.springframework.transaction.TransactionStatus#flush() 070 */ 071 @Override 072 default void flush() { 073 } 074 075 /** 076 * Invoked before transaction commit (before "beforeCompletion"). 077 * Can e.g. flush transactional O/R Mapping sessions to the database. 078 * <p>This callback does <i>not</i> mean that the transaction will actually be committed. 079 * A rollback decision can still occur after this method has been called. This callback 080 * is rather meant to perform work that's only relevant if a commit still has a chance 081 * to happen, such as flushing SQL statements to the database. 082 * <p>Note that exceptions will get propagated to the commit caller and cause a 083 * rollback of the transaction. 084 * @param readOnly whether the transaction is defined as read-only transaction 085 * @throws RuntimeException in case of errors; will be <b>propagated to the caller</b> 086 * (note: do not throw TransactionException subclasses here!) 087 * @see #beforeCompletion 088 */ 089 default void beforeCommit(boolean readOnly) { 090 } 091 092 /** 093 * Invoked before transaction commit/rollback. 094 * Can perform resource cleanup <i>before</i> transaction completion. 095 * <p>This method will be invoked after {@code beforeCommit}, even when 096 * {@code beforeCommit} threw an exception. This callback allows for 097 * closing resources before transaction completion, for any outcome. 098 * @throws RuntimeException in case of errors; will be <b>logged but not propagated</b> 099 * (note: do not throw TransactionException subclasses here!) 100 * @see #beforeCommit 101 * @see #afterCompletion 102 */ 103 default void beforeCompletion() { 104 } 105 106 /** 107 * Invoked after transaction commit. Can perform further operations right 108 * <i>after</i> the main transaction has <i>successfully</i> committed. 109 * <p>Can e.g. commit further operations that are supposed to follow on a successful 110 * commit of the main transaction, like confirmation messages or emails. 111 * <p><b>NOTE:</b> The transaction will have been committed already, but the 112 * transactional resources might still be active and accessible. As a consequence, 113 * any data access code triggered at this point will still "participate" in the 114 * original transaction, allowing to perform some cleanup (with no commit following 115 * anymore!), unless it explicitly declares that it needs to run in a separate 116 * transaction. Hence: <b>Use {@code PROPAGATION_REQUIRES_NEW} for any 117 * transactional operation that is called from here.</b> 118 * @throws RuntimeException in case of errors; will be <b>propagated to the caller</b> 119 * (note: do not throw TransactionException subclasses here!) 120 */ 121 default void afterCommit() { 122 } 123 124 /** 125 * Invoked after transaction commit/rollback. 126 * Can perform resource cleanup <i>after</i> transaction completion. 127 * <p><b>NOTE:</b> The transaction will have been committed or rolled back already, 128 * but the transactional resources might still be active and accessible. As a 129 * consequence, any data access code triggered at this point will still "participate" 130 * in the original transaction, allowing to perform some cleanup (with no commit 131 * following anymore!), unless it explicitly declares that it needs to run in a 132 * separate transaction. Hence: <b>Use {@code PROPAGATION_REQUIRES_NEW} 133 * for any transactional operation that is called from here.</b> 134 * @param status completion status according to the {@code STATUS_*} constants 135 * @throws RuntimeException in case of errors; will be <b>logged but not propagated</b> 136 * (note: do not throw TransactionException subclasses here!) 137 * @see #STATUS_COMMITTED 138 * @see #STATUS_ROLLED_BACK 139 * @see #STATUS_UNKNOWN 140 * @see #beforeCompletion 141 */ 142 default void afterCompletion(int status) { 143 } 144 145}