[![Maven version][maven-img]][maven-url]

Example code for using the non-blocking client to send a message

NonBlockingClient.create("amqp://localhost", new NonBlockingClientAdapter() {
  public void onStarted(NonBlockingClient client, Void context) {
    SendOptions opts = SendOptions.builder().setQos(QOS.AT_LEAST_ONCE).build();
    client.send("/public", "Hello World!", null, opts, new CompletionListener<Void>() {
      public void onSuccess(NonBlockingClient client, Void context) {
        client.stop(null, null);
      }
      public void onError(NonBlockingClient client, Void context, Exception exception) {
        client.stop(null, null);
      }
    }, null);
  }
  public void onDrain(NonBlockingClient client, Void context) {}
}, null);

Example code for receiving messages published to the '/public' topic.

NonBlockingClient client = NonBlockingClient.create("amqp://localhost", null, null);
client.subscribe("/public", new DestinationAdapter() {
  public void onMessage(NonBlockingClient client, Void context, Delivery delivery) {
    switch (delivery.getType()) {
      case BYTES:
        BytesDelivery bd = (BytesDelivery)delivery;
        System.out.println(bd.getData());
        break;
      case STRING:
        StringDelivery sd = (StringDelivery)delivery;
        System.out.println(sd.getData());
        break;
    }
  }
}, null, null);

State machine that underpins the client:

The client depends on the following jar files (and has been built and tested using the indicated versions):

The client can be installed into a Maven repository and automatically resolve these dependencies. For example:

mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=mqlight-api-$version.jar
mvn dependency:get -Dartifact=com.ibm.mqlight.api:mqlight-api:$version

The client includes maven_install.sh (for Linux) and maven_install.cmd (for Windows) scripts to perform the above maven install step, and additionally installs the samples.

The client implements a number of its components in such a way as they can be replaced by alternative implementations.

The following table describes the various plug-points provided by the client. For more information about an individual plug-point, please consult the Javadoc for the relevant interface.

The client logs using the SLF4J interfaces. If it is used in a runtime where an implementation of SLF4J has already been started, then it will use this for logging. If it is used in a runtime where Logback is used to implement SLF4J and the LogManager has not been started then it will configure Logback itself. Currently this involves enabling WARN and above logging unless the MQLIGHT_JAVA_LOG environment variable is set in which case the level it specifies will be enabled using Logback's BasicConfigurator. There are also the following environment variables that can be set to control the logging behavior when MQLIGHT_JAVA_LOG has been set:

• MQLIGHT_JAVA_LOG_STREAM can be set to specify the log output. By default log output up to and including the debug level goes to stdout, and trace level goes to stderr. MQLIGHT_JAVA_LOG_STREAM can be set to a file path prefix to direct log output to log files named in the following format:

  • {file path prefix}%i.log - for log output up to and including the debug level.
  • {file path prefix}%i.trc - for log output of the trace level.

  where %i is blank for the current log file and an index number, starting at 1, for archive log files.

  A Logback RollingFileAppender with a FixedWindowRollingPolicy and SizeBasedTriggeringPolicy is used to ensure the current log file does not exceed a certain size (the default is 20 MB) and is rolled over to an archive file to start a fresh log file. By default up to 5 archived log files are kept, the oldest is deleted when required to make room for a new archive file.

  MQLIGHT_JAVA_LOG_STREAM can also be set to stdout or stderr to direct all log output to stdout or stderr as required.

• MQLIGHT_JAVA_LOG_FILE_COUNT can be set to specify the number of archive log files that should be kept, when MQLIGHT_JAVA_LOG_STREAM is specified as a file path prefix.

• MQLIGHT_JAVA_LOG_FILE_LIMIT can be set to specify the maximum size of the log files when MQLIGHT_JAVA_LOG_STREAM is specified as a file path prefix. The value can be specified in bytes, kilobytes, megabytes, or gigabytes by suffixing a numeric value with KB, MB, and GB respectively.

• MQLIGHT_JAVA_LOG_TRACE_ARG_MAX_BYTES can be set to specify the maximum number of bytes output for each argument, truncating any over length arguments from the right. By default the maximum number of bytes output for each argument is 1024.

• No support for dispatching application callbacks into a pool of threads. Callbacks are run on whatever thread needs to call back into application code - which is not a good fit for some workloads.

-- [maven-url]: https://search.maven.org/#search%7Cga%7C1%7Cmqlight [maven-img]: https://img.shields.io/maven-central/v/com.ibm.mqlight/mqlight-api.svg