CosTransactions
Interface Resource

        
interface Resource

The Resource class represents a recoverable resource, that is, a transaction participant that manages data subject to change within a transaction. The Resource class specifies the protocol that must be defined for a recoverable resource. Interfaces that inherit from this class must implement each of the member methods to manage the data appropriately for the recoverable object based on the outcome of the transaction. These methods are invoked by the Transaction Service to execute two-phase commit; the requirements of these methods are described in the following sections.

To become a participant in a transaction, a Resource object must be registered with that transaction. Coordinator::register_resource() can be used to register a resource for the transaction associated with the Coordinator object.

The full name for the class is CosTransactions::Resource.

package org.omg.CosTransactions;

public interface Resource
    extends ResourceOperations,
    org.omg.CORBA.Object,
    org.omg.CORBA.portable.IDLEntity
{
}

The Resource class extends ResourceOperations:

public interface ResourceOperations

{
     org.omg.CosTransactions.Vote prepare() throws org.omg.CosTransactions.HeuristicMixed, org.omg.CosTransactions.HeuristicHazard;

     void rollback() throws org.omg.CosTransactions.HeuristicCommit, org.omg.CosTransactions.HeuristicMixed, org.omg.CosTransactions.HeuristicHazard;

     void commit() throws org.omg.CosTransactions.NotPrepared, org.omg.CosTransactions.HeuristicRollback, org.omg.CosTransactions.HeuristicMixed, org.omg.CosTransactions.HeuristicHazard;

     void commit_one_phase() throws org.omg.CosTransactions.HeuristicHazard;

     void forget();

}

See also:

CosTransactions::Synchronization 

CosTransactions::RecoveryCoordinator 
CosTransactions::Vote 

Two-phase Commit

The two-phase commit requires methods prepare() and commit().

prepare() must be defined to vote on the outcome of the transaction with which the resource is registered. The transaction service invokes this method as the first phase of a two-phase commit; the return value controls the second phase:

• Returns VoteReadOnly if the resource's data is not modified by the transaction. The transaction service does not invoke any other methods on the resource, and the resource can forget all knowledge of the transaction.
• Returns VoteCommit if the resource's data is written to stable storage by the transaction and the transaction is prepared. Based on the outcome of other participants in the transaction, the transaction service calls either commit() or rollback() for the resource. The resource should store a reference to the RecoveryCoordinator object in stable storage to support recovery of the resource.
• Returns VoteRollback for all other situations. The transaction service calls rollback() for the resource, and the resource can forget all knowledge of the transaction.

commit() must be defined to commit all changes made to the resource as part of the transaction. If forget() has already been called, no changes need to be committed. If the resource has not been prepared, the NotPrepared exception must be thrown.

Use the heuristic outcome exceptions to report heuristic decisions related to the resource. The resource must remember heuristic outcomes until forget() is called, so that the same outcome can be returned if the transaction service calls commit() again.

One-phase Commit

commit_one_phase() must be defined to commit all changes made to the resource as part of the transaction. The transaction service may invoke this method if the resource is the only participant in the transaction. Unlike commit(), commit_one_phase() does not require that the resource be prepared first. Use the heuristic outcome exceptions to report heuristic decisions related to the resource. The resource must remember heuristic outcomes until forget() is called, so that the same outcome can be returned if the transaction service calls commit_one_phase() again.

Rollback Transaction

rollback() must be defined to undo all changes made to the resource as part of the transaction. If forget() has been called, no changes need to be undone. Use the heuristic outcome exceptions to report heuristic decisions related to the resource. The resource must remember heuristic outcomes until forget() is called, so that the same outcome can be returned if the transaction service calls rollback() again.

Forget Transaction

forget() must be defined to cause the resource to forget all knowledge of the transaction. The transaction service invokes this method if the resource throws a heuristic outcome exception in response to commit() or rollback().

prepare

CosTransactions::Vote prepare()
raises(
    CosTransactions::HeuristicMixed,
    CosTransactions::HeuristicHazard
)

// Java
public org.omg.CosTransactions.Vote prepare(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.HeuristicMixed,
 org.omg.CosTransactions.HeuristicHazard                

rollback

void rollback()
raises(
    CosTransactions::HeuristicCommit,
    CosTransactions::HeuristicMixed,
    CosTransactions::HeuristicHazard
)

// Java
public void rollback(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.HeuristicCommit,
 org.omg.CosTransactions.HeuristicMixed,
 org.omg.CosTransactions.HeuristicHazard                

commit

void commit()
raises(
    CosTransactions::NotPrepared,
    CosTransactions::HeuristicRollback,
    CosTransactions::HeuristicMixed,
    CosTransactions::HeuristicHazard
)

// Java
public void commit(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.NotPrepared,
 org.omg.CosTransactions.HeuristicRollback,
 org.omg.CosTransactions.HeuristicMixed,
 org.omg.CosTransactions.HeuristicHazard                

commit_one_phase

void commit_one_phase()
raises(
    CosTransactions::HeuristicHazard
)

// Java
public void commit_one_phase(
)
throws org.omg.CORBA.SystemException,
 org.omg.CosTransactions.HeuristicHazard                

forget

void forget()

// Java
public void forget(
)
throws org.omg.CORBA.SystemException