001/*
002 * ModeShape (http://www.modeshape.org)
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 *       http://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 */
016package org.modeshape.schematic;
017
018/**
019 * Notification interface which is used by ModeShape to tell a 3rd party (typically a {@link SchematicDb}) when a transaction has 
020 * been started, committed or rolled back from ModeShape's perspective. It also informs when locks have been obtained by ModeShape
021 * on certain resources.
022 * <p>
023 * Since ModeShape supports both user-managed transactions and internal transactions, the notification methods from this interface
024 * may be called in different contexts. For example, for a ModeShape-managed transaction the {@link #txStarted(String)} method
025 * will be called immediately after ModeShape starts a new transaction and the {@link #txCommitted(String)} or 
026 * {@link #txRolledback(String)} methods right after ModeShape has committed or rolled back the transaction.
027 * </p>
028 * <p>
029 * On the other hand, for a non ModeShape-managed transaction the {@link #txStarted(String)} method will be called once ModeShape
030 * detects an active external transaction (which may've been created a while back) while the {@link #txCommitted(String)} 
031 * and {@link #txRolledback(String)} methods will be called once the external transaction notifies ModeShape via a transaction
032 * synchronization.
033 * </p> 
034 * 
035 * @author Horia Chiorean (hchiorea@redhat.com)
036 * @since 5.0
037 */
038public interface TransactionListener {
039
040    /**
041     * Called by ModeShape once a ModeShape transaction has been created.
042     * 
043     * @param id the tx id; never null
044     */
045    void txStarted(String id);
046    
047    /**
048     * Called by ModeShape once an existing transaction has been successfully committed. This may be either a single ModeShape
049     * transaction or a longer-spanning user transaction.
050     *
051     * @param id the tx id; never null
052     */
053    void txCommitted(String id);
054
055    /**
056     * Called to indicate tha a transaction has been rolled back.
057     *
058     * @param id the tx id; never null
059     */
060    void txRolledback(String id);
061}