Put configuration properties behind getters and chain-setters

Author: dgant

src/main/java/bwapi/BWClient.java

@@ -47,7 +47,7 @@ public BWClientConfiguration getConfiguration() {
      * @return Whether the current frame should be subject to timing.
      */
     boolean doTime() {
-        return ! configuration.unlimitedFrameZero || (client.isConnected() && client.clientData().gameData().getFrameCount() > 0);
+        return ! configuration.getUnlimitedFrameZero() || (client.isConnected() && client.clientData().gameData().getFrameCount() > 0);
     }
 
     /**
@@ -81,7 +81,7 @@ public void startGame() {
     @Deprecated
     public void startGame(boolean autoContinue) {
         BWClientConfiguration configuration = new BWClientConfiguration();
-        configuration.autoContinue = autoContinue;
+        configuration.withAutoContinue(autoContinue);
         startGame(configuration);
     }
 
@@ -99,7 +99,7 @@ public void startGame(BWClientConfiguration gameConfiguration) {
         // Use reduced priority to encourage Windows to give priority to StarCraft.exe/BWAPI.
         // If BWAPI doesn't get priority, it may not detect completion of a frame on our end in timely fashion.
         Thread.currentThread().setName("JBWAPI Client");
-        if (configuration.async) {
+        if (configuration.getAsync()) {
             Thread.currentThread().setPriority(4);
         }
 
@@ -135,7 +135,7 @@ public void startGame(BWClientConfiguration gameConfiguration) {
                 }
             }
             botWrapper.endGame();
-        } while (configuration.autoContinue);
+        } while (configuration.getAutoContinue());
     }
 
     /**

src/main/java/bwapi/BWClientConfiguration.java

@@ -8,12 +8,26 @@ public class BWClientConfiguration {
     /**
      * Set to `true` for more explicit error messages (which might spam the terminal).
      */
-    public boolean debugConnection;
+    public BWClientConfiguration withDebugConnection(boolean value) {
+        debugConnection = value;
+        return this;
+    }
+    boolean getDebugConnection() {
+        return debugConnection;
+    }
+    private boolean debugConnection;
 
     /**
      * When true, restarts the client loop when a game ends, allowing the client to play multiple games without restarting.
      */
-    public boolean autoContinue = false;
+    public BWClientConfiguration withAutoContinue(boolean value) {
+        autoContinue = value;
+        return this;
+    }
+    boolean getAutoContinue() {
+        return autoContinue;
+    }
+    private boolean autoContinue = false;
 
     /**
      * Most bot tournaments allow bots to take an indefinite amount of time on frame #0 (the first frame of the game) to analyze the map and load data,
@@ -23,15 +37,29 @@ public class BWClientConfiguration {
      * Performance metrics omit the frame as an outlier.
      * Asynchronous operation will block until the bot's event handlers are complete.
      */
-    public boolean unlimitedFrameZero = true;
+    public BWClientConfiguration withUnlimitedFrameZero(boolean value) {
+        unlimitedFrameZero = value;
+        return this;
+    }
+    boolean getUnlimitedFrameZero() {
+        return unlimitedFrameZero;
+    }
+    private boolean unlimitedFrameZero = true;
 
     /**
      * The maximum amount of time the bot is supposed to spend on a single frame.
      * In asynchronous mode, JBWAPI will attempt to let the bot use up to this much time to process all frames before returning control to BWAPI.
      * In synchronous mode, JBWAPI is not empowered to prevent the bot to exceed this amount, but will record overruns in performance metrics.
      * Real-time human play typically uses the "fastest" game speed, which has 42.86ms (42,860ns) between frames.
      */
-    public int maxFrameDurationMs = 40;
+    public BWClientConfiguration withMaxFrameDurationMs(int value) {
+        maxFrameDurationMs = value;
+        return this;
+    }
+    int getMaxFrameDurationMs() {
+        return maxFrameDurationMs;
+    }
+    private int maxFrameDurationMs = 40;
 
     /**
      * Runs the bot in asynchronous mode. Asynchronous mode helps attempt to ensure that the bot adheres to real-time performance constraints.
@@ -44,13 +72,27 @@ public class BWClientConfiguration {
      * real-time performance requirements, while not fully guaranteeing it (subject to the whims of the JVM thread scheduler), at a cost of the bot possibly
      * issuing commands later than intended, and a marginally larger memory footprint.
      */
-    public boolean async = false;
+    public BWClientConfiguration withAsync(boolean value) {
+        async = value;
+        return this;
+    }
+    boolean getAsync() {
+        return async;
+    }
+    private boolean async = false;
 
     /**
      * The maximum number of frames to buffer while waiting on a bot.
      * Each frame buffered adds about 33 megabytes to JBWAPI's memory footprint.
      */
-    public int asyncFrameBufferCapacity = 10;
+    public BWClientConfiguration withAsyncFrameBufferCapacity(int size) {
+        asyncFrameBufferCapacity = size;
+        return this;
+    }
+    int getAsyncFrameBufferCapacity() {
+        return asyncFrameBufferCapacity;
+    }
+    private int asyncFrameBufferCapacity = 10;
 
     /**
      * Enables thread-unsafe async mode.
@@ -59,17 +101,34 @@ public class BWClientConfiguration {
      * This should enhance performance by allowing the bot to act while the frame is copied, but poses unidentified risk due to
      * the non-thread-safe switc from shared memory reads to frame buffer reads.
      */
-    public boolean asyncUnsafe = false;
+    public BWClientConfiguration withAsyncUnsafe(boolean value) {
+        asyncUnsafe = value;
+        return this;
+    }
+    boolean getAsyncUnsafe() {
+        return asyncUnsafe;
+    }
+    private boolean asyncUnsafe = false;
 
     /**
      * Toggles verbose logging, particularly of synchronization steps.
      */
-    public boolean logVerbosely = false;
+    public BWClientConfiguration withLogVerbosely(boolean value) {
+        logVerbosely = value;
+        return this;
+    }
+    boolean getLogVerbosely() {
+        return logVerbosely;
+    }
+    private boolean logVerbosely = false;
 
     /**
      * Checks that the configuration is in a valid state. Throws an IllegalArgumentException if it isn't.
      */
     void validate() {
+        if (asyncUnsafe && ! async) {
+            throw new IllegalArgumentException("asyncUnsafe mode needs async mode.");
+        }
         if (async && maxFrameDurationMs < 0) {
             throw new IllegalArgumentException("maxFrameDurationMs needs to be a non-negative number (it's how long JBWAPI waits for a bot response before returning control to BWAPI).");
         }

src/main/java/bwapi/BotWrapper.java

@@ -24,14 +24,14 @@ class BotWrapper {
     BotWrapper(BWClientConfiguration configuration, BWEventListener eventListener) {
         this.configuration = configuration;
         this.eventListener = eventListener;
-        frameBuffer = configuration.async ? new FrameBuffer(configuration) : null;
+        frameBuffer = configuration.getAsync() ? new FrameBuffer(configuration) : null;
     }
 
     /**
      * Resets the BotWrapper for a new botGame.
      */
     void startNewGame(ByteBuffer liveData, PerformanceMetrics performanceMetrics) {
-        if (configuration.async) {
+        if (configuration.getAsync()) {
             frameBuffer.initialize(liveData, performanceMetrics);
         }
         this.performanceMetrics = performanceMetrics;
@@ -73,10 +73,10 @@ private void setUnsafeReadReady(boolean value) {
      * Handles the arrival of a new frame from BWAPI
      */
     void onFrame() {
-        if (configuration.async) {
+        if (configuration.getAsync()) {
             configuration.log("Main: onFrame asynchronous start");
             long startNanos = System.nanoTime();
-            long endNanos = startNanos + configuration.maxFrameDurationMs * 1000000;
+            long endNanos = startNanos + configuration.getMaxFrameDurationMs() * 1000000;
             if (botThread == null) {
                 configuration.log("Main: Starting bot thread");
                 botThread = createBotThread();
@@ -89,7 +89,7 @@ void onFrame() {
             // Unsafe mode:
             // If the frame buffer is empty (meaning the bot must be idle)
             // allow the bot to read directly from shared memory while we copy it over
-            if (configuration.asyncUnsafe) {
+            if (configuration.getAsyncUnsafe()) {
                 frameBuffer.lockSize.lock();
                 try {
                     if (frameBuffer.empty()) {
@@ -123,7 +123,7 @@ void onFrame() {
                     // We don't synchronize on calls which access the buffer
                     // (to avoid tens of thousands of synchronized calls per frame)
                     // so there's no guarantee of safety here.
-                    if (configuration.asyncUnsafe && frameBuffer.size() == 1) {
+                    if (configuration.getAsyncUnsafe() && frameBuffer.size() == 1) {
                         configuration.log("Main: Weaning bot off live data");
                         botGame.clientData().setBuffer(frameBuffer.peek());
                     }
@@ -135,7 +135,7 @@ void onFrame() {
                         throw new RuntimeException(lastThrow);
                     }
 
-                    if (configuration.unlimitedFrameZero && frame == 0) {
+                    if (configuration.getUnlimitedFrameZero() && frame == 0) {
                         configuration.log("Main: Waiting indefinitely on frame #" + frame);
                         frameBuffer.conditionSize.await();
                     } else {
@@ -242,12 +242,12 @@ private void handleEvents() {
             gameOver = gameOver || gameData.getEvents(i).getType() == EventType.MatchEnd;
         }
 
-        if (configuration.async) {
+        if (configuration.getAsync()) {
             performanceMetrics.getFramesBehind().record(Math.max(1, frameBuffer.framesBuffered()) - 1);
         }
 
         performanceMetrics.getBotResponse().timeIf(
-            ! gameOver && (gameData.getFrameCount() > 0 || ! configuration.unlimitedFrameZero),
+            ! gameOver && (gameData.getFrameCount() > 0 || ! configuration.getUnlimitedFrameZero()),
             () -> {
                 for (int i = 0; i < gameData.getEventCount(); i++) {
                     EventHandler.operation(eventListener, botGame, gameData.getEvents(i));

src/main/java/bwapi/Client.java

@@ -82,7 +82,7 @@ void reconnect() {
     }
 
     private void disconnect() {
-        if (bwClient.getConfiguration().debugConnection) {
+        if (bwClient.getConfiguration().getDebugConnection()) {
             System.err.print("Disconnect called by: ");
             System.err.println(Thread.currentThread().getStackTrace()[2]);
         }
@@ -133,7 +133,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to map Game table.");
-            if (bwClient.getConfiguration().debugConnection) {
+            if (bwClient.getConfiguration().getDebugConnection()) {
                 e.printStackTrace();
             }
             return false;
@@ -167,7 +167,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to open communications pipe: " + communicationPipe);
-            if (bwClient.getConfiguration().debugConnection) {
+            if (bwClient.getConfiguration().getDebugConnection()) {
                 e.printStackTrace();
             }
             gameTableFileHandle = null;
@@ -183,7 +183,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to open shared memory mapping: " + sharedMemoryName);
-            if (bwClient.getConfiguration().debugConnection) {
+            if (bwClient.getConfiguration().getDebugConnection()) {
                 e.printStackTrace();
             }
             pipeObjectHandle = null;
@@ -196,7 +196,7 @@ boolean connect() {
         }
         catch (Exception e) {
             System.err.println("Unable to map game data.");
-            if (bwClient.getConfiguration().debugConnection) {
+            if (bwClient.getConfiguration().getDebugConnection()) {
                 e.printStackTrace();
             }
             return false;
@@ -217,7 +217,7 @@ boolean connect() {
             }
             catch (Exception e) {
                 System.err.println("Unable to read pipe object.");
-                if (bwClient.getConfiguration().debugConnection) {
+                if (bwClient.getConfiguration().getDebugConnection()) {
                     e.printStackTrace();
                 }
                 disconnect();
@@ -245,7 +245,7 @@ void sendFrameReceiveFrame() {
         }
         catch (Exception e) {
             System.err.println("failed, disconnecting");
-            if (bwClient.getConfiguration().debugConnection) {
+            if (bwClient.getConfiguration().getDebugConnection()) {
                 e.printStackTrace();
             }
             disconnect();
@@ -272,7 +272,7 @@ void sendFrameReceiveFrame() {
                 frameReady = pipeObjectHandle.readByte() == 2;
             } catch (Exception e) {
                 System.err.println("failed, disconnecting");
-                if (bwClient.getConfiguration().debugConnection) {
+                if (bwClient.getConfiguration().getDebugConnection()) {
                     e.printStackTrace();
                 }
                 disconnect();

src/main/java/bwapi/FrameBuffer.java

@@ -27,7 +27,7 @@ class FrameBuffer {
     final Condition conditionSize = lockSize.newCondition();
 
     FrameBuffer(BWClientConfiguration configuration) {
-        this.capacity = configuration.asyncFrameBufferCapacity;
+        this.capacity = configuration.getAsyncFrameBufferCapacity();
         this.configuration = configuration;
         while(dataBuffer.size() < capacity) {
             dataBuffer.add(ByteBuffer.allocateDirect(BUFFER_SIZE));

src/main/java/bwapi/PerformanceMetrics.java

@@ -229,7 +229,7 @@ public void reset() {
         flushSideEffects = new PerformanceMetric(this, "Time flushing side effects", 1, 3, 5);
         botResponse = new PerformanceMetric(this, "Duration of bot event handlers", 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 85);
         botIdle = new PerformanceMetric(this, "Time bot spent idle", Long.MAX_VALUE);
-        clientIdle = new PerformanceMetric(this, "Time client spent waiting for bot", configuration.maxFrameDurationMs);
+        clientIdle = new PerformanceMetric(this, "Time client spent waiting for bot", configuration.getMaxFrameDurationMs());
         excessSleep = new PerformanceMetric(this, "Excess duration of client sleep", 1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 85);
         numberOfEvents = new PerformanceMetric(this, "Number of events received from BWAPI", 1, 2, 3, 4, 5, 6, 8, 10, 15, 20);
         numberOfEventsTimesDurationReceiveToSent = new PerformanceMetric(this, "Number of events received from BWAPI, multiplied by the receive-to-sent duration of that frame", 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 85);

src/test/java/bwapi/SynchronizationEnvironment.java

@@ -84,10 +84,10 @@ void runGame() {
 
     void runGame(int onEndFrame) {
         this.onEndFrame = onEndFrame;
-        if (configuration.async) {
+        if (configuration.getAsync()) {
             final long MEGABYTE = 1024 * 1024;
             long memoryFree = Runtime.getRuntime().freeMemory() / MEGABYTE;
-            long memoryRequired = configuration.asyncFrameBufferCapacity * ClientData.GameData.SIZE / MEGABYTE;
+            long memoryRequired = configuration.getAsyncFrameBufferCapacity() * ClientData.GameData.SIZE / MEGABYTE;
             assertTrue(
                     "Unit test needs to be run with sufficient memory to allocate frame buffer. Has "
                             + memoryFree