Java applications can communicate with EMG using the Java implementation of the MGP protocol. JAR files are freely available for download from the download section.

Within this document you will find code examples for using the Java API. The Javadoc for the API can be found in the documentation section.

Background

The Java API uses the MGP protocol and therefore an incoming MGP connector needs to be defined in server.cfg for access via the Java API to be possible. In the examples below we use the default MGP connector configuration included in the EMG distribution.

Sending a message (Send.java)

import com.nmt.mgp.Mgp;
import com.nmt.mgp.MgpException;
import com.nmt.mgp.MgpOption;
import com.nmt.mgp.MgpSession;
import com.nmt.mgp.OptionHolder;
import com.nmt.util.StringUtils;

public class Send
{
public static void main(String[] args)
throws MgpException
{
// MGP connector information on server
String host = "localhost";
int port = 7185;
String username = "emguser";
String password = "secret";
String route = "smsc";
String destaddr = "4612345";
String message = "Hello world";

// Connect to server, non-SSL connection
MgpSession session = new MgpSession(host, port, false);
// Authenticate
session.login(username, password);

OptionHolder oh = new OptionHolder();

// Put together options for send operation
oh.add(new MgpOption(Mgp.MGP_OPTION_ROUTE, route));
oh.add(new MgpOption(Mgp.MGP_OPTION_DESTADDR, destaddr));
oh.add(new MgpOption(Mgp.MGP_OPTION_MESSAGE,
StringUtils.encodeHex(message)));

// Send operation and receive result
oh = session.execute(Mgp.MGP_OP_SENDMESSAGE, oh);

int ret = oh.getOption(Mgp.MGP_OPTION_RETCODE).getIntValue();

int id;

if(ret == Mgp.MGP_ERR_OK)
id = oh.getOption(Mgp.MGP_OPTION_ID).getIntValue();
else
id = -ret;

// Print id or error code (negative value indicates error)
System.out.println("id = " + id);

// Logout and close connection
session.close();
}
}

Compiling the example when Send.java and jar files are located in current directory

javac -classpath .:mgp-16a.jar:util-19.jar Send.java

Running example

java -classpath .:mgp-16a.jar:util-19.jar Send

Receiving messages (Receive.java)

import com.nmt.mgp.Mgp;
import com.nmt.mgp.MgpException;
import com.nmt.mgp.MgpOption;
import com.nmt.mgp.MgpSession;
import com.nmt.mgp.OptionHolder;
import com.nmt.util.StringUtils;

public class Receive
{
public static void main(String[] args)
throws MgpException
{
// MGP connector information on server
String host = "localhost";
int port = 7185;
String username = "emguser";
String password = "secret";

// Connect to server, non-SSL connection
MgpSession session = new MgpSession(host, port, false);
// Authenticate
session.login(username, password);

// Send operation and receive message (if any) in result
OptionHolder msgoh = session.execute(Mgp.MGP_OP_GETFIRSTMESSAGE, null);

// Was operation ok?
int ret = msgoh.getOption(Mgp.MGP_OPTION_RETCODE).getIntValue();

if(ret == Mgp.MGP_ERR_OK) {
// Did we get a message?
if(msgoh.getOption(Mgp.MGP_OPTION_ID) != null) {
int id = msgoh.getOption(Mgp.MGP_OPTION_ID).getIntValue();
OptionHolder oh = new OptionHolder();
oh.add(new MgpOption(Mgp.MGP_OPTION_ID, id));
oh.add(new MgpOption(Mgp.MGP_OPTION_RETCODE, Mgp.MGP_ERR_OK));
// Confirm message received ok
oh = session.execute(Mgp.MGP_OP_CONFIRMMESSAGE, oh);
String msg = msgoh.getOption(Mgp.MGP_OPTION_MESSAGE).getValue();
msg = StringUtils.decodeHex(msg);
// Print id and message
System.out.println("id = " + id);
System.out.println("message = " + msg);
} else {
System.out.println("No message received");
}
} else {
// Print error code (negative value indicates error)
System.out.println("An error has occured, err = " + msgoh.getOption(Mgp.MGP_OPTION_ID).getIntValue());
}

// Logout and close connection
session.close();
}
}

Benchmarking

The following code example (SmsBench.java) can be used to benchmarking sending of messages using Java. When running the code example on a Xeon 2.4 GHz server with Linux we reach throughput levels around 1900 mps.

import com.nmt.mgp.Mgp;
import com.nmt.mgp.MgpException;
import com.nmt.mgp.MgpOption;
import com.nmt.mgp.MgpSession;
import com.nmt.mgp.OptionHolder;
import com.nmt.util.StringUtils;

public class SmsBench
{
public static void main(String[] args)
throws MgpException
{
// MGP connector information on server
String host = "localhost";
int port = 7185;
String username = "emguser";
String password = "secret";
String route = "smsc";
String destaddr = "4612345";
String message = "Hello world";
// Number of messages to send
int nmessages = 30000;

// Connect to server, non-SSL connection
MgpSession session = new MgpSession(host, port, false);
// Authenticate
session.login(username, password);

long start = System.currentTimeMillis();

for(int i=0; i<nmessages; i++) {
OptionHolder oh = new OptionHolder();

// Put together options for send operation
oh.add(new MgpOption(Mgp.MGP_OPTION_ROUTE, route));
oh.add(new MgpOption(Mgp.MGP_OPTION_SOURCEADDR, sourceaddr));
oh.add(new MgpOption(Mgp.MGP_OPTION_DESTADDR, destaddr));
oh.add(new MgpOption(Mgp.MGP_OPTION_MESSAGE,
StringUtils.encodeHex(message)));

// Send operation and receive result
oh = session.execute(Mgp.MGP_OP_SENDMESSAGE, oh);

int ret = oh.getOption(Mgp.MGP_OPTION_RETCODE).getIntValue();

int id;

if(ret != Mgp.MGP_ERR_OK)
break;

id = oh.getOption(Mgp.MGP_OPTION_ID).getIntValue();
}

if(ret == Mgp.MGP_ERR_OK) {
long end = System.currentTimeMillis();
long runtime = end-start;
double mps = 0;

if (runtime > 0) {
mps = (1000 * nmessages / runtime);
}

System.out.println("Runtime: " + runtime + " ms");
System.out.println("That gives " + mps + " mps");
} else {
System.out.println("An error occurred, error code=" + ret);
}

// Logout and close connection
session.close();
}
}

Best practice

It is considered best practice to keep the session when performing multiple operations. That is, multiple session.execute operations can be performed without corresponding login and close operations. Creating a new session will impose overhead and impact performance severely.