AMPS Java Client QuickStart

Version 5.3

Publication Date Sep 27, 2024

Welcome to AMPS!

AMPS, the Advanced Message Processing System, is a reliable high-performance publish and subscribe engine designed for real-world messaging applications that demand the highest performance and lowest latency possible. AMPS solves the hardest problems for modern pub/sub and queuing applications in a way that maximizes performance and reliability without compromising ease of use.

What makes AMPS different?

AMPS is designed for extremely demanding, real-world messaging applications. This means that AMPS has:

  • Uncompromising focus on real-world needs
    • Hardware-level optimization for performance
    • Easy-to-use programming interface
    • Detailed monitoring and diagnostics
  • Complete solution for high-volume low-latency applications
    • Durability and transactional consistency
    • Both pub/sub and queuing delivery models
    • Replication for high availability
    • Persistent state-of-the-world database
    • Content filtering with SQL92 WHERE clause semantics
    • Topic views, projection and JOIN
    • Message replay and historical point-in-time query
    • Real-time computation and analysis using standard SQL semantics
    • Delta publish and subscribe for lightweight updates
    • Built-in handling for FIX, NVFIX, JSON, BSON, Google Protocol Buffer, MessagePack and XML messages

AMPS allows you to configure each server, topic, or view to use exactly the features that you need. This keeps AMPS programming and administration simple.

Get the Equipment

To get the most out of your evaluation, you will need:

  1. An installation of AMPS on a Linux host
  2. The AMPS Java Client Distribution (which this file is a part of). Visit crankuptheamps.com to download the latest client distribution and documents.

Turn It On

To install the Linux distribution of AMPS and start the evaluation server:

  1. Extract the Linux distribution of AMPS and the AMPS client.

  2. Make a config directory in the AMPS distribution directory, for example:

    $ mkdir ~/amps_dir/config
    
  3. Copy the sample.xml file from the samples directory into the config directory you just created, for example:

    $ cp sample.xml ~/amps_dir/config/sample.xml
    
  4. Change directories to the AMPS distribution directory and start AMPS with the sample config file. For example:

    $ cd ~/amps_dir/
    
    $ ./bin/ampServer ./config/sample.xml
    

Crank It Up!

In this section, we describe using the AMPS samples from the command line. You can also use Eclipse or another IDE if you prefer.

To get started with AMPS, create a simple subscriber and publisher:

  1. Open a command shell
  1. Navigate to the directory where you unzipped the AMPS Java Client
  2. Navigate to samples
  1. Update the connection strings to connect to AMPS

    FROM THE LINUX COMMAND LINE:

    1. From the samples directory, type the following command to replace the IP address:

      $sed -ri 's/127.0.0.1/ip address here/' *.java
      

    FROM THE WINDOWS COMMAND PROMPT:

    1. From the samples directory, type the following command to replace the IP address:

      powershell "gci | foreach-object { (Get-Content $_) –replace '127.0.0.1' , 'ip address here' | Set-Content $_ }"
      
  2. Build the samples. From the samples directory, type the following command to build the samples:

    $ ant build dist
    

    The build.xml file in the samples directory contains targets for building and running the samples. For example, to build the console subscriber example, the equivalent command line to directly use the Java compiler is:

    $ javac -d bin -sourcepath src -cp ./lib/amps_client.jar \
      ./src/com/crankuptheamps/examples/EX01AMPSConsoleSubscriber.java
    
  3. Run the sample subscriber

    1. From the samples directory, you can run the example by typing:

      $ ant runSub &
      

      This starts the program EX01AMPSConsoleSubscriber, with source located at src/com/crankuptheamps/examples/EX01AMPSConsoleSubscriber.java.

    1. The program connects to AMPS, subscribes to a topic, and waits for messages to arrive. When a message arrives, the program prints the message to the console.
  4. Run the sample publisher

    1. From the samples directory, run the publisher by typing:

      $ ant runPub &
      

    This starts the program EX02AMPSConsolePublisher, with source located at src/com/crankuptheamps/examples/EX02AMPSConsolePublisher.java.

    1. The program runs, and subscribers receive the Hello, World message. The publisher itself produces no output if it is successful.

Using a State-of-the-World Database

One of the most useful parts of AMPS is being able to keep track of the current value of a message, using the state of the world (SOW) database:

  1. Add messages to a state of the world database

    1. From the samples directory, run the publisher by typing:

      $ ant runPubSOW &
      

      This starts the program EX03AMPSSOWConsolePublisher, with source located at src/com/crankuptheamps/examples/EX03AMPSSOWConsolePublisher.java.

    2. The program runs. This program sends 100 messages to AMPS. In this case, the messages are sent on a topic, messages-sow, that maintains a state-of-the-world database. AMPS saves the most recent version of each unique message. Unique messages are identified by the messageNumber in the message. The program sends messages 0-99, then updates message 5.

  2. Query the state of the world

    1. From the samples directory, run the query example by typing:

      $ ant runSOWandSubscribe &
      

      This starts the program EX05AMPSSOWandSubscribeConsoleSubscriber, with source located at src/com/crankuptheamps/examples/EX05AMPSSOWandSubscribeConsoleSubscriber.java.

    2. The program runs. This program queries the state of the world for the messages-sow topic, filtered to messages with a messageNumber less than 10. The console output shows the results of the query. Notice that for message 5, the database shows the latest value – the current state of the world. Rather than ending, the program continues to run. AMPS will send the program any new messages that match the filter.

Go beyond

The sample directory contains a number of sample programs, including programs that show how to use a bookmark subscription to replay messages published to a transaction log, programs that demonstrate publishing to and consuming from AMPS queues, programs that work with composite messages, and more.

You call the tune

Now that you’ve seen the samples run, it’s time for you to play with the samples. Modify them. Step through them in a debugger to see how they work.

Faster. Louder. Better.

From here, the world of AMPS is yours to explore. The Evaluation Kit gives you a set of guides to help you understand how AMPS works and what you need to do to take advantage of AMPS in your applications.

The AMPS User Guide describes the features of AMPS in detail, with a focus on helping you understand the concepts behind AMPS. The AMPS C++ Developer Guide describes the C++ interface for AMPS.

You know what your application needs. We’ve provided some suggestions for simple programs that will help you get familiar with AMPS and help you understand how AMPS can help you.

Suggested learning projects:

  • Understanding the state of the world. Fill the SOW database with messages. Verify this using the amps_sow_dump tool, as you did for AMPSSOWPublisher. Update a few messages in the database. Verify the updates using the amps_sow_dump tool. Then write a program that uses SOW and delta subscriptions to get the same information.
  • Working with multiple AMPS instances. Create an application that forwards selected messages from one AMPS instance to another.
  • Working with views. Create a view in AMPS that does simple calculation on values within incoming messages. Create an application that uses a filtered subscription on the view to view messages where the calculated value is within a certain range. Modify the application to use an out-of-focus message to be notified when the calculated value is outside of that range.
  • Try a message queue. The sample configuration has a queue named sample-queue defined for the JSON message type. Try sending a few messages to the queue, then starting a few subscribers to receive and acknowledge the messages.
  • Make a remix. Add Enrichment to one of the Topic definitions in the state of the world and see how AMPS can enrich and annotate messages as they’re published to the server.

Keep It Going

Want to know more about how AMPS can help you build great applications? Still having trouble getting AMPS to play your tune? For help or questions, get in touch at http://support.crankuptheamps.com. And if AMPS ever overloads (produces a minidump), send the dump file to crash@crankuptheamps.com.