The R13B03 release.OTP_R13B03

1 files changed, 280 insertions, 0 deletions

diff --git a/lib/cosTransactions/doc/src/ch_example.xml b/lib/cosTransactions/doc/src/ch_example.xml
new file mode 100644
index 0000000000..65350166f0
--- /dev/null
+++ b/lib/cosTransactions/doc/src/ch_example.xml
@@ -0,0 +1,280 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1999</year><year>2009</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 parents 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>
+