Java Example

Java is generally used for larger, enterprise ready projects.

This example details sending a message in plain old Java with no required libraries. It includes a messageId which can be used by your code to identify conversational context (threading).

If you do not specify a messageId when using the API, the default will be applied and you will be unable to thread messages.

Plan of attack

This example can serve as library functions for your later project

It is not served up by a web server, it is just a piece of plain old Java that just needs a JDK installed to compile and run.

What we'll do therefore is:

  • Write the code
  • Compile the example
  • Run the example
  • Have a pat on the back - you've integrated the eTXT API with Java

Write the code

Open up a text editor and paste the code below:

import sun.misc.BASE64Encoder;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

/**
 * This example sends a single message via the eTXT API
 *
 * You must specify the messageId as an argument on execution e.g
 *
 * java SimpleReceive 115612
 *
 * You are free to reuse and distribute this code; it is free of copyright
 */

public class SimpleSend {
    private final static String username = "";
    private final static String password = "";

    public static void main(String[] args) throws IOException {
        if (args.length == 0){
            System.err.print("No messageId Supplied");
            System.exit(1);
        }

        int result = send(username, password, "xxxx", args[0], "hello, world. 2"); // Change xxxx to your phone number
        System.out.println("Result code: " + result);
    }

    /**
     * Send an sms message.
     *
     * @param user API user name
     * @param pass API password
     * @param to the number to send the message to
     * @param messageId the threading identifier you want to use
     * @param body the message
     * @throws IOException if the HTTP POST fails
     * @return the HTTP result code
     */

    public static int send(String user, String pass, String to, String messageId, String body) throws IOException {
        URL url = new URL("https://www.etxtservice.co.nz/api/3/sms/out");
        HttpURLConnection con = (HttpURLConnection) url.openConnection();
        try {
            con.setRequestMethod("POST");
            con.setRequestProperty("Authorization", encodeBasicAuth(user, pass));
            con.setDoOutput(true);

            StringBuffer form = new StringBuffer();
            form.append("to=");
            form.append(to);
            form.append("&messageId=").append(messageId);
            form.append("&body=");

            form.append (URLEncoder.encode(body, "UTF-8"));

            OutputStream out = con.getOutputStream();
            try {
                out.write(form.toString().getBytes("US-ASCII"));
            } finally {
                out.close();
            }
            return con.getResponseCode();
        } finally {
            con.disconnect();
        }
    }

    public static String encodeBasicAuth(String user, String pass) throws UnsupportedEncodingException {
        byte[] credentials = (user + ':' + pass).getBytes("US-ASCII");
        return "Basic " + new BASE64Encoder().encode(credentials);
    }

}
SimpleSend.java

Save the file as SimpleSend.java

The code has 3 methods.

  • The main method kicks off the sending and checks to see that you have specified the messageId on the command line.
  • The send method prepares an HTTP post response, connects to the API and transmits the payload
  • The encodeBasicAuth method Base64Encodes the authentication credentials as per the HTTP standard

Compile the code

Open up a terminal (Unix/Linux) or cmd.exe (Windows)

Run the following:

javac SimpleSend.java

This should produce SimpleSend.class in the current folder

Send a Message

In the same terminal as above type:

java SimpleSend <messageId>

A message should arrive on your handset.

Your should see a 204 result string the console:

Result code: 204

Hurray! You have successfully sent your first eTXT API Message using some Java. Now you can lift this code and use it in your software, either standalone or web. See the receiving messages tutorial to pickup the message.