Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

OnFrontendLostLinkToRouter()

RTRClientEventHandler::OnFrontendLostLinkToRouter();

Prototype


virtual rtr_status_t OnFrontendLostLinkToRouter(RTREvent *pRTREvent, 
                                   RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTREvent

Pointer to an RTREvent object that describes the RTR- generated event being processed.

pController

Pointer to the transaction controller within which this event was received.

Description

This method provides the default handler for the event where the frontend link to the current router has been lost.

The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_FERTRLOSS (99) and any associated data.

Example


MyCLIEventHandler:: OnFrontendLostLinkToRouter ( 
                                    RTREvent  *pRTREvent, 
                                    RTRClientTransactionController *pCTC ) 
{ 
        return RTR_STS_OK; 
}

OnNewKeyRangeAvailable()

RTRClientEventHandler::OnNewKeyRangeAvailable();

Prototype


virtual rtr_status_t OnNewKeyRangeAvailable(RTREvent * pRTREvent, 
                              RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTREvent

Pointer to an RTREvent object that describes the RTR- generated event being processed.

pController

Pointer to the transaction controller within which this event was received.

Description

This method provides the default handler for the event where one or more servers for a new routing key range have become available.

The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_KEYRANGEGAIN (102) and any associated data.

Example


MyCLIEventHandler:: OnNewKeyRangeAvailable ( 
         RTREvent  *pRTREvent, 
         RTRClientTransactionController *pCTC ) 
{ 
 return RTR_STS_OK; 
}

OnKeyRangeNoLongerAvailable()

RTRClientEventHandler::OnKeyRangeNoLongerAvailable();

Prototype


virtual rtr_status_t OnKeyRangeNoLongerAvailable( 
                             RTREvent * pRTREvent, 
                             RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTREvent

Pointer to an RTREvent object that describes the RTR- generated event being processed.

pController

Pointer to the transaction controller within which this event was received.

Description

This method provides the default handler for the event where no more servers remain for a particular routing key range.

The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_KEYRANGELOSS (103) and any associated data.

Example


MyCLIEventHandler:: OnKeyRangeNoLongerAvailable( 
                               RTREvent  *pRTREvent, 
                               RTRClientTransactionController *pCTC ) 
{ 
return RTR_STS_OK; 
}

OnRouterGainedLinkToBackend()

RTRClientEventHandler::OnRouterGainedLinkToBackend();

Prototype


virtual rtr_status_t OnRouterGainedLinkToBackend(RTREvent * pRTREvent, 
                             RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTREvent

Pointer to an RTREvent object that describes the RTR- generated event being processed.

pController

Pointer to the transaction controller within which this event was received.

Description

This method provides the default handler for the event where the current router established a link to the backend.

The client application is receiving an RTR-generated event. RTREvent contains the application-defined event number RTR_EVTNUM_RTRBEGAIN (100) and any associated data.

Example


MyCLIEventHandler::OnRouterGainedLinkToBackend( 
                                    RTREvent  *pRTREvent, 
                                    RTRClientTransactionController *pCTC ) 
{ 
return RTR_STS_OK; 
}

OnRouterLostLinkToBackend()

RTRClientEventHandler::OnRouterLostLinkToBackend();

Prototype


virtual rtr_status_t OnRouterLostLinkToBackend(RTREvent * pRTREvent, 
                                 RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTREvent

Pointer to an RTREvent object that describes the RTR- generated event being processed.

pController

Pointer to the transaction controller within which this event was received.

Description

This method provides the default handler for the event where the current router lost a link to a backend.

The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_RTRBELOSS (101) and any associated data.

Example


MyCLIEventHandler::OnRouterLostLinkToBackend( 
                                  RTREvent  *pRTREvent, 
                                  RTRClientTransactionController *pCTC ) 
{ 
        return RTR_STS_OK; 
}

RTRClientEventHandler()

RTRClientEventHandler::RTRClientEventHandler();

Prototype


RTRClientEventHandler();

Return Value

None

Parameters

None

Description

Construct a client event handler object.

Example


  RTRClientEventHandler::RTRClientEventhandler() 
  { 
  }

3.8 RTRClientMessageHandler

This class defines message handlers for all potential messages that an RTR client application can receive. Each handler has a default behavior. Applications should override those member functions for which they intend to perform application specific processing.

Note
Applications can extend this class by deriving from it and adding their own application-level message handlers.

For further information see RTRData::Dispatch().

RTRClientMessageHandler Class Members

Construction
Method Description
RTRClientMessageHandler() Constructor
~RTRClientMessageHandler() Destructor

Operations
Method Description
OnAccepted(RTRMessage,
RTRClientTransactionController) 		The specified transaction has been accepted by all participants.
OnAllPreparedTransaction
(RTRMessage, RTRClientTransactionController) 		The specified transaction has been prepared by all participants.
OnApplicationMessage
(RTRApplicationMessage, RTRClientTransactionController) 		The server has sent the client a message.
OnInitialize() A new transaction is being processed.
OnRejected(RTRMessage,
RTRClientTransactionController) 		The specified transaction has been rejected by a participant.
OnReturnToSender(RTRMessage,
RTRClientTransactionController) 		The message could not be delivered and has been returned to the sender.

OnAccepted()

RTRClientMessageHandler::OnAccepted();

Prototype


virtual rtr_status_t OnAccepted(RTRMessage *pRTRMessage, 
                         RTRClientTransactionController *pController) 
{ 
 return RTR_STS_OK; 
}

Return Value

None

Parameters

pRTRMessage

Pointer to an RTRApplicationMessage object that describes the message which is being processed.

pController

Pointer to the transaction controller within which this message was received.

Description

The specified transaction has been accepted by all participants.

The default behavior is the handler dismisses the notification.

Example


rtr_status_t ABCCHandlers::OnAccepted( RTRMessage *pRTRMessage, 
RTRClientTransactionController *pController ) 
{ 
        return ABCOrderSucceeded; 
}

OnAllPreparedTransaction()

RTRClientMessageHandler::OnAllPreparedTransaction();

Prototype


virtual rtr_status_t OnAllPreparedTransaction (RTRMessage * pRTRMessage, 
                            RTRClientTransactionController *pController) 
{ 
RTR_STS_OK; 
}

Parameters

pRTRMessage

Pointer to an RTRMessage object that describes the message which is being processed.

pController

Pointer to the transaction controller within which this message was received.

Description

The specified transaction has been prepared by all participants.

The default behavior is the handler dismisses the notification.

Example


rtr_status_t MyCLIMessageHandler::OnAllPreparedTransaction( 
                                   RTRMessage *pmyMsg, 
                                   RTRClientTransactionController *pTC) 
{ 
        cout << "prepare txn " << endl; 
        rtr_return RTR_STS_OK; 
}

OnApplicationMessage()

RTRClientMessageHandler::OnApplicationMessage();

Prototype


virtual rtr_status_t OnApplicationMessage(RTRApplicationMessage 
                                                *pRTRApplicationMessage, 
                             RTRClientTransactionController *pController) 
{ 
RTR_STS_OK; 
}

Return Value

None

Parameters

pRTRApplicationMessage

Pointer to an RTRApplicationMessage object that describes the message which is being processed.

pController

Pointer to the transaction controller within which this message was received.

Description

The RTRApplicationMessage parameter contains application data sent to it by an RTR server.

The default behavior is the handler dismisses the notification.

Example


rtr_status_t MyCLIMessageHandler::OnApplicationMessage( 
                                   RTRApplicationMessage *pmyMsg, 
                                   RTRClientTransactionController *pTC) 
{ 
        return RTR_STS_OK; 
}

OnInitialize()

RTRClientMessageHandler::OnInitialize();

prototype


virtual rtr_status_t OnInitalize()' 
{ 
RTR_STS_OK; 
}

Parameters

None

Description

This method is called at the beginning of each transaction to prepare the server for a transaction. Allowing the application to perform any application-specific initialization necessary to process the transaction.

Example


rtr_status_t MyCLIMessageHandler::OnInitialize() 
{ 
        return RTR_STS_OK; 
 
}

OnRejected()

RTRClientMessageHandler::OnRejected();

prototype


virtual rtr_status_t OnRejected(RTRMessage * pRTRMessage, 
                         RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTRMessage

Pointer to an RTRMessage object that describes the message which is being processed.

pController

Pointer to the transaction controller within which this message was received.

Description

The specified transaction has been rejected by a participant.

The default behavior is the handler dismisses the notification.

Example


rtr_status_t ABCCHandlers::OnRejected( RTRMessage *pRTRMessage, 
RTRClientTransactionController *pController ) 
{ 
        return ABCOrderFailed; 
}

OnReturnToSender()

RTRClientMessageHandler::OnReturnToSender();

prototype


virtual rtr_status_t OnReturnToSender(RTRMessage * pRTRMessage, 
                         RTRClientTransactionController *pController) 
{ 
return RTR_STS_OK; 
}

Parameters

pRTRMessage

Pointer to an RTRMessage object that describes the message which is being processed.

pController

Pointer to the transaction controller within which this message was received.

Description

The message could not be delivered and has been returned to sender.

The default behavior is the handler dismisses the notification.

Example


rtr_status_t MyCLIMessageHandler::OnReturnToSender( 
        RTRMessage *pmyMsg, 
        RTRClientTransactionController *pTC) 
{ 
    return RTR_STS_OK; 
}

RTRClientMessageHandler()

RTRClientMessageHandler::RTRClientMessageHandler();

Prototype


RTRClientMessageHandler(); 
virtual ~RTRClientMessageHandler();

Return Value

None

Parameters

None

Description

Call this constructor to create an RTRClientMessageHandler object.

Example


MyCLIMessageHandler::MyCLIMessageHandler() 
 
{ 
 
} 
 
MyCLIMessageHandler::~MyCLIMessageHandler() 
 
{ 
 
}

3.9 RTRClientTransactionController

RTRClientTransactionController is the main class used to create an RTR client application. The transaction controller object is used to send and receive all data between RTR clients and servers. Typically one instance of this class is used to process multiple consecutive transactions.

RTRClientTransactionController Class Members

Construction
Method Description
RTRClientTransactionController() Constructor
~RTRClientTransactionController() Destructor

Basic Methods
Method Description
AcceptTransaction(rtr_reason_t) Accept the current transaction.
Receive(RTRData, rtr_timout_t) Receive an RTR or application- generated message or an RTR event.
RegsiterClassFactory
(RTRClassFactory) 		Register a class factory for RTR to call when creating RTR Data derived objects.
RegisterFacility(rtr_const_facnam_t, rtr_const_rcpspc_t, rtr_const_access_t) Inform the controller that it should operate within the given facility.
RegisterHandlers
(RTRClientMessageHandler, RTRClientEventHandler) 		Register handlers for messages and events.
RejectTransaction(const rtr_reason_t) Reject the current transaction.
SendApplicationEvent
(RTRApplicationEvent, rtr_const_rcpspc_t, rtr_const_msgfmt_t) 		Send an application-defined event to the server.
SendApplicationMessage
(RTRApplicationMessage, bool, bool, rtr_const_msgfmt_t) 		Send an application-defined message to the server.
StartTransaction(rtr_timout_t) Start a new transaction.

AcceptTransaction()

RTRClientTransactionController::AcceptTransaction();

Prototype


virtual rtr_status_t AcceptTransaction(rtr_reason_t rtrReasonCode = 
                                                         RTR_NO_REASON);

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_NOACCEPT Client or Server has already voted or there is no active transaction.
RTR_STS_NOMESSAGE The data object does not contain a message.
RTR_STS_OK Normal successful completion.
RTR_STS_TXNOTACT No transaction currently active on this channel.

Parameters

rtrReasonCode

Optional reason for accepting the transaction. This reason is OR ed together with the reasons of the other participants in the transaction and returned to all participants of the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason().

Description

Call this member function to accept the transaction currently being processed by this object.

Example


// Let RTR know that this is the only object being sent and that 
// we are done with our work. 
    cout << "AcceptTransaction..." << endl; 
        sStatus = AcceptTransaction(); 
        print_status_on_failure(sStatus);

Receive()

RTRClientTransactionController::Receive();

Prototype


virtual rtr_status_t Receive (RTRData **pRTRData, 
                              rtr_timout_t tTimeout = RTR_NO_TIMOUTMS);

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_INVDATPTRPTARG Invalid pointer-to-data-pointer pointer argument
RTR_STS_NORECEIVE Attempting to receive at this point is not allowed.
RTR_STS_NOMESSAGE The data object does not contain a message.
RTR_STS_OK Normal successful completion.
RTR_STS_TIMOUT Call to Receive timed out.
RTR_STS_TRUNCATED Buffer too short for message. Message has been truncated.

Parameters

pRTRData

A pointer passed by reference, which will receive an object, derived from RTRData. This object can be any of the following:

If a class factory is registered with the transaction controller, the application has the ability to have this object be any application class derived from RTRData. By calling the Dispatch() method, the most over ridden implementation of dispatch will be called.

For more information see the description of the RTR receive model.

tTimeout

An optional receive timeout value in milliseconds. If the timeout expires, the call completes with status RTR_STS_TIMOUT.

Description

This member function should be called when the application is ready to receive messages and events from the RTR framework. Typically this function is called in a loop. The RTRData object returned contains the message or event type as well as other information useful to the application.

For more information see:

RTRData

Example


abc_status ABCOrderTaker::DetermineOutcome() 
{ 
        RTRData  *pResult = NULL; 
        abc_status sStatus = ABCSuccess; 
        bool bDone = false; 
        while (!bDone) 
        { 
               sStatus = Receive(&pResult); 
               print_status_on_failure(sStatus); 
        } 
delete pResult; 
        return sStatus; 
}

Previous Next Contents Index