Creating PMI Clients

PMI operations are identified by a string and can be initiated by clients using the cache.invoke method.

Prerequisites

• ScaleOut StateServer Pro license

Procedure

Note

This sample in its entirety is available on our GitHub Samples Repo.

1. Determine the name of the PMI operation to execute.

   • A handler application hosts the code implementing the PMI operation. Your client will use the same operationId identifier that the handler uses when it registers with the ScaleOut service.

2. Connect to the ScaleOut service and build a cache.

   • A PMI operation is scoped to the objects in a cache. Use the same cache that the PMI handler app uses when it registers with the ScaleOut service.

   • In this example, the PMI client uses the same cache as the handler in the Creating PMI Handlers topic.

   package com.scaleout.client.samples.compute;
   
   import com.scaleout.client.GridConnectException;
   import com.scaleout.client.GridConnection;
   import com.scaleout.client.caching.Cache;
   import com.scaleout.client.caching.CacheBuilder;
   import com.scaleout.client.caching.CacheException;
   import com.scaleout.client.caching.InvokeResponse;
   
   import java.nio.charset.StandardCharsets;
   import java.time.Duration;
   
   public class PMIClientSample {
       public static void main(String[] args) throws GridConnectException, CacheException {
           // Connect to the cache that stores login times.
           GridConnection connection = GridConnection.connect("bootstrapGateways=localhost");
           Cache<String, Long> cache = new CacheBuilder<String, Long>(connection, "PMISample", String.class)
                   .build();
   
           // Add some test data to the cache:
           for (int i = 0; i < 50; i++)
           {
               long lastLogin = System.currentTimeMillis() - Duration.ofDays(i % 10).toMillis();
               cache.addOrUpdate("User_"+i, lastLogin);
           }
           // ... continued below
   

3. Use the cache.invoke method to execute the PMI operation on the farm of ScaleOut hosts. The parameters to the invoke operation are:

   • operationId: The name of a registered invocation handler that is running on the ScaleOut farm.

   • invokeTimeout: The maximum allowed time for the PMI operation to complete. Use Duration.ZERO or null to wait indefinitely.

   InvokeResponse response = cache.invoke("Find inactive users", Duration.ofSeconds(0));
   

4. Check whether the PMI operation succeeded or failed.

   • If an unhandled exception is thrown from an invocation handler, error data will be sent back and made available to the Invoke client through InvokeResponse.getErrorData(). The representation and encoding of the error will vary depending on the library that is used to handle the PMI operation; if the handler is implemented using the Scaleout Client library, the error will be the full printStackTrace() String representation of the exception, encoded as UTF-8.

   switch (response.getRequestStatus()) {
       case InvokeComplete:
           System.out.println("Invoke complete.");
           System.out.println(response.getSuccessCount() + " were successfully evaluated.");
           break;
       case UnhandledExceptionInCallback:
           System.out.println("Unhandled exception thrown from PMI Handler.");
           System.out.println(new String(response.getErrorData(), StandardCharsets.UTF_8));
           break;
       default:
           System.out.println("Unexpected response: " + response.getRequestStatus());
   }