com.adventnet.nms.util
Interface RunProcessInterface

All Known Subinterfaces:

HotStandbyListener

All Known Implementing Classes:

Collector, DBUserStorageServer, EventMgr, NmsConfigurationServer, RunExeModule, TopoNotificationRegistry

public interface RunProcessInterface

This interface provides methods that allow various Web NMS modules and user applications to be run as separate processes in the Web NMS BE or FE server. The Web NMS server starts each process as a separate thread during the startup.

The applications which are to be run as separate Web NMS processes should implement this interface, and the NMS server uses the various methods in this interface to control the processes. The callMain method of this interface is the entry point for the corresponding NMS process, and that method is invoked from a separate thread for each process, when the Web NMS server starts. The applications can provide their own initialization and startup in the callMain method. The isInitialized method is used to check whether the corresponding process is started successfully and is ready to provide service to other modules/applications. The shutDown method is invoked for each process when the NMS server is shut down, where the processes can handle the shutdown operation.

Users should note that the call to the callMain of the process is made by the NMS server from a separate thread, meant exclusively for that process. Thus, the class implementing this interface neither needs to extend the Thread class nor implement the Runnable interface. Users can start their own threads from callMain and also it is not necessary that callMain should return.

To be started as a separate process by the Web NMS in the BE or FE server, the application has to be specified in the NmsProcessBE.conf or NmsProcessFE.conf, repectively. During startup, the NMS BE and FE servers start all the processes specified in the conf file. Arguments can also be specified in the file, which will be passed to the process when it is started. The processes will be started in the order they are specified in the conf file.

In the conf file, any line starting with a "#" (hash) will be treated as a comment line and will be ignored. The fully qualified class name of the implementation of the RunProcessInterface of the corresponding process should be metioned in a separate line against the keyword PROCESS. The arguments that need to be passed to the process should all be specified in a single line against the keyword ARGS, and anything that is specified will be passed as a String array to the process when callMain is called. Each space separated token in the ARGS entry will be a separate element in the String array.

The following is a typical entry in the NmsProcess[BE/FE].conf file,

 
 PROCESS        com.adventnet.nms.topodb.DBServer
 ARGS           TOPO_OBJECTS_IN_MEMORY 50 LOCK_TIMEOUT 2 
 

With the above entry in the conf file, the NMS server will invoke the callMain method of the com.adventnet.nms.topodb.DBServer class, with the argument (String array) as {"TOPO_OBJECTS_IN_MEMORY", "50", "LOCK_TIMEOUT", "2"}. That is, if "args" is the String array, then args[0] will have "TOPO_OBJECTS_IN_MEMORY", args[1] will have "50" and so on.

Users should take care that the class name specified in the conf file is in the CLASSPATH of the NMS server, otherwise the process will not be started. Also, any PROCESS entry must be followed only by the corresponding ARGS entry in the conf file, otherwise the process will not be started. If there are no arguments to be passed to the process, then an entry like ARGS NULL should be specified in the conf file.

The NMS server startup procedure succeeds only when all the processes specified in the NmsProcesses conf file are started, and this is checked by the server by invoking the isInitialized method of each process. Thus, it is mandatory that the processes do their initialization and make sure that their isInitialized method returns true, when they are ready to service requests from other processes/clients.

The following code snippet explains how the methods of this interface are to be used,

 

        public class NmsProcess implements RunProcessInterface
        {
                private boolean initialized = false;

                private void init (String[] args)
                {
                        // do process specific initialization
                        ...
                        ...
                }
   
                private void proc ()
                {
                        // implement the process logic
                        ...
                        ...
                }

                public void callMain (String[] args)
                {
                        // This method is called by the NMS server during startup.

                        init (args);
                        initialized = true;     // This is very important       
                        proc ();        
                }

                public boolean isInitialized ()
                {
                        return initialized;
                }

                public void shutDown ()
                {
                        // handle shutdown for the process
                        ...
                        ...
                }

        }       // End of class NmsProcess
 
  

Method Summary

void	callMain(java.lang.String[] args) The method that is called by the NMS server to start a process that is specified in the NmsProcesses[BE/FE].conf file.
boolean	isInitialized() The method that is used to check whether the NMS process has started and is ready to service requests from other processes/clients.
void	shutDown() The method that is called for the NMS process, when the Web NMS server is shutdown.

Method Detail

callMain

void callMain(java.lang.String[] args)

The method that is called by the NMS server to start a process that is specified in the NmsProcesses[BE/FE].conf file. The RunProcessInterface implementation class, whose fully qualified class name specified against the PROCESS keyword in the conf file, will be instantiated and it's callMain method will be called. Note that if the implementation class has any constructor, it should also provide a no-argument constructor, otherwise the instantiation by the NMS server will fail.

For each process specified in the conf file, the NMS server invokes it's callMain from a separate thread, meant exclusively for that process. Thus, the class implementing this interface neither needs to extend the Thread class nor implement the Runnable interface. Users can start their own threads from callMain and also it is not necessary that callMain should return.

The arguments specified for the process against the ARGS keyword in the conf file, is passed as a String array through the argument of this method. Each space separated token in the args entry will be a separate element in the String array.

Note that the callMain for the processes will be called in the order (top to bottom) they are specified in the NmsProcesses[BE/FE].conf file.

Parameters:

args - String array, containing the arguments for the process as specified in the NmsProcesses[BE/FE].conf file. Each space separated token in the arguments will be a separate element in the String array. For ex., for an entry like "ARGS TOPO_OBJECTS_IN_MEMORY 50 LOCK_TIMEOUT 2" in the conf file, the String array passed to the callMain would be {"TOPO_OBJECTS_IN_MEMORY", "50", "LOCK_TIMEOUT", "2"}.

isInitialized

boolean isInitialized()

The method that is used to check whether the NMS process has started and is ready to service requests from other processes/clients. The NMS server invokes the callMain method for all the processes specified in the NmsProcesses[BE/FE].conf file and keeps checking the isInitialized method of each process. The NMS startup procedure succeeds only when the isInitialized method of all the processes return true, and only then allows the clients to be connected to it.

The time taken for the NMS to startup is also dependent on the processes returning true from this method. The implementation must make sure that this method returns true as soon as all the important initialization related to that process is completed.

Returns:

true if the process has done all it's initialization and started successfully, ready to service requests from other processes and clients.

shutDown

void shutDown()

The method that is called for the NMS process, when the Web NMS server is shutdown. The implementation can handle the process specific shutdown operation in this method. All the resources used by the process must all be cleaned up in this method.

Note that this method has to return for the NMS server to shutdown, unlike the callMain method. Also, this method will be called in random order for the different processes specified in the conf file, and hence the implementation should not make any assumption about the order in which shutDown is invoked.