path: root/lib/cosTransactions/doc/src/ch_example.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1999</year><year>2010</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>cosTransactions Examples</title>
    <prepared></prepared>
    <docno></docno>
    <date>1999-04-27</date>
    <rev>A</rev>
    <file>ch_example.xml</file>
  </header>

  <section>
    <title>A Tutorial on How to Create a Simple Service</title>

    <section>
      <title>Interface design</title>
      <p>To use the cosTransactions application <em>participants</em> must be implemented. 
        There are two types of participants: </p>
      <list type="bulleted">
        <item><seealso marker="CosTransactions_Resource">CosTransactions_Resource</seealso> - operations used to commit or rollback resources.</item>
        <item><seealso marker="CosTransactions_SubtransactionAwareResource">CosTransactions_SubtransactionAwareResource</seealso> - 
         operations used when the resources want to be notified when a subtransaction commits. 
         This interface inherits the CosTransactions_Resource</item>
      </list>
      <p>The interfaces for these participants are defined in <em>CosTransactions.idl</em></p>
    </section>

    <section>
      <title>Generating a Participant Interface</title>
      <p>We start by creating an interface which inherits from <em>CosTransactions::Resource</em>. Hence, 
        we must also implement all operations defined in the Resource interface. The IDL-file could look like: </p>
      <code type="c"><![CDATA[
#ifndef _OWNRESOURCEIMPL_IDL
#define _OWNRESOURCEIMPL_IDL
#include <CosTransactions.idl>

module ownResourceImpl {

  interface ownInterface:CosTransactions::Resource {

    void ownFunctions(in any NeededArguments)
       raises(Systemexceptions,OwnExceptions);

  };
};

#endif
      ]]></code>
      <p>Run the IDL compiler on this file by calling the <c>ic:gen/1</c> function. 
        This will produce the API named <c>ownResourceImpl_ownInterface.erl</c>.
        After generating the API stubs and the server skeletons it is time to 
        implement the servers and if no special options are sent 
        to the IDl compiler the file name is <c>ownResourceImpl_ownInterface_impl.erl</c>.</p>
    </section>

    <section>
      <title>Implementation of Participant interface</title>
      <p>If the participant is intended to be a plain Resource, we must implement the following operations:</p>
      <list type="bulleted">
        <item><c>prepare/1</c> - this operation is invoked on the Resource to begin the two-phase commit protocol.</item>
        <item><c>rollback/1</c> - this operation instructs the Resource to rollback all changes made as a part of the transaction. </item>
        <item><c>commit/1</c> - this operation instructs the Resource to commit all changes made as a part of the transaction.</item>
        <item><c>commit_one_phase/1</c> - if possible, the Resource should commit all changes made as part of the transaction. 
         This operation can only be used if the Resource is the only child of its parent. </item>
        <item><c>forget/1</c> - this operation informs the Resource that it is safe to forget any 
        <term id="Heuristic decisions"><termdef>Heuristic decisions is a unilateral decision by a participant to commit
              or rollback without receiving the true outcome of the transaction from its parent's coordinator.</termdef></term>
              and the knowledge of the transaction.</item>
        <item><c>ownFunctions</c> - all application specific operations.</item>
      </list>
      <p>If the participant wants to be notified when a subtransaction commits, we must also implement the following operations 
        (besides the operations above):</p>
      <list type="bulleted">
        <item><c>commit_subtransaction/2</c> - if the <c>SubtransactionAwareResource</c> have been registered 
         with a transactions using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c> it will 
         be notified when the transaction has
         committed. </item>
        <item><c>rollback_subtransaction/1</c> - if the <c>SubtransactionAwareResource</c> have been registered 
         with a transactions using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c>
         it will be notified when the transaction has
         rolled back. </item>
      </list>
      <note>
        <p>The results of a committed subtransaction are relative to the completion of its ancestor transactions, 
          that is, these results can be undone if any ancestor transaction is rolled back. </p>
      </note>
    </section>

    <section>
      <title>Participant Operations Behavior</title>
      <p>Each application participant must behave in a certain way to ensure that the two-phase commit protocol
        can complete the transactions correctly.</p>

      <section>
        <title>prepare</title>
        <p>This operation ask the participant to vote on the outcome of the transaction. Possible replies are:</p>
        <list type="bulleted">
          <item><em>'VoteReadOnly'</em> - if no data associated with the transaction has been modified VoteReadOnly may be returned.
           The Resource can forget all knowledge of the transaction and terminate.</item>
          <item><em>'VoteCommit'</em> - if the Resource is able to write all the data needed to commit the transaction to a stable storage,
           VoteCommit may be returned. The Resource will then wait until it is informed of the outcome of the transaction.
           The Resource may, however, make a unilateral decision (Heuristic) to commit or rollback changes associated 
           with the transaction. When the Resource is informed of the true outcome (rollback/commit) and it is equal to
           the Heuristic decision the Resource just return 'ok'. But, if there is a mismatch and the commit-operation is irreversible,
           the Resource must raise a <seealso marker="CosTransactions_Resource">Heuristic Exception</seealso> and wait 
           until the <c>forget</c> operation is invoked. The Heuristic Decision must be recorded in stable storage.</item>
          <item><em>'VoteRollback'</em> - the Resource may vote VoteRollback under any circumstances.
           The Resource can forget all knowledge of the transaction and terminate.</item>
        </list>
        <note>
          <p>Before replying to the prepare operation, the Resource must record the prepare state, the reference of its
            superior <seealso marker="CosTransactions_RecoveryCoordinator">RecoveryCoordinator</seealso> in stable storage.
            The RecoveryCoordinator is obtained when registering as a participant in a transaction.</p>
        </note>
      </section>

      <section>
        <title>rollback</title>
        <p>The Resource should, if necessary, rollback all changes made as part of the transaction. If the Resource is not aware of the
          transaction it should do nothing, e.g., recovered after a failure and have no data in stable storage. Heuristic Decisions
          must be handled as described above.</p>
      </section>

      <section>
        <title>commit</title>
        <p>The Resource should, if necessary, commit all changes made as part of the transaction. If the Resource is not aware of the
          transaction it should do nothing, e.g., recovered after a failure and have no data in stable storage. Heuristic Decisions
          must be handled as described above.</p>
      </section>

      <section>
        <title>commit_one_phase</title>
        <p>If possible, the Resource should commit all changes made as part of the transaction. If it cannot, it should raise the
          TRANSACTION_ROLLEDBACK exception. This operation can only be used if the Resource is the only child of its parent.
          If a failure occurs the completion of the operation must be retried when the failure is repaired. Heuristic Decisions
          must be handled as described above.</p>
      </section>

      <section>
        <title>forget</title>
        <p>If the Resource raised a Heuristic Exception to <c>commit</c>, <c>rollback</c> or <c>commit_one_phase</c> this operation
          will be performed. The Resource can forget all knowledge of the transaction and terminate.</p>
      </section>

      <section>
        <title>commit_subtransaction</title>
        <p>If the <c>SubtransactionAwareResource</c> have been registered with a <em>subtransaction</em>
          using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c>
          it will be notified when the transaction has committed. The Resource may raise the exception
          <c>'TRANSACTION_ROLLEDBACK'</c>.</p>
        <note>
          <p>The result of a committed subtransaction is relative to the completion of its ancestor
            transactions, that is, these results can be undone if any ancestor transaction is rolled back.</p>
        </note>
      </section>

      <section>
        <title>rollback_subtransaction</title>
        <p>If the <c>SubtransactionAwareResource</c> have been registered with a <em>subtransaction</em>
          using the operation <c>CosTransactions_Coordinator:register_subtran_aware/2</c>
          it will be notified when the subtransaction has rolled back.</p>
      </section>
    </section>

    <section>
      <title>How to Run Everything</title>
      <p>Below is a short transcript on how to run cosTransactions. </p>
      <code type="none">

%% Start Mnesia and Orber
mnesia:delete_schema([node()]),
mnesia:create_schema([node()]),
orber:install([node()]),
application:start(mnesia),
application:start(orber),

%% Register CosTransactions in the IFR.
'oe_CosTransactions':'oe_register'(), 

%% Register the application specific Resource implementations
%% in the IFR.
'oe_ownResourceImpl':'oe_register'(), 

%%-- Set parameters --
%% Timeout can be either 0 (no timeout) or an integer N > 0.
%% The later state that the transaction should be rolled 
%% back if the transaction have not completed within N seconds.
TimeOut = 0,

%% Do we want the transaction to report Heuristic Exceptions?
%% This variable must be boolean and indicates the way the
%% Terminator should behave.
Heuristics = true,

%% Start the cosTransactions application.
cosTransactions:start(),  %% or application:start(cosTransactions),

%% Start a factory using the default configuration
TrFac = cosTransactions:start_factory(),
%% ... or use configuration parameters.
TrFac = cosTransactions:start_factory([{typecheck, false}, {hash_max, 3013}]),

%% Create a new top-level transaction.
Control = 'CosTransactions_TransactionFactory':create(TrFac, TimeOut),

%% Retrieve the Coordinator and Terminator object references from
%% the Control Object.
Term = 'CosTransactions_Control':get_terminator(Control),
Coord = 'CosTransactions_Control':get_coordinator(Control),

%% Create two SubTransactions with the root-Coordinator as parent.
SubCont1 = 'CosTransactions_Coordinator':create_subtransaction(Coord),
SubCont2 = 'CosTransactions_Coordinator':create_subtransaction(Coord),

%% Retrieve the Coordinator references from the Control Objects.
SubCoord1 = 'CosTransactions_Control':get_coordinator(SubCont1),
SubCoord2 = 'CosTransactions_Control':get_coordinator(SubCont2),

%% Create application Resources. We can, for example, start the Resources 
%% our selves or look them up in the naming service. This is application
%% specific.
Res1 = ...
Res2 = ...
Res3 = ...
Res4 = ...

%% Register Resources with respective Coordinator. Each call returns
%% a RecoveryCoordinator object reference.
RC1 = 'CosTransactions_Coordinator':register_resource(SubCoord1, Res1),
RC2 = 'CosTransactions_Coordinator':register_resource(SubCoord1, Res2),
RC3 = 'CosTransactions_Coordinator':register_resource(SubCoord2, Res3),
RC4 = 'CosTransactions_Coordinator':register_resource(SubCoord2, Res4),

%% Register Resource 4 with SubCoordinator 1 so that the Resource will be 
%% informed when the SubCoordinator commits or roll-back.
'CosTransactions_Coordinator':register_subtran_aware(SubCoord1, Res4),

%% We are now ready to try to commit the transaction. The second argument
%% must be a boolean
Outcome = (catch 'CosTransactions_Terminator':commit(Term, Heuristics)),
      </code>
      <note>
        <p>For the cosTransaction application to be able to recognize if a Resource is
          dead or in the process of restarting the Resource must be started as persistent,
          e.g., 'OwnResource':oe_create_link(Env, [{regname, {global, RegName}}, {persistent, true}]).
          For more information see the Orber documentation.</p>
      </note>
      <p>The outcome of the transaction can be:</p>
      <list type="bulleted">
        <item>ok - the transaction was successfully committed.</item>
        <item>{'EXCEPTION', HeuristicExc} - at least one participant made a
         Heuristic decision or, due to a failure, one or more participants
         where unreachable.</item>
        <item>{'EXCEPTION', #'TRANSACTION_ROLLEDBACK'{}} - 
         the transaction was successfully rolled back.</item>
        <item>Any system exception - 
         the transaction failed with unknown reason.</item>
      </list>
    </section>
  </section>
</chapter>