Package com.ibm.mqlight.api

Non-blocking API

See: Description

Package com.ibm.mqlight.api Description

Non-blocking API

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() {
        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.

public static void main(String[] args) {
    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:
Diagram of a state machine

Getting started

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

Dependency Version
Google Gson 2.2.4
Logback Classic 1.1.2
Logback Core 1.1.2
Apache Netty 4.0.21.Final
SLF4J 1.7.5
Stateless4J 2.5.0

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.

Plug-points for extending the client

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.

Interface Description Supplied implementations
com.ibm.mqlight.api.callback.CallbackService A plug point for the code that is run each time the client needs to call back into application code. The client supplies two implementations. The first is: com.ibm.mqlight.api.callback.impl.SameThreadCallbackService, which calls back into application code using whatever thread calls in to the plug-point. This introduces minimal overhead on running callbacks - but is not suitable for callbacks that block. The second implementation is: com.ibm.mqlight.api.callback.impl.ThreadPoolCallbackService which schedules callbacks into a threadpool. The default is com.ibm.mqlight.api.callback.impl.ThreadPoolCallbackService.
com.ibm.mqlight.api.endpoint.EndpointService A plug point for determining the location of the MQ Light server (or service) to connect to. The client supplies two implementations, which can be chosen between depending on the value of the service parameter passed into the create method used to create the client. The first implementation is: com.ibm.mqlight.api.impl.endpoint.SingleEndpointService, which always returns the same endpoint details and is useful when connecting to the stand-alone MQ Light server. The second implementation is: com.ibm.mqlight.api.impl.endpoint.BluemixEndpointService, which (as the name suggests) looks up instances of the MQ Light service in the Bluemix environment.
com.ibm.mqlight.api.network.NetworkService A plug point for interfacing with the network used between the MQ Light client and server. The client supplies an Apache Netty-based implementation: com.ibm.mqlight.api.impl.network.NettyNetworkService
com.ibm.mqlight.api.timer A plug point for scheduling work to be done at some point in the future. The client uses this to implement inactivity timeouts for the AMQP protocol, and also a delay between repeated attempts to establish connectivity to the MQ Light server. The client supplies an implementation based on ScheduledThreadPoolExecutor: com.ibm.mqlight.api.impl.timer.TimerServiceImpl

Some notes on logging

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 (to any value) in which case DEBUG and above logging is enabled using Logback's BasicConfigurator.

Current limitations

Copyright © 2015 International Business Machines Corporation. All rights reserved.