Reliable RPC for .NET Wrapper

Introduction to Reliable RPC

In the architecture of modern e-business applications (such as SOA), loosely coupled systems are becoming more and more important. Reliable messaging is one important technology for this type of system.

Reliable RPC is the EntireX implementation of a reliable messaging system. It combines EntireX RPC technology and persistence, which is implemented with units of work (UOWs).

  • Reliable RPC allows asynchronous calls ("fire and forget")

  • Reliable RPC is supported by most EntireX wrappers

  • Reliable RPC messages are stored in the Broker's persistent store until a server is available

  • Reliable RPC clients are able to request the status of the messages they have sent

graphics/reliableRpc_concept.png

Reliable RPC is used to send messages to a persisted Broker service. The messages are described by an IDL program that contains only IN parameters. The client interface object and the server interface object are generated from this IDL file, using the EntireX .NET Wrapper.

Reliable RPC is enabled at runtime. The client has to set one of two different modes before issuing a reliable RPC request:

  • AUTO_COMMIT

  • CLIENT_COMMIT

While AUTO_COMMIT commits each RPC message implicitly after sending it, a series of RPC messages sent in a unit of work (UOW) can be committed or rolled back explicitly using CLIENT_COMMIT mode.

The server is implemented and configured in the same way as for normal RPC.

Writing a Client

All methods for reliable RPC are available on the service class object. See description of class Service for details. The methods are:

  • Service.SetReliableState

  • Service.getReliableState

  • Service.ReliableCommit

  • Service.ReliableRollback

  • Service.GetReliableId

  • Service.GetReliableStatus

Example (this example is included as source in folder examples\ReliableRPC\NetClient)

Create Broker object and interface object. 

Mail mail = new Mail();
mail.service.broker.logon();

Enable reliable RPC with CLIENT_COMMIT:

mail.SetReliableState(Service.ReliableState.RELIABLE_AUTO_COMMIT);

The first RPC message.

mail.Sendmail("mail receiver", "subject 1", "Text 1");

Check the status: get the message ID first and use it to retrieve the status.

StringBuilder reliableID = new StringBuilder();
StringBuilder reliableStatus = new StringBuilder();

mail.service.GetReliableID(ref reliableID);
mail.service.GetReliableStatus(reliableID, ref reliableStatus);
Console.Out.WriteLine("Reliable ID = " + reliableID.ToString());
Console.Out.WriteLine("Reliable Status = " + reliableStatus.ToString());

The second RPC message.

mail.Sendmail("mail receiver", "subject 2", "Text 2");

Commit the two messages.

mail.service.ReliableCommit();

Check the status again for the same message ID.

mail.service.GetReliableStatus(reliableID, ref reliableStatus);
Console.Out.WriteLine("Reliable ID = " + reliableID.ToString());
Console.Out.WriteLine("Reliable Status = " + reliableStatus.ToString());

The third RPC message.

mail.Sendmail("mail receiver", "subject 3", "Text 3");

Check the status: get the new message ID and use it to retrieve the status.

mail.service.GetReliableID(ref reliableID);
mail.service.GetReliableStatus(reliableID, ref reliableStatus);
Console.Out.WriteLine("Reliable ID = " + reliableID.ToString());
Console.Out.WriteLine("Reliable Status = " + reliableStatus.ToString());

Roll back the third message and check status.

mail.service.ReliableRollback();
mail.service.GetReliableStatus(reliableID, ref reliableStatus);

Console.Out.WriteLine("Reliable ID = " + reliableID.ToString());
Console.Out.WriteLine("Reliable Status = " + reliableStatus.ToString());

mail.service.broker.logoff();

Limitations

  1. All program calls that are called in the same transaction (CLIENT_COMMIT) must be in the same IDL library.

  2. It is not allowed to switch from CLIENT_COMMIT to AUTO_COMMIT in a transaction.

  3. Messages (IDL programs) must have IN parameters only.

Writing a Server

There are no server-side methods for reliable RPC. The server does not send back a message to the client. The server can run deferred, thus client and server do not necessarily run at the same time. If the server fails, it throws an exception. This causes the transaction (unit of work inside the broker) to be cancelled, and the error code is written to the user status field of the unit of work.

Broker Configuration

A Broker configuration with PSTORE is recommended. This enables the Broker to store the messages for more than one Broker session. These messages are still available after Broker restart. The attributes STORE, PSTORE, and PSTORE-TYPE in the Broker attribute file can be used to configure this feature. The lifetime of the messages and the status information can be configured with the attributes UWTIME and UWSTAT-LIFETIME. Other attributes such as MAX-MESSAGES-IN-UOW, MAX-UOWS and MAX-UOW-MESSAGE-LENGTH may be used in addition to configure the units of work. See Broker Attributes.

The result of the function Service.GetReliableStatus depends on the configuration of the unit of work status lifetime in the EntireX Broker configuration. If the status is not stored longer than the message, the function returns the error code 00780305 (no matching UOW found).