    001/*
    002 * Copyright (c) 2009 The openGion Project.
    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,
    013 * either express or implied. See the License for the specific language
    014 * governing permissions and limitations under the License.
    015 */
    016package org.opengion.fukurou.db;
    017
    018import java.sql.Connection;
    019
    020/**
    021 * コネクションを共有して、トランザクションを実現するインターフェースです。
    022 *
    023 * 基本的には、TransactionTag で利用されますが、一部、このオブジェクトを
    024 * 渡して、直接、利用するケースもあります。
    025 *
    026 * トランザクション の実クラスには、close()時に、commit,rollback を行う、
    027 * TransactionReal クラスと、内部にキャッシュされた コネクションを、終了時点で
    028 * 一括処理を行う、TransactionImpl があります。
    029 * TransactionTag で利用するのが、TransactionImpl で、Connectionのラッパーとして
    030 * 利用するのが、TransactionReal クラスになります。
    031 *
    032 * 6.3.6.1 (2015/08/28)
    033 *   selectを実行した後で明示的にcommit,rollbackを行わないのはOracle位
    034 *   らしいので、検索終了時でも、commit か、rollback を行うようにします。
    035 *   つまり、commit されない(=途中で処理が打ち切られた)場合は、
    036 *   rollback するように仕様変更しますので、Transactionオブジェクトを
    037 *   呼び出した処理の最後には、検索であろうとなかろうと、commit()を入れてください。
    038 *   ただし、Transaction オブジェクトは、DBアクセス以外にも適用可能に
    039 *   作成しているため、Connection がある場合のみ、実際の commit/rollback が
    040 *   実行されます。
    041 *
    042 * @og.rev 5.1.9.0 (2010/08/01) 新規作成
    043 *
    044 * @version  5.0
    045 * @author       Kazuhiko Hasegawa
    046 * @since    JDK6.0,
    047 */
    048public interface Transaction extends AutoCloseable {
    049
    050        /**
    051         * 指定のDBID に対応した、Connection オブジェクトを返します。
    052         * 内部Mapに存在していれば、そのコネクションを、存在しなければ、
    053         * 新しく作成します。
    054         *
    055         * Connection をキャッシュに戻すなどは、Transaction実装クラスで行います。
    056         *
    057         * @param       dbid  接続先ID
    058         *
    059         * @return      指定のDBID に対応した、コネクションオブジェクト
    060         */
    061        Connection getConnection( final String dbid ) ;
    062
    063        /**
    064         * コミット処理が行われた場合に、内部フラグ(isCommit)を true にセットします。
    065         * １回でもコミットが行われており、ロールバックが行われていなければ、
    066         * コミットされます。
    067         *
    068         * 検索処理時でも、最後に commit() を実行してください。実行されていない場合は、
    069         * 自動的に、rollback() が、実行されます。
    070         *
    071         * @og.rev 6.3.6.1 (2015/08/28) AutoCloseable の close() メソッドに対応。return 不要。
    072         */
    073        void commit() ;
    074
    075        /**
    076         * ロールバック処理が行われた場合に、内部フラグ(isRollback)を true にセットします。
    077         * １回でもロールバックが行われていれば、最終的にはロールバックされます。
    078         *
    079         * 一度も、ロールバックが行われていない場合でも、コミットが行われていない場合は、
    080         * rollback()を実行します。
    081         *
    082         * @og.rev 6.3.6.1 (2015/08/28) AutoCloseable の close() メソッドに対応。return 不要。
    083         */
    084        void rollback() ;
    085
    086        /**
    087         * トランザクションの、終了時処理を行います。
    088         *
    089         * それまでの処理は、すべて正常に処理できた場合に、使用します。
    090         *
    091         * @og.rev 6.3.6.1 (2015/08/28) AutoCloseable の close() メソッドに対応。return 不要。
    092         *
    093         * @see AutoCloseable#close()
    094         */
    095        @Override       // AutoCloseable
    096        void close();
    097
    098        /**
    099         * 最終的なコミットが行われた場合に、内部フラグ(isEndCommit)を true にセットします。
    100         * 通常は、この処理は、１値度だけ実行されます。
    101         * 初期値が、false なので、途中で一度でも実行されると、true にセットされ、最後まで
    102         * 処理されたとみなされてしまうので、注意してください。
    103         *
    104         * 通常は、タグリブの、doEndTag() が実行された場合に、呼びます。
    105         * このフラグが、true でないと（つまり、一度でも呼ばれないと）最終的に、commit されません。
    106         *
    107         * なお、endCommit() が呼ばれると、自動的に、commit() も呼んでおきます。
    108         *
    109         * @og.rev 6.4.3.3 (2016/03/04) 一般的なタグで、SKIP_PAGE された場合、rollback するようにします。
    110         */
    111        void endCommit() ;
    112}