This article describes the development of a port checker application called Healthcheck. The application was created to address certain environmental conditions at a customer site and was then combined with the functionality of IBM Lotus Sametime versions 7.x and later. Although the application was useful for debugging specific problems, its true power was realized when it was transformed into a Lotus Sametime bot. The combination of Healthcheck with Lotus Sametime created a 24 X 7 server monitoring tool that can instantly notify one or more system administrators of an outage. This pure Javaâ„¢ application is designed to run on any platform supporting Software Development Kit (SDK) 1.4.2.

The article includes discussions of the following:

• The reasoning for the initial application
• Code samples of the original application
• Realizing the power of Lotus Sametime instant messaging (IM) to make this application real time
• How this application is useful
• New application code showing how Lotus Sametime was incorporated

Environment and problem scope

Healthcheck was originally designed as a diagnostic tool that could be used to determine whether an application is responding on a particular port. Network administrators are quite familiar with the ping utility as a means to determine whether a particular host is available. If a user is having trouble with an application, one of the troubleshooting steps is to ping the host to determine if the client has an unobstructed path to the host running the application.

Healthcheck goes a step further, enabling you to ping a particular port on which your application is listening. Healthcheck can be used for a one-time query to troubleshoot a connectivity problem, or it can be used to monitor an application continually. The real genius of Healthcheck is its ability to take input from a text file. By knowing the ports that are in use by your business applications, you can leverage Healthcheck as a monitoring tool for a variety of servers and as an ad hoc troubleshooting tool for connectivity issues.

The environment for which Healthcheck was developed included a variety of Lotus-based servers in the infrastructure, including IBM Lotus Domino® Mail, Application, LDAP, and SMTP servers; Lotus Sametime Instant Messaging, Meeting, Multiplexer (MUX), and SIP servers; as well as IBM Lotus QuickPlace® servers.

Back to top

Basic design and prerequisites of the Healthcheck application

The initial design of the Healthcheck application focused on providing an easy way for customers to use an input file, populating it with all their desired resources that needed to be monitored, and providing either a one-time report on the availability or a continuous query highlighting the resources that were not network available.

Prerequisites

One of the most basic requirements of Healthcheck was to make it as lightweight and portable as possible. This meant three things:

• Ability to run the application on anything from a small desktop to a large server. The ability to open and close sockets to remote hosts/servers is mostly a network operation and does not require any large amount of processing on the image running the application.
• Minimal software installed on client. The only software prerequisite for Healthcheck is to have the Java Runtime Environment (JRE) 1.4.2 installed and found within the path. Also, no product plug-ins of any kind are required, regardless of the type of host, application, or server. The idea was to keep the Healthcheck limited to a network socket check to eliminate any need for a product component to be installed to match the type of server or host being monitored.
• Ability to run on any platform. Written in Java, Healthcheck is platform agnostic and can run almost anywhere. Java's JRE 1.4.2 provides native support for many platforms, including Microsoft Windows, UNIX, Linuxâ„¢, and host-based systems, eliminating the need for platform-specific software components on the monitoring host.

Healthcheck is a versatile tool that can be placed anywhere in the network and that can monitor countless network-available applications and resources, all from one location.

Back to top

Displaying server status

Before Healthcheck incorporated the power of Lotus Sametime, there was only one method to notify the user of the status of the requested query. For the one-time Healthcheck invocation, a window would display the list of socket connections for every host or port requested. If a connection could not be made, the host or port was displayed along with the resultant error code from the socket open call.

Listings 1 and 2 show how to populate the local Display Window using a JPanel Java object and how to control the pop-up window with the host/port failures, respectively.

void PrintWindow()
{
// Does a local pop-up window if -service not specified on input of all errors found
	try {
		DisplayWindow dw=new DisplayWindow(outputfile,Errors,error_index);
		dw.setLocationRelativeTo(null);
		dw.setVisible(true);
	}
	catch (Exception e)
	{Printnow("exception from DisplayWindow");}

}

import java.awt.*;
import javax.swing.*;
import java.util.Calendar;

public class DisplayWindow extends JFrame {
    //============================================== instance variables
   JTextArea _resultArea = new JTextArea(20, 80);
        
    //====================================================== constructor
    public DisplayWindow(String logname, String Errors[], int error_index) {

	
	Calendar c = Calendar.getInstance();
	
        //... Set textarea's initial text, scrolling, and border.
	_resultArea.append("Log file: " + logname + ".log\n\n");
	for (int i = 0;i<error_index;i++)
	{
	_resultArea.append(Errors[i]+"\n");
	}
        //_resultArea.setText("Enter more text to see scrollbars");
        JScrollPane scrollingArea = new JScrollPane(_resultArea);
        
        //... Get the content pane, set layout, add to center
        JPanel content = new JPanel();
        content.setLayout(new BorderLayout());
        content.add(scrollingArea, BorderLayout.CENTER);
        
        //... Set window characteristics.
        this.setContentPane(content);
	String ampm;
	if (c.get(Calendar.AM_PM) == 1)
		ampm=new String("PM");
	else
		ampm=new String("AM");

        this.setTitle("Port Checker is Reporting Errors @ "+ c.get(Calendar.MONTH)+"/"+
        c.get(Calendar.DAY_OF_MONTH)+"/"+c.get(Calendar.YEAR)+" "+ 
        c.get(Calendar.HOUR_OF_DAY)+":"+c.get(Calendar.MINUTE) );
        this.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
        this.pack();
	

    }
 }

Figure 1 shows the resultant error display.

Back to top

Running Healthcheck as a Microsoft Windows service or AIX daemon

To make Heathcheck more proactive, a service option was added to enable the application to run without a user being logged in locally to the monitoring host. The service option also enables Healthcheck to automatically restart, should the monitoring box need to be restarted for maintenance or patches, for example.

The Microsoft® Windows® service enablement and AIX® daemon support were achieved by use of the Java Service Wrapper open source project developed by Tanuki Software. This open source tool provides the wrappers that allow Healthcheck to be controlled by the Microsoft Windows Services or AIX Daemon commands.

Back to top

Input specifications

To provide an input file and to make it easy to group resources into categories, the format of the properties file was designed without the requirement to repeatedly specify the same ports for every host that is listed. Port settings, located under the [Ports] section of the input file, provides a location to designate ports for specific server categories: [Domino], [Sametime], [MUX], [SIP], [QuickPlace]. This location allows Healthcheck to spin through each type and the use the port list to check each desired port.

For ad hoc input or for servers that have unique ports that don't fit easily into a category, the generic [Hosts] category can be used to designate individual hosts and ports together. Figure 2 shows a sample input file.

Back to top

Implementation of the port monitoring function

As previously mentioned, one of the design goals of Healthcheck was to make the code platform and application independent and to provide feedback on why the host/port combination is not available. This was done by use of the Java socket class java.net.socket. Listing 3 shows the sample code used to monitor each host or port and to track the exceptions.

void CheckSametime() {
int Ports[]=new int[100];
int token_count=1;

String port_ini_setting=FindPortInfo(SAMETIME_PORTS);

if (port_ini_setting.equals(""))
	{
Ports[0]=1352;
Ports[1]=80;
Ports[2]=1533;
Ports[3]=8081;
Ports[4]=8082;
token_count=5;
	}
else
	{
			                            
StringTokenizer st = new StringTokenizer(port_ini_setting,",");
		
        while (st.hasMoreTokens())
        {
	try {
		Ports[token_count-1]=Integer.parseInt(st.nextToken()); 
		// catch a NumberFormatException
		token_count++;
	}
	catch (Exception port)
	{
		Printnow("Port value is not a valid #");
	}
			
}
	} // end of if

for (int index=0;Sametime[index]!=null;index++)
	{
	Printnow("\nServer: " + Sametime[index]);

	
 	
	for (int ports_to_check=0; ports_to_check < token_count-1; ports_to_check++)
	{
 	try
 	{
 	  Socket con = new Socket(Sametime[index],Ports[ports_to_check]);
	if (con !=null)
	{
	Printnow("Connection was successful for server: " + Sametime[index] + " Port: "
		+ Ports[ports_to_check] );
		con.close();
	}
 	}
 	catch (UnknownHostException unoe)
	{
	//Printnow("CONNECTION FAILURE: server:Unknown host " + Quickplace[index] +
	" Port: " + Ports[ports_to_check] + "     );
	Printnow("CONNECTION FAILURE: server: " + Sametime[index] + " Port: " 
	+ Ports[ports_to_check] + "......Unknownhost Exception : " + unoe.getMessage() );
	}
	catch (IOException ioe)
	{
	//Printnow("CONNECTION FAILURE: server:IOException " + Quickplace[index]
	+ " Port: " + Ports[ports_to_check] );
	Printnow("CONNECTION FAILURE: server: " + Sametime[index] + " Port: "
	+ Ports[ports_to_check] + "......IOException : " + ioe.getMessage() );
	}
 	catch(SecurityException sece)
		 {
   			
		Printnow("CONNECTION FAILURE: server: " + Sametime[index] + " Port: " 
		+ Ports[ports_to_check] + "......Security Exception : " 
		+ sece.getMessage() );
		//Printnow("exception  " + ioe.getMessage());

	 	}
 
   }
	//token_count=1;
   }
}

If the socket connection is created and opened by creating a new Socket object, then the test is considered successful, and the socket is immediately closed. If, however, the new Socket object fails to be instantiated, then an exception is thrown and caught by the application. In the case of the Socket class, there are three types of exceptions thrown on a failure to create a Socket object, as shown in table 1.

Powering Healthcheck with Lotus Sametime: The power of real-time communication

The initial results and testing of Healthcheck were encouraging. Monitoring strategic points in the network, this tool let us log and monitor network and application outages. We achieved our goal of creating a simple application to easily and quickly identify network outages, application failures, firewall issues, and DNS trouble. It seemed this application had matured to its logical point. Or was it just getting started?

What about using Lotus Sametime to make Healthcheck pro-active rather than reactive? Up until now, Healthcheck had been run by one operator to monitor the network, with the results of trouble delivered only to the invoker of the tool. This approach worked well for debugging issues and for environments in which a user was always around to see the console, but to be mature, the application had to do more.

Lotus Sametime notification was chosen over other popular methods for notification (email, paging, and so on) because of its speed and flexibility. Email is not an immediate form of communication because it can take minutes to deliver a failure notification depending on the messaging infrastructure. Paging is immediate but requires the administrator to perform an action to know what is down and why it is down. Lotus Sametime enabled Healthcheck to provide instant notification, to one or more users with specific information regarding the trouble found, so that immediate action can be taken.

Back to top

Adding Lotus Sametime notification to Healthcheck

Using the Lotus Sametime 7.5.1 Software Development Kit, we easily transformed Healthcheck into a Lotus Sametime bot. To use Lotus Sametime notifications, we specified a Lotus Sametime user ID and password to be used by Healthcheck when a notification is to be sent. Healthcheck uses this information to log in to Lotus Sametime and send the notification to one or more users, as specified in the input file.

To ensure that Lotus Sametime notifications still occur in the event of a Lotus Sametime outage, it is best if your Lotus Sametime environment is redundant; it's a good idea to use the Lotus Sametime Chat clustering capabilities along with a load balancer for automatic failover.

The Lotus Sametime notification process is a five-step procedure:

1. Creating and logging in to a Lotus Sametime session. When our Notification object was started, first it had to create a Lotus Sametime session by instantiating a new STSession object. This STSession object is the root of all the Lotus Sametime functionality and must be created before any log-in can be attempted. Listing 4 illustrates the run method of the thread that connects to the Lotus Sametime server and issues the alerts.

   
   
   Listing 4. Healthcheck run method (showing STSession creation)
   

   public void run() { try { if (debug) healthchecker.Printnow("Notification thread is now starting"); // if stsession already exists, then unload and re-do if (stsession != null) {stsession.stop(); stsession.unloadSession(); } stsession = new STSession("AlertSession"); stsession.loadSemanticComponents(); stsession.start(); //Console message if we are debugging sysOut("Session created"); //Log into the st sametime server now stLogin(st_server, st_user, st_pw); while (healthchecker.iscomplete()==false) {sleep(2000);} healthchecker.Printnow("Notification thread is now complete"); } catch (DuplicateObjectException doe) { try { //doe.printStackTrace(); // if dup, then unload and re-do just in case if (stsession != null) {stsession.stop(); stsession.unloadSession(); } stsession = new STSession("AlertSession"); stsession.loadSemanticComponents(); stsession.start(); //Console message if we are debugging sysOut("Session created"); stLogin(st_server, st_user, st_pw); } catch (DuplicateObjectException doe1) { //After unloading and trying again, just fail sysOut("DuplicateObjectException thrown again"); healthchecker.setcomplete(); //destroy(); } } catch (Exception e) { System.out.println("We failed getting the sametime session"); } }

   
   

   The stLogin method called from this routine drives the user log-in for the bot. Listing 5 shows the simple log-in routine.

   
   
   Listing 5. Simple log-in routine
   

   public void stLogin(String server, String user, String password) // Login routine to ST server. { commService = (CommunityService) stsession.getCompApi(CommunityService.COMP_NAME); commService.addLoginListener(this); commService.loginByPassword(server, user, password); sysOut("Attempting login to " + server); }

   
   
2. Providing action after log-in is successful. After successfully completing the commService.loginByPassword() method, the application must provide a loggedIn() method that is called by the listener object. This method is passed the Administrator name to notify. It is important in this class to create an InstantMessagingService object and make Healthcheck a listener for such activity, ensuring that our object is what gets called when an Instant Message is created.
   
   

   At the end of this method, once the Services have been created, the Resolver service is called to look up the name of the user to be notified. Listing 6 is the application code that is driven after the successful log-in to Lotus Sametime. Services must be started, and we attempt to resolve the user to which the alert must be sent.

   
   
   Listing 6. Code showing Services starting and Resolver
   

   public void loggedIn(LoginEvent le) // Called after successful login // method will issue resolve of user to notify { sysOut("Logged In"); //Attempt to set our status try { STUserStatus status = new STUserStatus (STUserStatus.ST_USER_STATUS_DND, 0, STATUSMSG); le.getLogin().changeMyStatus(status); } catch (Exception exc) { sysOut("Exception caught - " + exc.getMessage()); } sysOut("Register to listen for incoming messages"); //Register to listen for incoming messages //We aren't concerned about failures so no need for a try/catch imService = (InstantMessagingService) stsession.getCompApi(InstantMessagingService.COMP_NAME); imService.registerImType(ImTypes.IM_TYPE_CHAT); imService.addImServiceListener(this); sysOut("Get a handle to the Lookup Service and add a resolve listener"); //Get a handle to the Lookup Service and add a resolve listener lookupService = (LookupService) stsession.getCompApi(LookupService.COMP_NAME); resolver = lookupService.createResolver(true, false, true, false); resolver.addResolveListener(this); // The way healthcheck class uses this class, only one name is supplied at once // May want to change in future to resolve all at once. String [] copy = new String[name_count]; sysOut("Name count is: " + name_count); for ( int idx = 0; idx < name_count; idx++ ) { sysOut("copy complete; copied name: " + users_to_notify[idx]); copy[idx] = users_to_notify[idx]; } sysOut("doing the resolve, length is " + copy.length); for (int i=0;i<copy.length;i++) { sysOut("names are " + copy[i]); } resolver.resolve(copy); }

   
   
3. Creating and sending IM session. Now that the resolver.resolve() method has been invoked, it is up to Healthcheck to provide a resolved() method, which is called by a successful call to the resolve() API. In our case, once the name of the System Administrator has been found in the Lotus Sametime directory, we are ready to create the Lotus Sametime IM object and send the actual list of application or server outages.
   
   

   Listing 7 shows the code that is driven by a successful resolution of the target user for the IM; once resolved, the actual IM can be sent.

   
   
   Listing 7. Example code showing creating InstantMessagingService and opening the IM session
   

   public void resolved(ResolveEvent re) { /* if (re.getResolved() instanceof STUser) { STUser user = ((STUser) re.getResolved()); String userName = user.getName(); sysOut("Resolved " + userName); watchList.addItem(user); sysOut("Added " + userName + " to WatchList"); */ sysOut("We resolved the name"); if (re.getResolved() instanceof STUser) { // User was resolved. Now get the IM service STUser partner = ((STUser) re.getResolved()); imService= (InstantMessagingService) stsession.getCompApi(InstantMessagingService.COMP_NAME); String userName = partner.getName(); sysOut("Resolved " + userName); //Set the IM Type to IM_TYPE_CHAT int imt = ImTypes.IM_TYPE_CHAT; //Set the encryption level EncLevel enc = EncLevel.ENC_LEVEL_ALL; //Create the IM so we can send the message Im im = imService.createIm(partner, enc, imt); im.addImListener(this); // open will call imOpened in this class im.open(); } }

   
   

   Notice that, at the end of the resolved() method, we actually create the Im object of type IM_TYPE_CHAT. This object drives the application to have a defined ImOpened() object, which is then used to send the actual message. In our case, the message sent is the list of hosts or ports that did not successfully allow a socket to be opened to it.

   Once the Im.open() method is invoked, the listener is then driven through the ImOpened() provided by Healthcheck. It is this routine that actually sends the message to the notification list and closes the session as well. Listing 8 shows the ImOpened method, which the listener task invokes after a successful call to Im.open().

   
   
   Listing 8. ImOpened method showing actual sending of text message to Administrator
   

   public void imOpened(ImEvent ie) // method does the actual send of the IM once the IM was successfully opened { sysOut("IM Opened to " + ie.getIm().getPartner().getName()); //To get the user status we need to cast the Im Object as an STWatchedUser // if open, we are ready to send the IM if (ie.getIm().isOpen()) { // Create message from all the failure reported in healthcheck class String text="HeathCheck reporting problems on the following ports:\n"; for (int loop=0;loop<error_index;loop++) { text=text.concat(Errors[loop] + "\n"); } //send the IM ie.getIm().sendText(false, text+"\n"); im_sent++; healthchecker.Printnow("Message sent to " + ie.getIm().getPartner().getName()); try { Thread.sleep(2000); } catch (InterruptedException e) { } // close the IM and start to tear everything down. ie.getIm().close(STError.ST_OK); healthchecker.setcomplete(); } }

   
   

   When the message is sent successfully with the sendText method, the close() method is called on the Im object, followed by the destroy() method object to begin the logout process and teardown of the STSession itself. Failure to do this results in a DuplicateSession Exception the next time a new Session is attempted for the next notification.

4. Closing the instant message. Once the close() method is called on the ImEvent object, it drives the imClosed method to remove the listener that was handling the instant message channel. Listing 9 illustrates the simple imClosed routine.
   
   
   
   Listing 9. Simple imClosed routine
   

   public void imClosed(ImEvent ie) { sysOut("IM Closed from " + ie.getIm().getPartner().getName()); //The channel is closed so we can remove the listener ie.getIm().removeImListener(this); }

   
   
5. Logging out of and destroying the Lotus Sametime session. After the session is closed, Healthcheck is logged out of Lotsu Sametime, and the STSession object created in the first step is destroyed. The teardown() method is used to issue the logout and to tear the session down. Listing 10 shows the teardown method and LoggedOut method.
   
   
   
   Listing 10. Teardown() method showing cleanup of Lotus Sametime bot
   

   public static void teardown() // destroy is called whenever we are unloading the session after IM is sent or if failure occurs { sysOut("Destroy called"); if (debug) healthchecker.Printnow("Notification thread is now complete"); if (commService != null && commService.isLoggedIn()) { try { commService.logout(); } catch (Exception exc) { sysOut("Could not logout: " + exc.toString()); } } try{ if (stsession != null) {stsession.stop(); stsession.unloadSession(); sysOut("Sametime Session unloaded"); } } catch (Exception exc1) { sysOut("Could not logout:Could not unload session object " + exc1.toString()); } }

   
   

Once the teardown is successful, the Lotus Sametime resources that were used to generate the notification are freed up. All that is left is to notify Healthcheck that the notification thread is complete and then continue with either the next notification or the next iteration of host monitoring. Figure 3 shows a Lotus Sametime notification from Healthcheck.

The Healthcheck output to the notification list includes:

• Time of outage
• Server or host name
• Port number
• Exception type (one of three thrown by Socket open call)
• Reason returned, in the Exception object text field

Healthcheck logs in and out of Lotus Sametime with each notification. If Healthcheck were logged into Lotus Sametime for the duration of the monitoring, we would need to build in reconnect logic to ensure that Healthcheck could fail over automatically in the event of a Lotus Sametime server outage. Although this approach is not the fastest delivery, it does enable Healthcheck to leverage a redundant Lotus Sametime environment for the delivery of notifications.

If you are using the newer Lotus Sametime Eclipse-based clients (versions 7.5 and later), you can also leverage automatic chat logging to keep a running record of outages. You can establish group chats from the notification window to include other administrators who may know what is wrong or how to resolve the issue. Healthcheck could also be customized to respond with additional information, although we did not include this capability.

Back to top

Conclusion

In this article, we demonstrated how to create a port checker application that can be combined with Lotus Sametime to provide instant notification of outages in your environment. The Lotus Sametime toolkits can be used in powerful ways to create customized applications that harness the power of Lotus Sametime. We hope this article sparks your imagination for new ways to use the power of Lotus Sametime in your own bots.

You can download this tool from developerWorks Lotus.

Resources

Learn

• Read the developerWorks® Lotus article, "A tour of the IBM Lotus Sametime V7.5 toolkits."
  
  
• Read the developerWorks Lotus article, " Creating a stock quote bot using the IBM Lotus Sametime Java toolkit."
  
  
• Read the developerWorks Lotus article, " Building a Lotus Sametime bot for language translation."
  
  
• Read the developerWorks Lotus article, " Building your own Sametime bots, Part 1."
  
  
• Read the developerWorks Lotus article, " Building your own Sametime bots, Part 2."
  
  
• Read the developerWorks developerWorks New to SOA and Web Services page.
  
  

Get products and technologies

• Download the Real time Port Monitoring Application.
  
  
• Download the Lotus Sametime SDK, which includes the Lotus Sametime Java toolkit from developerWorks Lotus.
  
  
• Register for the IBM Lotus Sametime 7.5.1 demonstration site.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Read the developerWorks Lotus Team blog.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Environment and problem scope
• Basic design and prerequisites of the Healthcheck application
• Displaying server status
• Running Healthcheck as a Microsoft Windows service or AIX daemon
• Input specifications
• Implementation of the port monitoring function
• Adding Lotus Sametime notification to Healthcheck
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Sametime
• Demo: Lotus Notes 8 composite applications
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Sametime

My developerWorks community

Dig deeper into Lotus on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers