Genesys Platform SDK 7.6 Documentation

Connecting to a Server

The applications you write with the Platform SDK will need to communicate with one or more Genesys servers. So the first thing you need to do is create a connection with these servers. Genesys recommends that you use the Protocol Manager Application Block to do this. Protocol Manager is designed for high-performance communication with Genesys servers. It also includes built-in support for warm standby.

Once you have connected to a server, you will be sending and receiving messages to and from this server. The next article shows how to use the Message Broker Application Block for efficient event handling.

Note: Protocol Manager may not support all of the servers you need to use in your application. For information about how to update Protocol Manager to communicate with these servers, see the Protocol Manager Application Block Guide.

To use the Protocol Manager Application Block, add the following file to your classpath:

This jar file was precompiled using the default Application Block code, and can be located at: <Platform SDK Folder>\applicationblocks\protocolmanager\dist\lib.

Note: You can also view or modify the Protocol Manager Application Block source code. To do this, open the Protocol Manager Java source files that were installed with the Platform SDK. The Java source files for this project are located at: <Platform SDK Folder>\applicationblocks\protocolmanager\src\java. If you make any changes to the project, you will have to run Ant (or use the build.bat file for this Application Block) to rebuild the jar archive listed above. After you run Ant, add the resulting jar to your classpath.

Now you can add import statements to your source code. For example:

[Java]

import com.genesyslab.platform.applicationblocks.commons.protocols.*;
import com.genesyslab.platform.applicationblocks.warmstandby.*;

In order to use the Protocol Manager, you need to create a ProtocolManagementServiceImpl object. This object manages all of your server connections. Declare it with your other fields:

[Java]

ProtocolManagementServiceImpl protocolManagementServiceImpl;

Then you can initialize the service object inside the appropriate method body:

[Java]

protocolManagementServiceImpl =
	new ProtocolManagementServiceImpl();

You are now ready to create an object that will be used to specify how to communicate with the server. For example, if you are working with Configuration Server, you will set up a ConfServerConfiguration object:

[Java]

ConfServerConfiguration confServerConfiguration =
	new ConfServerConfiguration("Config_Server_App");

Note that you have to provide a string when you create the ConfServerConfiguration object. This string should be unique for each protocol used in your application. It might be a good idea to use the name of the server's application object from the configuration layer, which guarantees uniqueness as well as clearly identifying which server you are communicating with.

After setting up the ConfServerConfiguration object, you need to specify the URI of the Configuration Server you want to communicate with, as well as a few other necessary pieces of information:

[Java]

try {
	confServerConfiguration.setUri(
		new URI("tcp://" + confServerHost + ":" + confServerPort));
} catch (URISyntaxException e) {
	e.printStackTrace();
}
confServerConfiguration.setClientApplicationType(CfgAppType.CFGSCE);
confServerConfiguration.setClientName(clientName);
confServerConfiguration.setUserName(userName);
confServerConfiguration.setUserPassword(password);

At this point, you can register your ConfServerConfiguration object with Protocol Manager:

[Java]

protocolManagementServiceImpl.register(confServerConfiguration);

Now you can tell Protocol Manager to open the connection to your server:

[Java]

try {
	protocolManagementServiceImpl.getProtocol("Config_Server_App").open();
} catch (ProtocolException e) {
	e.printStackTrace();
} catch (IllegalStateException e) {
	e.printStackTrace();
} catch (InterruptedException e) {
	e.printStackTrace();
}

You may want to set up a connection to more than one server. To do that, you could repeat the steps outlined above. Here is an example of how you might do that in order to add a connection to Stat Server:

[Java]

StatServerConfiguration statServerConfiguration = new StatServerConfiguration(
		"Stat_Server_App");
try {
	statServerConfiguration.setUri(new URI(statServerUri));
} catch (URISyntaxException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}
protocolManagementServiceImpl.register(statServerConfiguration);
.
.
.
// Add this line to the try block for the Configuration Server open()
protocolManagementServiceImpl.getProtocol("Stat_Server_App").open();

In some cases, you may want to use the beginOpen() method instead of using the open() method. beginOpen() will open all of your connections with a single method call. However, unlike open(), beginOpen() is asynchronous. This means you will need to make sure you have received the onChannelOpened event before you send any messages. Otherwise, you might be trying to use a connection that does not yet exist.

In order to use beginOpen(), you need to implement the ChannelListener interface:

[Java]

import com.genesyslab.platform.commons.protocol.ChannelListener;
.
.
.
public class YourApplication
	implements ChannelListener, ...

You will also need to add a channel listener after you register your ServerConfiguration objects:

[Java]

protocolManagementServiceImpl.register(confServerConfiguration);
protocolManagementServiceImpl.register(statServerConfiguration);
.
.
.
protocolManagementServiceImpl.addChannelListener(this);

Now you can add a method to handle the OnChannelOpened event:

[Java]

public void onChannelOpened(EventObject event) {
	if ( event.getSource() instanceof ClientChannel )	{
		ClientChannel channel = (ClientChannel)event.getSource();

		if ( channel instanceof ConfServerProtocol ) {
			// Work with Configuration Server messages...
		}
		else if ( channel instanceof StatServerProtocol ) {
			// Work with Stat Server messages...
		}
	}
}

Having done that, you can remove these lines from the try block:

[Java]

protocolManagementServiceImpl.getProtocol("Config_Server_App").open();
protocolManagementServiceImpl.getProtocol("Stat_Server_App").open();

And replace them with this one:

[Java]

protocolManagementServiceImpl.beginOpen();

However, if you want to issue an asynchronous open for a specific protocol, you can invoke beginOpen for that protocol, like this:

[Java]

protocolManagementServiceImpl.getProtocol("Config_Server_App").beginOpen();
protocolManagementServiceImpl.getProtocol("Stat_Server_App").beginOpen();

Note: When using the beginOpen() method, make sure that your code waits for the onChannelOpened event to fire before attempting to send or receive messages.

Once you have opened your connection, you can send and receive messages, as shown in the article on Event Handling. But before getting to that, please note that when you have finished communicating with your servers, you should close the connection, like this:

[Java]

protocolManagementServiceImpl.beginClose();

Or like this:

[Java]

protocolManagementServiceImpl.getProtocol("Config_Server_App")
	.close();
protocolManagementServiceImpl.getProtocol("Stat_Server_App")
	.close();

Or like this:

[Java]

protocolManagementServiceImpl.getProtocol("Config_Server_App")
		.beginClose();
protocolManagementServiceImpl.getProtocol("Stat_Server_App")
		.beginClose();

This introduction has only covered the most basic features of the Protocol Manager Application Block. Consult the Protocol Manager Application Block Guide for more information on how to use Protocol Manager, including the following topics:

To learn how to send and receive messages, go to the article on Event Handling.

Top of Page

Additional Information

For more information about the Genesys SDKs, including the latest versions of all SDK documents, check out the Genesys Developer Zone, which also contains forums and other important sources of developer-related information. DevZone is available at http://www.genesyslab.com/developer.

Genesys DevZone

Additional information on Genesys Telecommunications Laboratories, Inc. is available on our Technical Support website. The following documentation also contains information about this software. Please consult the Deployment Guide first.

Top of Page


Send comments on this topic to Techpubs.webadmin@genesyslab.com