06. Message Router

Table of contents

1. General Information
2. Router Setup
3. Router Configuration
4. Connection Initialization

---

General Information

The AREG Framework leverages the robust Object Remote Procedure Call (ORPC) protocol for seamless communication between its software components. Facilitating this communication is the Multicast Message Router, also known as the Message Router. This essential component forms a network of interconnected applications and efficiently routes messages to the targets. In this chapter, we will provide an overview of the Multicast Message Router and provide guidance on its configuration.

[ ↑ Back to top ↑ ]

---

Router Setup

The Multicast Router, an integral part of the AREG Framework, is implemented in the mcrouter module. It is compiled as a standalone executable, offering the flexibility to run either as a console application or as a service managed by Windows or Linux operating systems. The Multicast Router can be deployed on any machine operating a General Purpose Operating System (GPOS) within the network.

To streamline the setup process on Windows, the Multicast Router includes two files for easy installation (mcrouter_install.bat) and uninstallation (mcrouter_uninstall.bat). Execute these scripts to configure the router and run it as a service. While it is recommended to start the Multicast Router first, there are no strict restrictions on the startup sequence.

Once the Multicast Router is launched, all other applications should be configured to establish a connection with it. Although the communication engine of AREG-enabled applications will automatically retry establishing a connection, it is advisable to start the Multicast Router beforehand. As soon as the socket connection is successfully established, applications can proceed to register or wait for service availability before initiating communication.

[ ↑ Back to top ↑ ]

---

Router Configuration

The configuration of the Multicast Router, as well as applications, relies on the router.init configuration file by default. This file adheres to a straightforward syntax, consisting of key and value pairs. The key includes a mandatory section and property, with optional module and position elements. The syntax follows the format: section.property[.module][.position] = value.

To gain a comprehensive understanding of the configuration syntax, please consult the Persistence Syntax section in the AREG SDK Wiki. It provides detailed information and further guidance on configuring the initialization file.

Below is an example of a typical Multicast Router configuration file:

connection.type             = tcpip	# protocol, currently only supports 'tcpip' (TCP/IP)
connection.enable.tcpip     = true	# if set to 'true', enables the service mcrouter connection
connection.name.tcpip       = TCPIP	# a unique connection name within the system
connection.address.tcpip    = 127.0.0.1 # the address of the service mcrouter host
connection.port.tcpip       = 8181	# the service mcrouter connection port

Each property within the connection section contains a value that configures the connection. The configuration file is used by the Multicast Router to establish the network server connection, while other applications utilize it to connect to the Multicast Router. To disable the Multicast Router, simply change the connection.enable.tcpip flag to false.

[ ↑ Back to top ↑ ]

---

Connection Initialization

Typically, applications make use of the configuration file during setup by passing the file path when initializing the services. In the following code snippet, the application initializes and establishes a connection with the Multicast Router by specifying ./config/myapp-router.init as the path to the application-specific configuration file:

#include "areg/appbase/Application.hpp"

int main()
{
    // Initialize services, providing the path to establish a connection with mcrouter
    Application::initApplication(true, true, true, true, true, nullptr, "./config/myapp-router.init");
    
    // ... your code goes here

    // Release resources
    Application::releaseApplication();
    return 0;
}

By calling Application::initApplication() and providing the appropriate parameters, the application initializes and configures the necessary services. In this case, the last parameter, ./config/myapp-router.init, specifies the path to the configuration file, enabling the establishment of a connection with the Multicast Router. Once the initialization is complete, you can proceed with your application-specific code. Finally, releasing the application resources is done by calling Application::releaseApplication().

[ ↑ Back to top ↑ ]

---