# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# OnFacilityReady()

## RTRClientEventHandler::OnFacilityReady();

## Prototype

>     virtual rtr_status_t OnFacilityReady(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 facility has become operational.

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

## Example

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

# OnFrontendGainedLinkToRouter()

## RTRClientEventHandler::OnFrontendGainedLinkToRouter();

## Prototype

>     virtual rtr_status_t OnFrontendGainedLinktToRouter(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 a frontend link to the current router has been established.

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

## Example

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

# 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;
>     }

# 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;
>     }

# 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;
>     }

# 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.

Previous | Next | Contents | Index