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

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

<erlref>
  <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_Resource</title>
    <prepared></prepared>
    <docno></docno>
    <checked></checked>
    <date>1999-04-12</date>
    <rev>PA1</rev>
  </header>
  <module>CosTransactions_Resource</module>
  <modulesummary>This module implements the OMG CosTransactions::Resource interface.</modulesummary>
  <description>
    <p>To get access to the record definitions for the structures use:      <br></br>
<c>-include_lib("cosTransactions/include/CosTransactions.hrl").</c></p>
  </description>
  <funcs>
    <func>
      <name>commit(Resource) -> Return</name>
      <fsummary>Instruct the target object to commit the transaction</fsummary>
      <type>
        <v>Resource = #objref</v>
        <v>Return = ok | {'EXCEPTION', E}</v>
        <v>E = #'CosTransactions_NotPrepared'{} | #'CosTransactions_HeuristicRollback'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v>
      </type>
      <desc>
        <p>This operation instructs the Resource to commit all changes made as a part of the transaction.</p>
        <p>The Resource can raise:</p>
        <list type="bulleted">
          <item>Heuristic Exception - if a Heuristic decision is made which differ
           from the true outcome of the transaction. The Resource must remember
           the Heuristic outcome until the <c>forget</c> operation is performed.</item>
        </list>
      </desc>
    </func>
    <func>
      <name>commit_one_phase(Resource) -> Return</name>
      <fsummary>Instruct the target object to commit the transaction</fsummary>
      <type>
        <v>Resource = #objref</v>
        <v>Return = ok | {'EXCEPTION', E}</v>
        <v>E = #'CosTransactions_HeuristicHazard'{} | #'CosTransactions_TransactionRolledBack'{}</v>
      </type>
      <desc>
        <p>If possible, the Resource should commit all changes made as part of the transaction,
          else it should raise the TRANSACTION_ROLLEDBACK exception. 
          This operation can only be used if the Resource is the only child of its parent.</p>
      </desc>
    </func>
    <func>
      <name>forget(Resource) -> Return</name>
      <fsummary>Instruct the target object to forget any heuristic decisions</fsummary>
      <type>
        <v>Resource = #objref</v>
        <v>Return = ok</v>
      </type>
      <desc>
        <p>This operation informs the Resource that it is safe to forget any Heuristic
          decisions and the knowledge of the transaction.</p>
      </desc>
    </func>
    <func>
      <name>prepare(Resource) -> Return</name>
      <fsummary>Instruct the target object to begin the two-phase commit protocol</fsummary>
      <type>
        <v>Resource = #objref</v>
        <v>Return = Vote | {'EXCEPTION', E}</v>
        <v>Vote = 'VoteReadOnly' | 'VoteCommit' | 'VoteRollback'</v>
        <v>E = #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v>
      </type>
      <desc>
        <p>This operation is invoked on the Resource to begin the two-phase commit protocol.</p>
        <p>The Resource can reply:</p>
        <list type="bulleted">
          <item>'VoteReadOnly' - if no persistent data has been modified by the transaction. 
           The Resource can forget all knowledge of the transaction. </item>
          <item>'VoteCommit' - if the Resource has been prepared and is able to write all the
           data needed to commit the transaction to stable storage.</item>
          <item>'VoteRollback' - under any circumstances but must do so if none of the alternatives above
           are applicable.</item>
          <item>Heuristic Exception - if a Heuristic decision is made which differ
           from the true outcome of the transaction. The Resource must remember
           the Heuristic outcome until the <c>forget</c> operation is performed.</item>
        </list>
      </desc>
    </func>
    <func>
      <name>rollback(Resource) -> Return</name>
      <fsummary>Instruct the target object to rollback the transaction</fsummary>
      <type>
        <v>Resource = #objref</v>
        <v>Return = ok | {'EXCEPTION', E}</v>
        <v>E = #'CosTransactions_HeuristicCommit'{} | #'CosTransactions_HeuristicMixed'{} | #'CosTransactions_HeuristicHazard'{}</v>
      </type>
      <desc>
        <p>This operation instructs the Resource to rollback all changes made as a part of the transaction.</p>
        <p>The Resource can raise:</p>
        <list type="bulleted">
          <item>Heuristic Exception - if a Heuristic decision is made which differ
           from the true outcome of the transaction. The Resource must remember
           the Heuristic outcome until the <c>forget</c> operation is performed.</item>
        </list>
      </desc>
    </func>
  </funcs>
  
</erlref>