001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2019 microBean.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.narayana.jta.cdi;
018
019import java.util.Objects;
020
021import javax.transaction.HeuristicMixedException;
022import javax.transaction.HeuristicRollbackException;
023import javax.transaction.InvalidTransactionException;
024import javax.transaction.NotSupportedException;
025import javax.transaction.RollbackException;
026import javax.transaction.Status; // for javadoc only
027import javax.transaction.SystemException;
028import javax.transaction.Transaction;
029import javax.transaction.TransactionManager;
030
031/**
032 * An {@code abstract} {@link TransactionManager} implementation that
033 * delegates all method invocations to another {@link
034 * TransactionManager}.
035 *
036 * @author <a href="https://about.me/lairdnelson" target="_parent">Laird Nelson</a>
037 *
038 * @see TransactionManager
039 */
040public abstract class DelegatingTransactionManager implements TransactionManager {
041
042  private final TransactionManager delegate;
043
044  /**
045   * Creates a new {@link DelegatingTransactionManager}.
046   *
047   * @param delegate the {@link TransactionManager} to which all
048   * method invocations will be delegated; must not be {@code null}
049   *
050   * @exception NullPointerException if {@code delegate} is {@code null}
051   */
052  protected DelegatingTransactionManager(final TransactionManager delegate) {
053    super();
054    this.delegate = Objects.requireNonNull(delegate);
055  }
056
057  /**
058   * Creates a new transaction and associates it with the current thread.
059   *
060   * @exception NotSupportedException if the thread is already
061   * associated with a transaction and this {@link TransactionManager}
062   * implementation does not support nested transactions
063   *
064   * @exception SystemException if this {@link TransactionManager}
065   * encounters an unexpected error condition
066   */
067  @Override
068  public void begin() throws NotSupportedException, SystemException {
069    this.delegate.begin();
070  }
071
072  /**
073   * Completes the transaction associated with the current thread.
074   *
075   * <p>When this method completes, the thread is no longer associated
076   * with a transaction.</p>
077   *
078   * @exception RollbackException if the transaction has been rolled
079   * back rather than committed
080   *
081   * @exception HeuristicMixedException if a heuristic decision was
082   * made and that some relevant updates have been committed while
083   * others have been rolled back
084   *
085   * @exception HeuristicRollbackException if a heuristic decision was
086   * made and all relevant updates have been rolled back
087   *
088   * @exception SecurityException if the thread is not allowed to
089   * commit the transaction
090   *
091   * @exception IllegalStateException if the current thread is not
092   * associated with a transaction
093   *
094   * @exception SystemException if this {@link TransactionManager}
095   * encounters an unexpected error condition
096   */
097  @Override
098  public void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SystemException {
099    this.delegate.commit();
100  }
101
102  /**
103   * Returns the status of the transaction associated with the current
104   * thread.
105   *
106   * @return the transaction status expressed as the value of one of
107   * the {@code int} constants in the {@link Status} class; if no
108   * transaction is associated with the current thread, this method
109   * returns {@link Status#STATUS_NO_TRANSACTION}
110   *
111   * @exception SystemException if this {@link TransactionManager}
112   * encounters an unexpected error condition
113   *
114   * @see Status
115   */
116  @Override
117  public int getStatus() throws SystemException {
118    return this.delegate.getStatus();
119  }
120
121  /**
122   * Returns the {@link Transaction} object that represents the
123   * transaction context of the calling thread.
124   *
125   * <p>This method never returns {@code null}.</p>
126   *
127   * @return the {@link Transaction} object representing the
128   * transaction associated with the calling thread; never {@code
129   * null}
130   *
131   * @exception SystemException if this {@link TransactionManager}
132   * encounters an unexpected error condition
133   */
134  @Override
135  public Transaction getTransaction() throws SystemException {
136    return this.delegate.getTransaction();
137  }
138
139  /**
140   * Resumes the transaction context association of the calling thread
141   * with the transaction represented by the supplied {@link
142   * Transaction} object.
143   *
144   * <p>When this method returns, the calling thread is associated
145   * with the transaction context specified.</p>
146   *
147   * @param transaction the {@link Transaction} representing the
148   * transaction to be resumed; must not be {@code null}
149   *
150   * @exception InvalidTransactionException if {@code transaction} is
151   * invalid
152   *
153   * @exception IllegalStateException if the thread is already
154   * associated with another transaction
155   *
156   * @exception SystemException if this {@link TransactionManager}
157   * encounters an unexpected error condition
158   */
159  @Override
160  public void resume(final Transaction transaction) throws InvalidTransactionException, SystemException {
161    this.delegate.resume(transaction);
162  }
163
164  /**
165   * Rolls back the transaction associated with the current thread.
166   *
167   * <p>When this method completes, the thread is no longer associated
168   * with a transaction.</p>
169   *
170   * @exception SecurityException if the thread is not allowed to roll
171   * back the transaction
172   *
173   * @exception IllegalStateException if the current thread is not
174   * associated with a transaction
175   *
176   * @exception SystemException if this {@link TransactionManager}
177   * encounters an unexpected error condition
178   */
179  @Override
180  public void rollback() throws SystemException {
181    this.delegate.rollback();
182  }
183
184  /**
185   * Irrevocably modifies the transaction associated with the current
186   * thread such that the only possible outcome is for it to
187   * {@linkplain #rollback() roll back}.
188   *
189   * @exception IllegalStateException if the current thread is not
190   * associated with a transaction
191   *
192   * @exception SystemException if this {@link TransactionManager}
193   * encounters an unexpected error condition
194   */
195  @Override
196  public void setRollbackOnly() throws SystemException {
197    this.delegate.setRollbackOnly();
198  }
199
200  /**
201   * Sets the timeout value that is associated with transactions
202   * started by the current thread with the {@link #begin()} method.
203   *
204   * <p>If an application has not called this method, the transaction
205   * service uses some default value for the transaction timeout.</p>
206   *
207   * @param seconds the timeout in seconds; if the value is zero, the
208   * transaction service restores the default value; if the value is
209   * negative a {@link SystemException} is thrown
210   *
211   * @exception SystemException if this {@link TransactionManager}
212   * encounters an unexpected error condition or if {@code seconds} is
213   * less than zero
214   */
215  @Override
216  public void setTransactionTimeout(final int seconds) throws SystemException {
217    this.delegate.setTransactionTimeout(seconds);
218  }
219
220  /**
221   * Suspends the transaction currently associated with the calling
222   * thread and returns a {@link Transaction} that represents the
223   * transaction context being suspended, or {@code null} if the
224   * calling thread is not associated with a transaction.
225   *
226   * <p>This method may return {@code null}.</p>
227   *
228   * <p>When this method returns, the calling thread is no longer
229   * associated with a transaction.</p>
230   *
231   * @return a {@link Transaction} representing the suspended
232   * transaction, or {@code null}
233   *
234   * @exception SystemException if this {@link TransactionManager}
235   * encounters an unexpected error condition
236   */
237  @Override
238  public Transaction suspend() throws SystemException {
239    return this.delegate.suspend();
240  }
241
242}