transaction
Interface IResourceManager

All Superinterfaces:
java.rmi.Remote
All Known Implementing Classes:
ResourceManagerImpl

public interface IResourceManager
extends java.rmi.Remote

/** Interface for a simple Resource Manager for the Distributed Travel Reservation System. A single resource manager can be used to manage arbitrary resources, e.g. hotels, rental cars or flights.

Failure reporting is done using two pieces, exceptions and return values. Exceptions are used for systemy things - like transactions that were forced to abort, or don't exist. Return values are used for operations that would affect the consistency of the database, like the reservation of a data item that the database does not know about.

If there is a return value and you're not sure how it would be used in your implementation, ignore it. Return values in the interface are used generously to allow flexibility in implementation.

Author:
bross

Field Summary
static java.lang.String RMI_NAME_CAR_RM
           
static java.lang.String RMI_NAME_FLIGHT_RM
           
static java.lang.String RMI_NAME_HOTEL_RM
           
 
Method Summary
 void abort(int xid)
          Abort transaction.
 boolean addResource(int xid, java.lang.String rid, int num, int price)
          Add a new resource (e.g. hotel) to the database.
 int begin()
          Deprecated. Only distributed transaction should by allowed from now on. Begin a new local transaction, and return its transaction id.
 boolean beginDistributed(int globalXID)
          Begin a new distributed transaction.
 boolean commit(int xid)
          Commit transaction.
 void dieAfterPointerSwitch()
          Closes ResourceManager by calling System.exit(-1) right after switching the pointer to the shadow copy file.
 void dieBeforePointerSwitch()
          Closes ResourceManager by calling System.exit(-1) right before switching the pointer to the shadow copy file.
 void dieNow()
          immediately closes the ResourceManager by calling System.exit(-1)
 boolean newCustomer(int xid, java.lang.String custName)
          Add a new customer to the database.
 boolean prepare(int globalXID)
          This method is part of the 2PC protocol for atomic committment of distributed transactions.
 int queryCustomerBill(int xid, java.lang.String custName)
          Query the bill of a customer.
 int queryResourceAvailability(int xid, java.lang.String rid)
          Query the availability of a resource.
 int queryResourcePrice(int xid, java.lang.String rid)
          Query the price of a resource.
 boolean reserveResource(int xid, java.lang.String rid, java.lang.String custName)
          Reserve a resource for a given customer.
 boolean shutdown()
          Shutdown gracefully.
 void start(java.lang.String workingdir, java.lang.String rmiName)
           
 boolean updateResource(int xid, java.lang.String rid, int num, int price)
          Update the attributes (total capacity and price) of a resource.
 

Field Detail

RMI_NAME_HOTEL_RM

static final java.lang.String RMI_NAME_HOTEL_RM
See Also:
Constant Field Values

RMI_NAME_FLIGHT_RM

static final java.lang.String RMI_NAME_FLIGHT_RM
See Also:
Constant Field Values

RMI_NAME_CAR_RM

static final java.lang.String RMI_NAME_CAR_RM
See Also:
Constant Field Values
Method Detail

start

void start(java.lang.String workingdir,
           java.lang.String rmiName)
           throws java.rmi.RemoteException
Throws:
java.rmi.RemoteException

begin

int begin()
          throws ShutdownException,
                 java.rmi.RemoteException
Deprecated. Only distributed transaction should by allowed from now on. Begin a new local transaction, and return its transaction id.

Returns:
A unique local transaction ID > 0.
Throws:
ShutdownException - thrown if no new transactions can be accepted due to shutdown of the resource manager
java.rmi.RemoteException

beginDistributed

boolean beginDistributed(int globalXID)
                         throws ShutdownException,
                                java.rmi.RemoteException,
                                InvalidTransactionException
Begin a new distributed transaction. Part of starting a new distributed transaction is to call the transaction manager's enlist() method in order to register this RM as a participant of the given distributed transaction.

Parameters:
globalXID - the id of the distributed transaction which will be the parent of this local subtransaction. Use this id to enlist this RM at the transaction manager.
Returns:
true if successful, false otherwise
Throws:
ShutdownException - thrown if no new transactions can be accepted due to shutdown of the resource manager
InvalidTransactionException - if a distributed transaction with this globalXID has already been started at this RM
java.rmi.RemoteException

prepare

boolean prepare(int globalXID)
                throws InvalidTransactionException,
                       java.rmi.RemoteException
This method is part of the 2PC protocol for atomic committment of distributed transactions.

Parameters:
globalXID - the transaction ID of the distributed transaction which needs to be prepared for commitment
Returns:
true if prepare was successful, false otherwise
Throws:
InvalidTransactionException
java.rmi.RemoteException

commit

boolean commit(int xid)
               throws TransactionAbortedException,
                      InvalidTransactionException,
                      java.rmi.RemoteException
Commit transaction.

Parameters:
xid - id of transaction to be committed.
Returns:
true on success, false on failure.
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

abort

void abort(int xid)
           throws InvalidTransactionException,
                  java.rmi.RemoteException
Abort transaction.

Parameters:
xid - id of transaction to be aborted.
Throws:
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

newCustomer

boolean newCustomer(int xid,
                    java.lang.String custName)
                    throws TransactionAbortedException,
                           InvalidTransactionException,
                           java.rmi.RemoteException
Add a new customer to the database. A customer is identified by his unique customer name (e.g. Smith)

Parameters:
xid - the id of the transaction requesting this operation
custName - the unique customer name
Returns:
true if the operation succeeded, false otherwise (e.g. customer already exists or name is null, etc.)
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

queryCustomerBill

int queryCustomerBill(int xid,
                      java.lang.String custName)
                      throws TransactionAbortedException,
                             InvalidTransactionException,
                             java.rmi.RemoteException
Query the bill of a customer.

Parameters:
xid - the id of the transaction requesting this operation
custName - the unique customer name whose bill should be calculated
Returns:
the sum of costs accumulated due to reservations of this customer, -1 if the customer does not exist
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

addResource

boolean addResource(int xid,
                    java.lang.String rid,
                    int num,
                    int price)
                    throws TransactionAbortedException,
                           InvalidTransactionException,
                           java.rmi.RemoteException
Add a new resource (e.g. hotel) to the database. A resource is identified by a unique name (e.g. HotelA).

Parameters:
xid - the id of the transaction requesting this operation
rid - the unique identifier of the resource which is to be added (e.g. HotelA)
num - the total capacity of this resource
price - the price a customer needs to pay for reserving this resource
Returns:
true if the operation succeeded, false otherwise (e.g. resource already exists)
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

updateResource

boolean updateResource(int xid,
                       java.lang.String rid,
                       int num,
                       int price)
                       throws TransactionAbortedException,
                              InvalidTransactionException,
                              java.rmi.RemoteException
Update the attributes (total capacity and price) of a resource.

Parameters:
xid - the id of the transaction requesting this operation
rid - the unique identifier of the resource which is to be added (e.g. HotelA)
num - a number indicating the change in total capacity, negative numbers decrease capacity, positive values increase capacity
price - the price a customer needs to pay for reserving this resource
Returns:
true if the operation succeeded, false otherwise (e.g. decrease > total capacity - reservations)
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

queryResourceAvailability

int queryResourceAvailability(int xid,
                              java.lang.String rid)
                              throws TransactionAbortedException,
                                     InvalidTransactionException,
                                     java.rmi.RemoteException
Query the availability of a resource.

Parameters:
xid - the id of the transaction requesting this operation
rid - the unique identifier of the resource
Returns:
the current availability (i.e. total capacity - reservations), -1 if the resource does not exist
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

queryResourcePrice

int queryResourcePrice(int xid,
                       java.lang.String rid)
                       throws TransactionAbortedException,
                              InvalidTransactionException,
                              java.rmi.RemoteException
Query the price of a resource.

Parameters:
xid - the id of the transaction requesting this operation
rid - the unique identifier of the resource
Returns:
the price of the resource, -1 if the resource does not exist
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

reserveResource

boolean reserveResource(int xid,
                        java.lang.String rid,
                        java.lang.String custName)
                        throws TransactionAbortedException,
                               InvalidTransactionException,
                               java.rmi.RemoteException
Reserve a resource for a given customer. The availability of the resource is decreased by one.

Parameters:
xid - the id of the transaction requesting this operation
rid - the unique identifier of the resource
custName - the unique name of the customer
Returns:
true if the operation succeeded, false otherwise (e.g. customer or resource do not exist, or no availability)
Throws:
TransactionAbortedException - if transaction was aborted.
InvalidTransactionException - if transaction id is invalid.
java.rmi.RemoteException

shutdown

boolean shutdown()
                 throws java.rmi.RemoteException
Shutdown gracefully. Stop accepting new transactions, wait for running transactions to terminate, and clean up disk state. When this RM restarts, it should not attempt to recover its state if the client called shutdown to terminate it.

Returns:
true on success, false on failure.
Throws:
java.rmi.RemoteException

dieNow

void dieNow()
            throws java.rmi.RemoteException
immediately closes the ResourceManager by calling System.exit(-1)

Throws:
java.rmi.RemoteException

dieBeforePointerSwitch

void dieBeforePointerSwitch()
                            throws java.rmi.RemoteException
Closes ResourceManager by calling System.exit(-1) right before switching the pointer to the shadow copy file.

Throws:
java.rmi.RemoteException

dieAfterPointerSwitch

void dieAfterPointerSwitch()
                           throws java.rmi.RemoteException
Closes ResourceManager by calling System.exit(-1) right after switching the pointer to the shadow copy file.

Throws:
java.rmi.RemoteException