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}