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

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1999</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>