Network interceptors

This extension allows user-defined code to intercept and make use of any JPPF-initiated network connection as soon as it is established. A typical use of this extension is so you can perform a custom authentication procedure before a connection is considered valid, but it is not limited to that.

The network interceptors are used with all possible types of network connections in JPPF: client to driver, node to driver, driver to driver, JMX connections and recovery connections (heart-beat mechanism) between nodes and drivers.

1 Creating a network interceptor

To define a network interceptor, simply create a class with a no-arg constructor that implements the interface NetworkCommunicationInterceptor, which is defined like this:

public interface NetworkConnectionInterceptor {
  // The list of interceptors loaded via the Service Provider Interface
  List<NetworkConnectionInterceptor> INTERCEPTORS;

  // Called when a Socket is accepted by a ServerSocket
  // on the server side of a connection
  boolean onAccept(Socket acceptedSocket);

  // Called when a SocketChannel is accepted by a ServerSocketChannel
  // on the server side of a connection
  boolean onAccept(SocketChannel acceptedChannel);

  // Called when a Socket is connected on the client side of a connection
  boolean onConnect(Socket connectedSocket);

  // Called when a SocketChannel is connected on the client side of a connection
  boolean onConnect(SocketChannel connectedChannel);
}

Note that there are 2 onAccept() and 2 onConnect() methods: one takes a Socket as input, the other takes a SocketChannel. SocketChannels are used by the JPPF driver for connections with nodes, clients or other servers. The JPPF driver makes sure they are configured in blocking mode before passing them to an interceptor.

In terms of semantics, onAccept() is called from the server side of a connection: the provided Socket or SocketChannel is obtained from a call to ServerSocket.accept() and ServerSocketChannel.accept(), respectively. On the other hand, onConnect() is called from the client side of a connection, that is, the side that initiates the connection.

In practice, Socket and SocketChannel use very different APIs for I/O reads and writes. However, when a SocketChannel is configured in blocking mode, it is possible to work directly with the underlying Socket via a prior call to SocketChannel.socket(). Consequently, you could write your interceptor like this:

public class MyInterceptor implements NetworkConnectionInterceptor {
  @Override
  public boolean onAccept(Socket acceptedSocket) {
    // do the job ...
    return ...;
  }

  @Override
  public boolean onConnect(Socket connectedSocket) {
    // do the job ...
    return ...;
  }

  @Override
  public boolean onAccept(SocketChannel acceptedChannel) {
    return onAccept(acceptedChannel.socket());
  }

  @Override
  public boolean onConnect(SocketChannel connectedChannel) {
    return onConnect(connectedChannel.socket());
  }
}

To make life even easier, JPPF provides the class AbstractNetworkConnectionInterceptor, which implements the methods from NetworkCommunicationInterceptor as in the example above, and delegates the sream-based processing to two abstract methods. Our example could then be rewritten as:

public class MyInterceptor extends AbstractNetworkConnectionInterceptor {
  @Override
  public boolean onAccept(Socket acceptedSocket) {
    // do the job ...
    return ...;
  }

  @Override
  public boolean onConnect(Socket connectedSocket) {
    // do the job ...
    return ...;
  }
}

2 Plugging-in the interceptor

To diescover the interceptor, JPPF uses the Service Provider Interface (SPI):

• in your sources or resources folder, create a file org.jppf.comm.interceptor.NetworkConnectionInterceptor in the META-INF/services folder
• in this file, add the fully qualified name of your interceptor implementation class, e.g.: org.example.MyInterceptor
• make sure the file META-INF/services/org.jppf.comm.interceptor.NetworkConnectionInterceptor is then placed into the resulting jar file
• add the jar file to the classpath of all JPPF components in your grid topology

3 Related sample

The Network Interceptor demo illustrates a simple encrypted authentication scheme implemented with an interceptor.