The Lotus Expeditor Client gives you an extensive network management framework that can be used to make applications network aware. It gives applications access to the network status of the client platform as well as its connectivity to remote resources; it also notifies an implementing application of a change in network state. The Lotus Expeditor network framework is also extensible and provides two extension points that applications can use to provide custom detecting and handling of network faults.

This article explains the network capabilities of Lotus Expeditor Client and walks you through a step-by-step example of how to make your application network aware.

Prerequisites

You need a strong understanding of Java as well as Eclipse plug-in development. You should also understand the basics of Lotus Expeditor and have installed Lotus Expeditor Toolkit. More information on these topics can be found in the "Resources" section of this article.

Back to top

Understanding the network-aware capabilities of Lotus Expeditor

Lotus Expeditor’s network awareness layer provides a base framework for handling network errors platform-wide. It consists of the components shown in table 1.

The network awareness capability provided by Lotus Expeditor is twofold. It not only manages the connectivity of the local network adapter, but also provides a mechanism to manage the connectivity of registered remote resources.

Lotus Expeditor’s net status component monitors the network connectivity of the client machine’s network adapter. If a network cable is unplugged or if the network adapter is unable to connect to the network, an error is sent to the net faults component. This component then notifies the registered applications so they can take appropriate action before encountering the network error. In addition, the Lotus Expeditor net status service continues to monitor the adapter’s network connectivity and to notify registered applications once connectivity is regained.

Lotus Expeditor also allows applications to register a remote server. If any application using that server encounters a network error when attempting to contact it, the application notifies the net faults component. This component then informs all applications that are registered with that server so that they can take appropriate action before encountering the error themselves. Although the default Lotus Expeditor implementation does not provide a mechanism for detecting when a server is back online, the net faults component can be extended to provide a monitor to detect the availability of a remote resource.

Lotus Expeditor’s network awareness framework is based on the concept of early detection and notification. Any application wishing to make use of network awareness must register with the framework. The network awareness framework detects only local network errors. It does not automatically detect remote network errors, but instead relies on the first application encountering an error to announce it. (We explain more about this later.) Once informed of a network fault, the network awareness framework categorizes it and notifies all other listeners before other applications encounter the same error. This warning allows applications to handle the fault before it occurs, eliminating user interruptions.

Lotus Expeditor also provides an Online/Offline widget displayed in the bottom right corner of the Lotus Expeditor Client as shown in figure 1. A user can request a client disconnection by toggling this button from Online to Offline. This type of planned disconnection allows applications to wrap up their network activity and prepare for disconnection. In this scenario, the network layer notifies all network listeners that a request has been issued to go offline. Each application can then take the appropriate steps to prepare for disconnection. Applications are also given the opportunity to cancel the request to go offline. This is usually done by prompting the user that a network task is underway and giving the user the option to cancel the task and continue going offline or to cancel the offline request completely.

Lotus Notes V8.0 is built on top of the Lotus Expeditor platform and is one example of an application that benefits from Lotus Expeditor’s network awareness. It uses the framework in its replication function, to detect connectivity losses to mail servers and to fail over to backup servers. Lotus Expeditor’s Synchronization Manager also takes advantage of the planned disconnection scenario to prompt the user to synchronize before going offline.

Back to top

A sample application

We created a simple application that demonstrates in more detail the capabilities of Lotus Expeditor’s network awareness. Our application retrieves the current times of IBM sites around the world from a remote server. By enabling network awareness in our application, it can differentiate between network failures and determine the proper behavior.

Download the sample application from the "Download section of this article, and follow the instructions in README.txt to set up the sample and to import the project into your Eclipse workspace. The sample application is called com.ibm.rcp.time.client and contains eight classes as listed in table 2.

The classes in package com.ibm.rcp.time.client.netaware are described in more detail as we go through the steps to enable network awareness.

Back to top

Readying the application for client network awareness

We begin by enabling awareness for total connectivity losses by the client. This includes planned disconnection as well as abrupt disconnection from the local network.

The first step in registering the application with the network component of Lotus Expeditor is to implement the com.ibm.rcp.offline.api.service.INetworkAware interface found in the com.ibm.rcp.offline plug-in. Once registered, this subclass receives notifications of network state transitions sent by the Lotus Expeditor network component.

For this example, we focus on the implementation of four methods: disconnected(), reconnected(), goOffline(), and goOnline(). Details of the other methods in this class can be found in the Reference section of the Lotus Expeditor Information Center.

The disconnected() method is called when the network-aware component detects that the client has gone offline abruptly as opposed to a planned disconnection. Conversely, the reconnected() method is called when the network-aware component detects that the client has regained connectivity to the network. The goOffline() method is called after a planned disconnection has been approved by all registered components. Similarly, the goOnline() method is called upon approval of planned reconnection. The application does not require any preparation for a planned disconnection or reconnection, so the goOffline() method simply calls the disconnected() method, and the goOnline() method calls the reconnected() method.

The application retrieves the current time at various IBM sites around the world from a remote server. By leveraging Lotus Expeditor’s network awareness, the application is notified [through the disconnected() method] if network connectivity is lost. At this time, the application can decide instead to calculate the times locally based on the system clock. But how does the application know when connectivity returns? The Lotus Expeditor network component contains a system connectivity monitor that constantly monitors the state of the network adapter and notifies registered components of any state changes. This eliminates the need for the application to monitor the local network or to deal with network errors. It simply waits for the notification that network connectivity has been regained [through the reconnected() method], before again retrieving the times remotely.

Ignoring the methods that we are not implementing at this time, the INetworkAware class looks like the code shown in listing 1.

public class NetworkConnectivityListener implements IConnectionStates, INetworkAware {
	
	/**
	 * Called by the offline service when network is no longer available.
	 */
	public void disconnected() {
		//set network state to disconnected
		TimeBean._networkState = STATE_DISCONNECTED_NETWORK;
	}
	
	/**
	 * Called by the offline service when network is available again.
	 */
	public void reconnected() {
		//set network state to connected
		TimeBean._networkState = STATE_CONNECTED;
	}

	/**
	 * Called by the offline service when it is disconnecting from the 
   network.
	 */
	public void goOffline() {
		disconnected();
	}

	/**
	 * Called by the offline service when it is reconnecting to the 
   network.
	 */
	public void goOnline() {
		reconnected();
	}

	...
}

The disconnected() method implemented here changes the state in TimeBean.java to STATE_DISCONNECTED_NETWORK. By reading this flag, the time client knows that it is no longer connected to the network and chooses to calculate the site times from the system clock. Similarly, the reconnected() method changes the state to STATE_CONNECTED letting the client know it is again connected to the network and can retrieve times from the server.

Now that you have implemented the listener for network events, you need to register it with Lotus Expeditor’s offline helper to begin receiving notifications of the client’s connectivity. To do this, add an instance of the offline service helper and an initialization method to the class you created previously as shown in listing 2.

IOfflineServiceHelper myHelper = null; 

	/**
	 * Initializes the connectivity listener by registering with the 
   offline service.
	 * 
	 * @return an instance of this class.
	 */
	public INetworkAware init() {
		//create offline service helper
		myHelper = IOfflineServiceHelperFactory.INSTANCE.create(this);
		return this;
	}

Then, when the application starts up, you simply need to instantiate an instance of the listening class:

INetworkAware networkListener = new NetworkAwareImpl().init();

You do this in the start() method of com.ibm.rcp.time.client.Activator.java. In addition to registering, you also need to close the service created by the listening class when the application stops. This can be done in the stop() method of com.ibm.rcp.time.client.Activator.java as follows:

networkListener.getOfflineServiceHelper().closeOfflineService();

Back to top

Running and testing the application

Before you add further functionality to the application, let’s give it a try. To run the application from the toolkit, open the MANIFEST.MF file found in the META-INF folder of the project. On the Overview tab, click the "Launch Client Services Application" link in the Testing section as shown in figure 2.

This launches the application in the Lotus Expeditor Client. Enter your Lotus Expeditor Client password and choose Open - IBM Time Client. A view appears that shows the current times of IBM sites around the world. These times are currently being retrieved remotely.

Next, use the Online/Offline toggle button to change the state of the client to Offline. Click the Refresh button. Notice that the IBM site times have been updated even though you have lost your connection to the Internet. Behind the scenes the application was notified by the Lotus Expeditor network framework of the loss in connectivity. At this time, the disconnected() method that you implemented previously made the time client aware of the change in network state, and the client chose instead to calculate the displayed times from the system clock.

After network connectivity is regained, the listener is notified, and the time client again retrieves times from the Web server. You can simulate this by toggling the Online/Offline button to Online.

Back to top

Adding awareness for remote resource connectivity

You can take greater advantage of Lotus Expeditor’s network framework by narrowing your interest in connectivity to the remote server from which the application retrieves its times. For the purposes of this example, we say that the times retrieved from the server are more accurate and therefore, more desirable. If the primary server is unavailable, but the client still has network connectivity, you want to fail over to a secondary server as opposed to using system time. You can do this by implementing another connectivity listener and associating it with a server context.

The following implementation of the server connectivity listener is slightly different from the listener you just created for local network awareness. In this listener, you are no longer interested in the goOffline() and goOnline() methods. These methods are called by the network framework when the client is completely disconnected from the network in a planned disconnection. Because we already handle this situation in the previous listener implementation, we do not need to handle it here.

In addition, when registering a listener for a remote resource, the network framework requires that you pass along a server context, that is, a string value that represents the server in which you are interested. This also requires a modification to the init() method to accept a String context. Therefore, the implementation for the server listener is as shown in listing 3.

public class ServerConnectivityListener implements INetworkAware, IConnectionStates {

	IOfflineServiceHelper myHelper = null; 

	/**
	 * Initializes the connectivity listener by registering with the 
	 *  offline service.
	 * @param context The server in which the listener is interested.
	 * @return an instance of this class.
	 */
	public INetworkAware init(String context) {
		//create offline service helper
		myHelper = IOfflineServiceHelperFactory.INSTANCE.create(this, 
context);
		return this;
	}
	
	/**
	 * Called by the offline service when the context with which the 
	 *  listener is registered is no longer available.
	 */
	public void disconnected() {
		//set network state to disconnected
		TimeBean._networkState = STATE_DISCONNECTED_PRIMARY_SERVER;
	}
	
	/**
	 * Called by the offline service when the context with which the 
     * listener is registered is available.
	 */
	public void reconnected() {
		//set network state to connected
		TimeBean._networkState = STATE_CONNECTED;
	}

	/**
	 * Returns the offline service helper.
	 */
	public IOfflineServiceHelper getOfflineServiceHelper() {
		return myHelper;
	}

	...
}

You also register this listener in the start() method of com.ibm.rcp.time.client.Activator.java.

serverListener = new
ServerConnectivityListener().init(TimeBean.PRIMARY_SERVER);

Let’s not forget to close the offline service helper created by this listener in the stop() method of com.ibm.rcp.time.client.Activator.java.

serverListener.getOfflineServiceHelper().closeOfflineService();

Now, when it is detected that the server is unavailable, the disconnected() method is called by Lotus Expeditor’s network-aware component. In the disconnected() method, you set the network state flag for the time client informing it to switch to the secondary server.

You still face a problem, though. The network-awareness support in Lotus Expeditor does not actively monitor remote resources for connectivity. How does the framework know when the server is unavailable or when it becomes available again after connectivity is lost? The answer is simple: You have to tell it. You can do so through a public API provided by the network-awareness framework.

Back to top

Extending the handler extension point to create a connectivity monitor

The network faults framework provides developers with an API that categorizes network exceptions passed to it by an application. It then passes the fault to all extensions to the com.ibm.rcp.net.faults.handler extension point through the handle() method. Each handler can examine the fault, decide if it is of interest, and if so, perform the appropriate behavior. In this scenario, you want to have a handler that detects a connection fault related to the primary server context and that triggers an Eclipse Job to monitor the availability of the remote resource. First, however, you must notify the framework if you lose connectivity to the primary server.

The com.ibm.rcp.time.client.TimeBean.java class is responsible for connecting to the server and for retrieving the time through the getTimeFromServer() method. This method attempts to open a stream on a URL object pointing to the remote server. If an exception occurs during this connection attempt, you need to pass it along to the network framework through the DetectAndHandle.detectAndHandle() method. The detectAndHandle() method takes two parameters: the exception that was thrown and the context in which it was thrown. In this case, the context is the server. This is the method that is responsible for categorizing the exception it is given and passing it along to handler extensions. The call to detectAndHandle() shown next is placed in the catch block of the getTimeFromServer() method in TimeBean.java.

DetectAndHandle.detectAndHandle(new ConnectException(e.getMessage()), server);

With this in place, the network framework is notified when the primary server is unavailable. It then calls the disconnected() method in the server connectivity listener you registered with the server context. The application then knows to switch to the secondary server.

By extending the handler extension point you can detect the fault that was categorized as a result of the ConnectException, and you can start an Eclipse Job to monitor the availability of the remote server without having to tie up the application’s main thread.

The first step in creating a handler is to implement the com.ibm.rcp.net.faults.Handler interface as shown in listing 4. This interface contains one method called handle() that accepts an array of Fault objects. The com.ibm.rcp.net.faults plug-in provided by Lotus Expeditor contains a number of Fault objects used to describe various network errors. You are interested only in a ConnectFault because it describes the ConnectException seen by the application when the primary server is unavailable. Each Fault object contains an object named context. You know that the context object you passed to the network framework in the detectAndHandle() method was a String representation of the primary server. Therefore, in your handle() implementation (shown in listing 4), you want to iterate through the array of Fault objects and look for a ConnectFault with a String context that is equal to the primary server. Once you find this, you know that the primary server is unavailable and that you should begin to monitor for connectivity. Note that the handle() method in every extension to the com.ibm.rcp.net.faults.handler extension point is called every time any type of network fault is detected. For this reason, it is necessary to ensure that you start the connectivity monitor only when the proper fault occurs.

//called by the network component when a fault is detected
public void handle(Fault[] faults) {
	
	for (int i = 0; i < faults.length; i++) {
		Fault f = faults[i];
		Object context = f.getContext();
	if (context != null && f instanceof ConnectFault &&
     f.getContext().toString().equals(TimeBean.PRIMARY_SERVER)) {
		     //start monitor
		     reconnect(context);
		     break;
		}
	}
}

When you create a monitor for a remote resource, it is good practice to extend the Eclipse Job framework. This allows the monitor to run in its own thread and prevents it from tying up the application’s main resources. Learn more about the Eclipse Job framework.

The last step required to complete the implementation of the primary server monitor is to notify the Lotus Expeditor network framework when connectivity to the remote server is restored. The network awareness framework then notifies all listeners registered with that server context, including the listener that you have registered, by calling the reconnected() method. The reconnected() method that you have implemented changes the network state of the time client to STATE_CONNECTED so that the time client knows that it can again retrieve the time from the primary server.

To register your handler extension with the Eclipse framework, you must add the following to the plugin.xml file of the project, where handlerClass is the name of the implementing class and id is a unique ID for this handler. See listing 5.

<extension point="com.ibm.rcp.net.faults.handler">
    <handler     
    handlerClass="com.ibm.rcp.time.client.netaware.ServerConnectivityMonitor"
    id="com.ibm.rcp.time.client.handler.1"/>
</extension>

You can view the complete implementation of the server connectivity monitor in com.ibm.rcp.time.client.netaware.ServerConnectivityMonitor.java.

Back to top

Creating your own network-aware application

Now that we have shown you how to modify an existing application to be network aware, you can easily create your own network-aware application. The Lotus Expeditor Toolkit that accompanies the Lotus Expeditor Client makes it easy to create the framework for a network-aware application. The toolkit helps you create an empty project with the necessary network-awareness dependencies ready to be deployed in the Lotus Expeditor environment.

Follow these steps to create a network-aware application.

1. In Eclipse, choose File - New - Project.
2. Expand the Client Services node, and then select Client Services Project.
3. Click Next.
4. Enter a project name, and then click Next.
5. On the next panel shown in figure 3, specify the package and name of the Activator class for the plug-in you are creating. Enter the following in these fields:
   • Plug-in ID: MyNetAwareApplication
   • Plug-in Version: 1.0.0
   • Plug-in Name: MyNetAwareApplication Plug-in
   • Activator: com.im.developerworks.netaware.Activator
   Be sure that you have selected the "Generate an activator, a Java class that controls the plug-in's life cycle" option under Plug-in Options and both the "Search for dependences automatically upon resource changes" and "Attempt to automatically resolve Manifest dependencies" options under Auto-Management Preference.

6. Click Next.
7. Scroll through the Target Features and select Network Layer as shown in figure 4.

8. Click Finish.

Your application appears in the Eclipse Package Explorer and is equipped with the necessary Lotus Expeditor dependencies for network awareness.

Back to top

Conclusion

This article guided you through the details of the network awareness framework of the Lotus Expeditor Client. It also described how to modify an existing application to take advantage of these capabilities for both local and remote network resources. We encourage you to download and install the sample and to use it as a guide to enable network awareness in your own Lotus Expeditor application.

Back to top

Download

Information about download methods

Resources

Learn

• Read the developerWorks Lotus article, "End-to-end integration with pervasive messaging and IBM Lotus Expeditor micro broker."
  
  
• Read the developerWorks Lotus article, "Building an offline application in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Developing and deploying rich client applications on desktops and mobile devices using IBM Lotus Expeditor V6.1."
  
  
• Read the developerWorks Lotus article, "Migrating Eclipse RCP applications to IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Creating collaborative components for IBM Lotus Expeditor Property Broker."
  
  
• Read the developerWorks Lotus article, "Developing an OSGi service as a Web service in IBM Lotus Expeditor."
  
  
• Read the developerWorks Lotus article, "Building and deploying a simple Web Services Resource in IBM Lotus Expeditor."
  
  
• Read the IBM Redbooks publication, Building Composite Applications in Lotus Expeditor V6.1.
  
  
• Read the developerWorks Lotus Expeditor page.
  
  
• Refer to the IBM Lotus Expeditor Information Center.
  
  
• See the Eclipse Web site for more information on the Eclipse development environment or to download the IDE.
  
  
• Learn about the Eclipse Job framework.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Prerequisites
• Understanding the network-aware capabilities of Lotus Expeditor
• A sample application
• Readying the application for client network awareness
• Running and testing the application
• Adding awareness for remote resource connectivity
• Extending the handler extension point to create a connectivity monitor
• Creating your own network-aware application
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Expeditor toolkit
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Expeditor toolkit

My developerWorks community

Dig deeper into Lotus on developerWorks

Lotusphere knows the secret to a successful collaboration event: You.

Lotusphere 2010. Register now! January 17-21, 2010 in Orlando, FL

Special offers