Develop a Custom Java Client for WebSphere Everyplace Connection Manager

IBM® WebSphere® Everyplace® Connection Manager enables you to optimize and secure the connection between mobile clients and IT infrastructure. It also provides a toolkit that you can use to create a custom mobility client. This article describes how to use the Connection Manager Mobility Client toolkit to develop a custom JavaTM client.


Jerome Tarte, Technical Solution Architect, IBM

Jerome Tarte photoJerome Tarte is an IT Architect from e-Business Solutions Center at La Gaude, France. For the last five years, he has been involved in many J2EE and wireless projects. Today, as a member of the EMEA Client Technology Center (IBM Systems and Technology Group lab services), he provides service for leading edge IBM software and hardware for the IBM eServers, including Architecture Design, WebSphere, High Availability, and more.

06 October 2004

WebSphere Everyplace Connection Manager Overview

WebSphere Everyplace Connection Manager Version 5.0.x is a distributed, scalable, multipurpose communications platform that provides protection of sensitive data, optimization of network traffic, and enables seamless roaming across a wide range of network technologies (Wifi, Ethernet, GPRS, and more). The WebSphere Everyplace Connection Manager (hereafter called Connection Manager), supports secure data access from a wide choice of mobile devices, using standards-based protocols.

Connection Manager provides solutions that enable comprehensive enterprise access and deliver enterprise-level security from mobile devices like laptops, WAP phones, PDAs, Internet kiosks, and SMS devices. This main goal of this communications platform is to extend the corporate network and IT infrastructure for on demand solutions into the mobile workforce, enabling mobile workers to reach enterprise data and application everywhere and whenever they need it.

Figure 1. Connection Manager Overview
Figure 1. Connection Manager Overview

The Connection Manager Mobility Client provides a virtual IP interface used by the application to connect with the enterprise network. The Mobility Client provides a virtual IP stack to handle the communication and internally translates the packet to the real adapter used. On the server side, a similar behavior can be observed. In fact, the communication between the Mobility Client and the Connection Manager, isn't constituted by the IP packets generated by the business application (client-server application, mail application or other), but by IP packets that encapsulate the packets generated by applications. This method provides better security for the data and allows the Mobility Client to work with different network adapters and switch to the best one without impact for your applications. The application works with only one adapter, the virtual adapter provided by Connection Manager.

Figure 2. Mobility Client and Connection Manager Interaction
Figure 2. Mobility Client and Connection Manager Interaction

Connection Manager is composed of three parts:

  • The gateway, on the server side, manages the connections and enables the user to connect to the IT infrastructure.
  • The Connection Manager gatekeeper is an administrative console that can be used to configure the gateway behavior.
  • The Mobility Client is used to establish a connection and open a communication channel with the gateway on the client.

The Mobility Client enables you to do all the functions permitted by Connection Manager, including opening a connection, roaming between two or more networks, and so on. However, in some cases, the behavior of this standard client isn't adapted to your requirements or your needs. The IBM Mobility Client has been written to support many standard needs, but not necessarily yours. For example, if you're using cross-network roaming, you may want to extend the Mobility Client to be able to have knowledge of network connectivity events for a specific radio modem by developing a piece of code designed for that modem. Developing a component that retrieves modem-specific information and passes it to the Mobility Client, enables the Mobility Client to become aware when a given network is no longer available.

To assist users with creating their own Connection Manager client applications, Connection Manager provides a Mobility Client toolkit. The toolkit contains three variations of the Mobility Client API, providing support for different types of applications:

  • The C/C++ API is the basis for all of the client APIs.
  • The Visual Basic API encapsulates the C/C++ API within an ActiveX object that can be referenced by Visual Basic programs.
  • The Java API encapsulates the C/C++ API within a Java class

In this article, we'll focus on the Java API.

General considerations when developing a Connection Manager client

Two important terms have been borrowed from the IP sockets environment, and are used throughout this document:


An interface is a physical link between the Mobility Client and the Connection Manager. Once an interface has been opened to the Connection Manager, the Mobility Client must create a logical connection to the Connection Manager before IP data can be sent or received. Interfaces are established using the eOpenInterface function and ended using eCloseInterface.


A connection is a logical link between the Mobility Client and the Connection Manager established using eLogon and ended using eLogoff. This connection exists independent of any physical links over interfaces and allows the Mobility Client to switch physical networks while maintaining a logical connection.

The Mobility Client API is asynchronous in nature, since interactions with modems and adapters tend to be asynchronous activities (for example, send a command, wait for a response). Most API functions generate asynchronous events to report success or failure. Applications should always be capable of receiving and processing any API event. The return code of a method indicates that the call has been made and no error is detected when the method is executed. As the result of this call, in most cases, the program needs to handle the associated events and analyze the response embedded in it.

The Java API for a Connection Manager Client

To control the Mobility Client by a Java application, our program must use the eWirelessApi Java class, which acts as a wrapper for the C/C++ API. The Java classes provide the same API functions and events that are supported by the C/C++ API.

To use the Java API, we need two things:

  • The eWirelessAPI.jar file, which contains the Java API classes. This jar file must be included in the CLASSPATH of our application.
  • The artapij.dll. The Java API depends on a native DLL to interact with the C/C++ API, located in the artapi.dll provided by the Mobility Client installation. The artapij.dll file must be located in the directory of your application or in the Java library path (in the case of Windows®, the DLL must be located in the Windows path. The DLL is loaded dynamically by the Java API class.

Develop a Connection Manager client application

Now we're ready to begin developing a custom Java client for Connection Manager with the Mobility Client toolkit.

Step 1: Load the Connection Manager API and obtain an eWireless instance

The first thing to do is to create an instance of eWireless class, as showin in Listing 1.

Listing 1. Create an eWireless class
public class WECMClientProcess implements eWirelessAPIListener

	 * The eWirelessApi instance
	protected eWirelessAPI api = null;

	public WECMClientProcess()
		//get the log instance
		log = LogManager.getLog("");
		// initialize the wecm client
	 * Init the wecm client. This method opens the different interfaces
	 * in use and logon the user
	public void init()
		log.debug("initalisation WECM");
		api = new eWirelessAPI();

Step 2: Obtain a network interface

The interface represents the physical link between the Mobility Client and the gateway. There are two ways to obtain a network interface. The first method is to obtain an already active interface by calling either the eGetActiveInterface method, as shown in Listing 2, to get the active interface (the interface in use to communicate with the gateway) or the eGetAllActiveInterface method to retrieve all the initialized interfaces.

Listing 2. eGetActiveInterface method
eInterfaceHandle h = new eInterfaceHandle(-1);
		int rc = api.eGetActiveInterface(h);
		if ((rc == eWirelessAPI.eErrNoActiveInterface) || (h.getInterfaceHandle() == -1))

The second method is to create a network interface with the method eOpenInterface. This method takes three parameters, as shown in Listing 3. The first is the name of the interface as defined in the artour.ini file, the configuration file of the Mobility Client. The second allows you to override the destination defined in the configuration file with a new gateway address. The third defines the instance of the interface. The only parameter you can modify is the interface destination. However, if you change any parameters in an interface definition, you must also edit the artour.ini file and modify them there, or use the configuration interface provided with the Mobility Client.

Listing 3. eOpenInterface method and parameters
eInterfaceHandle handle = new eInterfaceHandle(-1);
		int rc = api.eOpenInterface(name, "", handle);
		if (rc == eWirelessAPI.eOK)

Step 3: Handle the event and message

Because the Mobility toolkit works asynchronously, most of the results of method calls aren't returned by the method, but as events. The application must be able to catch the events sent by the Mobility Client. To do this, it must define a component implementing the eWirelessApiListener interface. This component defines some of the methods called when a particular event is produced, or in response to call methods or unsolicited events for information on network status.

Listing 4. eWirelessApiListener interface
// register the listener

Step 4: Log on and log off user

To log a user onto the gateway and activate the connection, the program calls the method eLogon, shown in Listing 5. The first parameter is the name of the Connection Manager connection as defined in the artour.ini file. The other parameters identify the user by ID, password and organization unit.

Listing 5. eLogon method
int rc = api.eLogon(config.getSession(), config.getUserName(), config.getPassword(), "");

If this method returns with an eOk status, it doesn't mean that the user is logged, only that the request for authentication is sent without problems. The real result of the log-on operation can be found in the eMsg_Logon event. The program must catch this event and analyze the associated return code to determine whether the user is authenticated. If a problem occurs, the return code gives information about the problem.

To log a user off, the program must call the eLogoff method, as shown in Listing 6. The log-off can be considered successful when a logoff event has been caught with no error return code.

Listing 6. eLogoff method
int rc = api.eLogoff();

Step 5: Survey the Connection Manager status or execute some operations

After you have completed the initialization and logged on on the gateway, you can manipulate the connection to try some actions or just survey it, by catching the events emitted by the Mobility Client. In the first case, you must call a specific method to take the action, such as eSuspendInterface to suspend the usage of an interface. In both cases, the program must listen for the events.

Step 6: Close the program

When your program has finished its job, it must release the resource and close properly. First, it must deregister its listener using the api.removeWirelessAPIListener method, as shown in Listing 7. If your application manages the logon and logoff operations, be sure this operation occurs after the logoff event has been intercepted, otherwise you can't know if the logoff has succeeded.

Listing 7. api.removeWirelessAPIListener method,
// register the listener

The program can also call the eCloseApi method on the eWirelessAPI instance. This method closes the link between this application and the wireless client.

Step 7: Stop the Mobility Client

If your application will control Mobility Client interfaces, or will call logon or logoff operations, you might want to modify the UseDefaultAPIBehavior parameter in the Mobility Client configuration file, artour.ini. This parameter determines whether default rules are used to control the API.

The default value for the UseDefaultAPIBehavior parameter is 1. When this parameter is set to 1, the Mobility Client code uses the following rules to determine whether the Mobility Client should automatically shut down:

  • If the Mobility Client state changes from logged-on to logged-off, the Mobility Client automatically closes all open interfaces and shuts down. This change to a logged-off state can occur when a user right-clicks the antenna icon in the status area of the taskbar on the desktop, then clicks "Exit" on the pop-up menu, or because the Connection Manager sends a log-off command to the Mobility Client.
  • If the last active interface changes from active to closed, the Mobility Client shuts down. An interface might change from active to closed due to various errors detected at the interface driver level, or because the Mobility Client has processed an eCloseInterface API command.

If you want the Mobility Client core to continue running after an eMsg_Logoff event is received from a network driver or after the last active interface closes, set the UseDefaultAPIBehavior parameter to 0.

Sample code

This article contains some sample Java code that represents a Connection Manager connection survey application. This application is looking for active interfaces and listening to the different events emitted by the Mobility toolkit. Sample screens are shown below.

Figure 3. Sample Application Screen 1
Sample Application Screen 1
Figure 4. Sample Application Screen 2
Sample Application Screen 2


In this article, we've seen how we can develop an application that can interact with the IBM Mobility Client. The API provided by the Mobility toolkit enables you to easily develop an application that addresses any needs not covered by the standard IBM Mobility Client. For example, you can automate the launch of a Connection Manager connection embedded in a business application without user intervention.

However, in my opinion, the Java API does have one drawback: it provides only one listener interface for all the events managed by the API. With the same listener, your component handles the events from user actions (logon and logoff), network and hardware events (battery, modem status, and so on). Therefore, your listener needs to implement all the event processing. This problem can be ameliorated by defining a more specialized interface and developing a component that handles all the events, then dispatching it to a specialized listener that implements the new interface. In this way, you can work only with those events that interest you, such as user events.


Java sample  ( HTTP | FTP )6 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Develop a Custom Java Client for WebSphere Everyplace Connection Manager