In this chapter, we will learn more about the structure and features of the AMPS Java client library, and build our first Java program using AMPS.
About the Client Library
The AMPS client is packaged as a single JAR file, amps_client.jar. You can find amps_client.jar in the dist/lib directory of the AMPS Java client installation. Every Java application you build will need to reference this JAR file, and the JAR file must be deployed along with your application in order for your application to function properly.
Connecting to AMPS
Let's begin by writing a simple program that connects to an AMPS server and sends a single message to a topic:
In the example above, we show the entire program; but future examples will isolate one or more specific portions of the code. The next section describes how to build and run the application and explains the code in further detail.
Build and Run with a Java Command Line
To build this program, you can run the following javac command, substituting the path to the amps_client.jar with the path where you have installed the AMPS Java Client:
TestPublisher.class This will create the TestPublisher.class file. To run the class file and send your first message to AMPS, you can issue the following command:
If the message is published successfully, there is no output to the console. We will demonstrate how to create a subscriber to receive messages in ` <#java-subscriptions-chapter>`_.
Examining the Code
Let us now revisit the code we listed earlier.
/* The import statements add names into reference for convenience in typing later
* on in the code. These import the names from the AMPS namespaces:
* com.crankuptheamps.client.Client — contains the methods for interacting with AMPS
* com.crankuptheamps.client.exception.AMPSException — the package contains the
* exception classes thrown by AMPS when errors occur.
*/
import com.crankuptheamps.client.Client;
import com.crankuptheamps.client.exception.AMPSException;
public class TestPublisher
{
public static void main(String[] args) {
/* This line creates a new Client object. Client encapsulates a single
* connection to an AMPS server. Methods on Client allow for connecting,
* disconnecting, publishing, and subscribing to an AMPS server. The
* argument to the Client constructor, "TestPublisher-Client", is a name
* chosen by the client to identify itself to the server. Errors
* relating to this connection will be logged with reference to this
* name, and AMPS will use this name to help detect duplicate messages.
* AMPS enforces uniqueness for client names when a transaction log is
* configured, and it is good practice to always use unique client names.
*/
Client client = new Client("TestPublisher-Client");
// Here, we open a try block that concludes with catch (AMPSException aex).
try
{
/* This statement declares a connection to AMPS with the provided
* URI. The URI consists of the transport, the address, and the
* protocol to use for the AMPS connection. In this case, the
* transport is tcp, the address is 127.0.0.1:9007, and the protocol
* is amps. This connection will be used for JSON messages. Check
* with the person who manages the AMPS instance to get the connection
* string to use for your programs.
*/
client.connect("tcp://127.0.0.1:9007/amps/json");
/* The AMPS logon() command connects to AMPS and creates a named
* connection. If we had provided logon credentials in the URI, the
* command would pass those credentials to AMPS. Without credentials,
* the client logs on to AMPS anonymously. AMPS versions 5.0 and
* later require a logon() command in the default configuration.
*
* This version of logon uses the DefaultAuthenticator, which provides
* credentials from the URI, if any are present. To use a different
* authentication scheme, implement an Authenticator.
*/
client.logon();
client.publish("messages", "{ \"message\" : \"Hello, world!\" } ");
}
// All caught exceptions in AMPS derive from AMPSException.
catch (AMPSException aex)
{
System.err.println("TestListener caught exception.");
}
/* We close out the example with a finally block that closes the
* Client connection and releases all accompanying resources, making
* the connection eligible for garbage collection.
*/
finally
{
client.close();
}
}
}
About Authentication
When a client logs on to AMPS, the client sends AMPS a username and password. The username is derived from the URI, using the standard syntax for providing a username in a URI. For example, tcp://JohnDoe:@server:port/amps/messagetype to include the username JohnDoe in the request.
For a given username, the password is provided by an Authenticator. The AMPS client distribution includes a DefaultAuthenticator that simply returns the password, if any, provided in the URI. A logon() command that does not specify an Authenticator will use an instance of DefaultAuthenticator.
If your authentication system requires a different authentication token, you can implement an Authenticator that provides the appropriate token.
You are now able to develop and deploy an application in Java that publishes messages to AMPS. In the following chapters, you will learn how to subscribe to messages, use content filters, work with SOW caches and fine-tune messages that you send.
