This document describes the API for managing the network configuration of an RM system

Overview

RM offers a convenient mechanism for managing connections to backend server hosts, residing in a private network.

From the control center it is possible to define new networks and network filters for them, add hosts to them and introduce host URLs for each network.

For more information about the basic principles of backend server host configuration, refer to Network Configuration Management.

Calling the APIs for Network Configuration

The networks in an RM system can be monitored through the Configurator Manager service (com.prosyst.mprm.admin.system.ConfiguratorManager) and be configured through the com.prosyst.mprm.admin.system.Configurator instance, obtained from the Configurator Manager.

When using the Configurator Manager service, you can get information only about networks stored persistently in the system.

The Configurator instance is designed for submitting changes into the system configuration. They are accumulated in the Configurator until applied altogether, which saves needless system restart and reinitialization. Note that before applying modifications you receive information about the networks currently stored in the Configurator, not about the ones from the persistent configuration.

Both configuration utilities can be accessed from either a backend OSGi framework or a Remote Access Client. For more information about the accessing the Configurator Manager and Configurator, refer to the System Configuration Management document.

Managing Networks

Networks are represented by the com.prosyst.mprm.admin.system.Network interface whose methods provide access to network filters and can be used to easily determine the network of a specified host.

The DEFAULT_NETWORK field represents the name of the default network, which is always present in RM and keeps the connection URLs of registered backend server hosts.

Getting the Networks in an RM System

To get networks defined in RM, use the getNetworks or getNetwork(String networkName) method of the SystemObserver interface, implemented in the Configurator Manager and Configurator. As a result, RM returns one or more Network instances representing the corresponding networks.

Adding and Removing Networks

The RM system allows adding new networks only in system configuration mode, which is handled by the Configurator. To add a new network, simply call the Configurator's addNetwork method passing the network name as argument.

Removing a network is again possible only in system configuration mode by calling the removeNetwork method of the Configurator.

Moving a Host to Another Network

You can directly move a host from one network by another by using the changeBackendServerNetwork method of Configurator. The method takes as arguments the host ID and the name of the new parent network.

Managing Network Filters

Network filters are represented as com.prosyst.mprm.admin.system.NetworkFilter instances.

Getting the Filters of a Network

To retrieve the filters of a network, invoke the getFilters method of the appropriate Network instance.

Adding and Removing Network Filters

To add a filter to a network, in system configuration mode call the addNetworkFilter method of the Configurator passing the filter's attributes as described in the "Network Configuration Management" document.

To remove a filter, again in system configuration mode use the removeNetworkFilter method of the Configurator.

Changing the Priority of a Filter

You can change the priority of a defined filter with the changeNetworkFilterPriority method of the Configurator.

Determining the Network of a Host

A host can determine the parent network of another host by using the filters of its own network. The IP address of the checked host is matched to the destination network of the filter by applying BITWISE AND to the IP address and the filter's net mask. If the result is equal to the filter's net address, then the host is considered to belong to the destination network.

Basically there are two ways to determine the network of a host in relation to the own network:

  • By calling the getNetwork method on the own Network instance, specifying the IP address of the target host.
  • By calling iteratively the match method of the filters defined in the own Network instance.

Managing Host Network URLs

Each host can own one or more URLs in different networks. There can be more than one URL for a single network. In addition, there can be different network URLs for each supported communication scheme - currently, RM supports the socket and ssl schemes.

Defining such a network URL is possible in system configuration mode with the setBackendServerNetworkURLs method of the Configurator.

Network Configuration Example

This simple example illustrates most of the defined management operations for the RM network configuration. The example represents an RPC-enabled service, which returns a host's network URL(s) within the caller network. This RPC service can be contacted from a Remote Access to RM or through the backend RM RPC Service.

Example RPC-Enabled Service (Server Side)

The example RPC-enabled service, introduced in this document, runs on the backend and consists of interface and implementation (see the following two listing). From the local system configuration the service takes the ID of the host on which it is running and uses it to retrieve the home network of this host. When the getLocalHostURLs service method is called by the RAC application, the RPC-enabled service retrieves the URL of the caller and determines its network according to its home network filters. Finally, the service gets the URL of the specified host for the caller network and returns it to the caller.

The interface of the RPC-accessible service:

/**
* Interface of the example RPC-enabled service.
*/
 
public interface MyRPCService {
public String[] getLocalHostURLs(String hostId);
 
}

The implementation of the RPC-enabled service:

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.framework.ServiceRegistration;
 
import com.prosyst.mprm.admin.system.BackendServerHost;
import com.prosyst.mprm.admin.system.ConfiguratorManager;
import com.prosyst.mprm.admin.system.Network;
import com.prosyst.mprm.backend.system.SystemConfigInfo;
import com.prosyst.mprm.net.connection.RequestContext;
import com.prosyst.util.io.Remote;
import com.prosyst.util.threadpool.ThreadContext;
 
public class MyRPCServiceImpl implements MyRPCService, Remote, BundleActivator {
 
private Network myNetwork;
private ServiceReference sysConfigRef = null;
private String sysConfigClazz = SystemConfigInfo.class.getName();
private SystemConfigInfo sysConfigInfo = null;
private String myHostId = null;
private ServiceRegistration sReg = null;
private ServiceReference configMngrRef = null;
private ConfiguratorManager configMngr = null;
 
public String[] getLocalHostURLs(String hostId) {
Thread ctx = Thread.currentThread();
if (ctx instanceof ThreadContext) {
RequestContext reqCtx = (RequestContext) ((ThreadContext) ctx).getRunnable();
String tmpUrl = reqCtx.getP2PConnection().getRemoteURL();
// Parsing the remote URL as it is provided in scheme://host:port form.
String url = parseUrl(tmpUrl);
String callerNetwork = myNetwork.getNetwork(url);
try {
BackendServerHost reqHost = configMngr.getBackendServerHost(hostId);
return reqHost.getNetURLs(callerNetwork);
} catch (Exception e) {
e.printStackTrace();
}
}
return null;
}
 
// A helper method for retrieving the host address from a URL.
private String parseUrl(String tmpUrl) {
int idx = tmpUrl.indexOf("://");
if (idx != -1) {
int idx1 = idx + 3;
return tmpUrl.substring(idx1, tmpUrl.lastIndexOf(":"));
}
return null;
}
 
// Method inherited from com.prosyst.io.Remote
public Class[] remoteInterfaces() {
return new Class[] { MyRPCService.class };
}
 
// Method inherited from org.osgi.framework.BundleActivator
public void start(BundleContext bc) throws Exception {
sysConfigRef = bc.getServiceReference(sysConfigClazz);
if (sysConfigRef != null) {
sysConfigInfo = (SystemConfigInfo) bc.getService(sysConfigRef);
if (sysConfigInfo != null) {
// Getting the ID of the local backend server host
myHostId = sysConfigInfo.getMyHostId();
}
}
 
configMngrRef = bc.getServiceReference(ConfiguratorManager.class.getName());
if (configMngrRef != null) {
configMngr = (ConfiguratorManager) bc.getService(configMngrRef);
if (configMngr != null) {
BackendServerHost myHost = configMngr.getBackendServerHost(myHostId);
// Getting the home network
myNetwork = configMngr.getNetwork(myHost.getNetwork());
}
}
// Registering the RPC-enabled service
sReg = bc.registerService(MyRPCService.class.getName(), this, null);
}
 
public void stop(BundleContext bc) throws Exception {
if (sysConfigRef != null) {
bc.ungetService(sysConfigRef);
}
if (configMngrRef != null) {
bc.ungetService(configMngrRef);
}
 
if (sReg != null) {
sReg.unregister();
}
}
}


Example Consumer of the RPC-Enabled Service


The consumer of the RPC-enabled service is a RAC-based application, which remotely invokes the getLocalHostURLs service method for all defined hosts in the system and prints the result.

RAC-based consumer of the example RPC-enabled service:

import java.util.Hashtable;
 
import test.mprm.rpc.MyRPCService;
 
import com.prosyst.mprm.admin.system.BackendServerHost;
import com.prosyst.mprm.admin.system.CommunicationException;
import com.prosyst.mprm.admin.system.ConfiguratorManager;
import com.prosyst.mprm.backend.rpc.RPCException;
import com.prosyst.mprm.backend.rpc.RemoteReference;
import com.prosyst.mprm.common.ManagementException;
import com.prosyst.mprm.rac.RemoteAccessClient;
 
public class RemoteCaller {
static RemoteAccessClient rac;
 
public static void main(String[] args) {
Hashtable credentials = new Hashtable();
credentials.put(RemoteAccessClient.USER_PASSWORD, "system");
 
Hashtable connProps = new Hashtable();
connProps.put(RemoteAccessClient.CONNECT_TO_CC, "true");
 
try {
rac = RemoteAccessClient.connect("socket://192.168.104.17:11449",
"system",
credentials,
connProps);
 
RemoteReference service = rac.getRemoteReference(MyRPCService.class.getName(), null);
// Getting the IDs of registered backend server hosts
String[] hostIds = getHostIds();
if (hostIds != null) {
for (int i = 0; i < hostIds.length; i++) {
// Retrieving the URLs of registered backend server hosts
String[] urls = (String[]) service.invoke("getLocalHostURLs",
new Class[] { String.class },
new String[] { hostIds[i] });
for (int j = 0; j < urls.length; j++) {
System.out.println(
"[RemoteCaller] URL of host " + hostIds[i] + " is " + urls[j]);
}
}
}
} catch (ManagementException e) {
e.printStackTrace();
} catch (RPCException e) {
e.printStackTrace();
}
}
 
// Gets the IDs of the backend server hosts currently defined in the system
private static String[] getHostIds() {
ConfiguratorManager configMngr;
String[] hostIds = null;
 
try {
configMngr =
(ConfiguratorManager) rac.getService(ConfiguratorManager.class.getName());
BackendServerHost[] hosts = configMngr.getBackendServerHosts();
hostIds = new String[hosts.length];
for (int i = 0; i < hosts.length; i++) {
hostIds[i] = hosts[i].getId();
}
} catch (ManagementException e) {
e.printStackTrace();
} catch (CommunicationException e) {
e.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
return hostIds;
}
}


References