org.licas.call

## Class CallPool

- java.lang.Object
- - org.licas.call.CallPool

- All Implemented Interfaces:
    java.lang.AutoCloseable

      public final class CallPool
      extends java.lang.Object
      implements java.lang.AutoCloseable

  This stores a pool of `MethodInfo`s allowing for several object or communication invocations to be run at the same time, each run in a separate `InvokeThread`. There is a single execution option, or a timed loop option, for repeating each call. There is also the option for making a callback to the invoking object, to notify it when each execution phase has completed. That is - after one complete cycle through executing each of the methods.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CallPool(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos)` Create a new instance of CallPool.
    `CallPool(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos, MethodInfo theCallback)` Create a new instance of CallPool.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Clean-up before shutting down the service.
    `void` | `executeLoop(int thisSleepTime)` Perform one cycle through executing each method and try the callback method at the end, then repeat this indefinitely with a timed delay between each execution phase.
    `void` | `executeOnce()` Perform just one cycle through executing each method and try the callback method at the end.
    `java.util.ArrayList<java.lang.String>` | `getKeys()` Get the key list for the methods to execute.
    `java.lang.Object` | `getResult(java.lang.String key)` Get the method invocation result for a particular method.
    `java.util.HashMap<java.lang.String,java.lang.Object>` | `getResults()` Get the full method invocation result set, as a cloned HashMap.
    `boolean` | `getShutDown()` Get the current CallPool status.
    `boolean` | `getStarted()` Indicates if the loop has started.
    `void` | `resetTimeInterval(int thisSleepTime)` Reset the loop delay time.
    `protected void` | `setShutDown(boolean thisShutDown)` Set the shut down variable to value passed in.
    `void` | `shutDown()` Shut down the whole CallPool thread.
    `static CallPool` | `syncExecuteLoop(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos, MethodInfo theCallback, int thisSleepTime)` Create a new instance of CallPool and synchronize a loop execution with the construction process.
    `static CallPool` | `syncExecuteOnce(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos, MethodInfo theCallback)` Create a new instance of CallPool and synchronize a single execution with the construction process.
    `protected void` | `tryCallback()` If the callback method is not null, try to execute it.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CallPool

          public CallPool(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos)

      Create a new instance of CallPool. This sets the callback method to null, or does not perform any callback.
      Parameters:
        `theMethodInfos` - the list of methods to invoke. The key is a unique identifier and the value is of type `MethodInfo`.

    - #### CallPool

          public CallPool(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos,
                          MethodInfo theCallback)

      Create a new instance of CallPool.
      Parameters:
        `theMethodInfos` - the list of methods to invoke. The key is a unique identifier and the value is of type `MethodInfo`.
        `theCallback` - the method to invoke on the parent object after each execution phase.

  - ### Method Detail

    - #### executeOnce

          public void executeOnce()

      Perform just one cycle through executing each method and try the callback method at the end.

    - #### executeLoop

          public void executeLoop(int thisSleepTime)

      Perform one cycle through executing each method and try the callback method at the end, then repeat this indefinitely with a timed delay between each execution phase. Note that results are overwritten each execution phase.
      Parameters:
        `thisSleepTime` - the time to sleep between each execution phase of all methods.

    - #### tryCallback

          protected void tryCallback()

      If the callback method is not null, try to execute it.

    - #### resetTimeInterval

          public void resetTimeInterval(int thisSleepTime)

      Reset the loop delay time.
      Parameters:
        `thisSleepTime` - the time to sleep between execution phases.

    - #### getKeys

          public java.util.ArrayList<java.lang.String> getKeys()

      Get the key list for the methods to execute.
      Returns:
        the list of `methodInfos` keys. Not the callback method.

    - #### getResult

          public java.lang.Object getResult(java.lang.String key)

      Get the method invocation result for a particular method. This will then also reset the result value to null once retrieved. If there is no stored result, (or if it was null) then null is returned.
      Parameters:
        `key` - the key for the result entry.
      Returns:
        the value of the result.

    - #### getResults

          public java.util.HashMap<java.lang.String,java.lang.Object> getResults()

      Get the full method invocation result set, as a cloned HashMap.
      Returns:
        the value of results. If a reply was null, then the entry will be missing.

    - #### getStarted

          public boolean getStarted()

      Indicates if the loop has started.
      Returns:
        the value of started.

    - #### syncExecuteLoop

          public static CallPool syncExecuteLoop(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos,
                                                 MethodInfo theCallback,
                                                 int thisSleepTime)

      Create a new instance of CallPool and synchronize a loop execution with the construction process. This should be more thread-safe.
      Parameters:
        `theMethodInfos` - the list of methods to invoke. The key is a unique identifier and the value is of type `MethodInfo`.
        `theCallback` - the method to invoke on the parent object after each execution phase.
        `thisSleepTime` - the time to sleep between each execution phase of all methods.
      Returns:
        the CallPool object, initialised and running.

    - #### syncExecuteOnce

          public static CallPool syncExecuteOnce(java.util.HashMap<java.lang.String,MethodInfo> theMethodInfos,
                                                 MethodInfo theCallback)

      Create a new instance of CallPool and synchronize a single execution with the construction process. This should be more thread-safe.
      Parameters:
        `theMethodInfos` - the list of methods to invoke. The key is a unique identifier and the value is of type `MethodInfo`.
        `theCallback` - the method to invoke on the parent object after each execution phase.
      Returns:
        the CallPool object, initialised and running.

    - #### shutDown

          public void shutDown()

      Shut down the whole CallPool thread.

    - #### setShutDown

          protected void setShutDown(boolean thisShutDown)

      Set the shut down variable to value passed in.
      Parameters:
        `thisShutDown` - true if shut down, false if keep running.

    - #### getShutDown

          public boolean getShutDown()

      Get the current CallPool status.
      Returns:
        the value of shutDown.

    - #### close

          public void close()

      Clean-up before shutting down the service.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`