Merge pull request #7 from antithesishq/feature-reorganize-packages

Hoist packages!

sdk/build.gradle

@@ -6,18 +6,12 @@ repositories {
     mavenCentral()
 }
 
-project.logger.lifecycle("Hi world")
-
 dependencies {
-    // Concrete Jackson version released before JDK8, runtime requires the injection of a compatible Jackson implementation
-    // https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind
     api 'com.fasterxml.jackson.core:jackson-databind:2.2.3'
 
-    // implementation project(':ffi')
     implementation(files("libs/antithesis-ffi-1.3.1.jar"))
 
     // Use JUnit Jupiter for testing.
-    testImplementation group: 'com.googlecode.json-simple', name: 'json-simple', version: '1.1.1'
     testImplementation 'org.junit.jupiter:junit-jupiter:5.9.3'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
     testImplementation 'com.fasterxml.jackson.core:jackson-databind:2.2.3'

sdk/src/main/java/com/antithesis/sdk/assertions/Assertions.java → sdk/src/main/java/com/antithesis/sdk/Assertions.java

@@ -1,37 +1,28 @@
-package com.antithesis.sdk.assertions;
+package com.antithesis.sdk;
 
 import com.antithesis.sdk.internal.Assertion;
 import com.antithesis.sdk.internal.LocationInfo;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 
 /**
- * Assertions contains static methods for 
- * always, sometimes, alwaysOrUnrechable, reachable and unreachable
+ * The assertions class enables defining <a href="https://antithesis.com/docs/using_antithesis/properties.html" target="_blank">test properties</a>
+ * about your program or <a href="https://antithesis.com/docs/getting_started/workload.html" target="_blank">workload</a>.
+ * <p>
+ * Each static method in this class takes a parameter called <code>message</code>, which is
+ * a string literal identifier used to aggregate assertions.
+ * Antithesis generates one test property per unique <code>message</code> This test property will be named <code>message</code> in the <a href="https://antithesis.com/docs/reports/triage.html" target="_blank">triage report</a>.
+ * <p>
+ * Each static method also takes a parameter called <code>details</code>, which is an <code>ObjectNode</code> reference of optional additional information provided by the user to add context for assertion failures.
+ * The information that is logged will appear in the <code>logs</code> section of a <a href="https://antithesis.com/docs/reports/triage.html" target="_blank">triage report</a>.
+ * Normally the values in <code>details</code> are evaluated at runtime.
  */
 final public class Assertions {
 
-    /**
-     * Types of assertions available
-     */
-    public enum AssertType {
-        /**
-         * Condition must always be true
-         */
-        Always,
-        /**
-         * Condition must be true at least once
-         */
-        Sometimes,
-        /**
-         * Indicates if an assertion should be encountered
-         */
-        Reachability
-    }
-
     /**
      * Default constructor
      */
-    public Assertions(){}
+    public Assertions() {
+    }
 
     /**
      * Assert that <code>condition</code> is true every time this function is called, <i>and</i> that it is
@@ -155,7 +146,7 @@ public static void reachable(final String message, final ObjectNode details) {
 
     /**
      * This is a low-level method designed to be used by third-party frameworks.
-     * Regular users of the assertions package should not call it.
+     * Regular users of the assertions class should not call it.
      * <p>
      * This is primarily intended for use by adapters from other
      * diagnostic tools that intend to output Antithesis-style
@@ -220,4 +211,22 @@ public static void rawAssert(
                 .build()
                 .trackEntry();
     }
+
+    /**
+     * Types of assertions available
+     */
+    public enum AssertType {
+        /**
+         * Condition must always be true
+         */
+        Always,
+        /**
+         * Condition must be true at least once
+         */
+        Sometimes,
+        /**
+         * Indicates if an assertion should be encountered
+         */
+        Reachability
+    }
 }

sdk/src/main/java/com/antithesis/sdk/lifecycle/Lifecycle.java → sdk/src/main/java/com/antithesis/sdk/Lifecycle.java

@@ -1,19 +1,20 @@
-package com.antithesis.sdk.lifecycle;
+package com.antithesis.sdk;
 
 import com.antithesis.sdk.internal.Internal;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 
 /**
- * Lifecycle contains static methods for 
- * setupComplete and sendEvent
+ * The lifecycle class contains methods which inform the Antithesis
+ * environment that particular test phases or milestones have been reached.
  */
 final public class Lifecycle {
 
     /**
      * Default constructor
      */
-    public Lifecycle(){}
+    public Lifecycle() {
+    }
 
     /**
      * Indicates to Antithesis that setup has completed. Call this function when

sdk/src/main/java/com/antithesis/sdk/random/Random.java → sdk/src/main/java/com/antithesis/sdk/Random.java

@@ -1,19 +1,26 @@
-package com.antithesis.sdk.random;
+package com.antithesis.sdk;
 
 import com.antithesis.sdk.internal.Internal;
 
 import java.util.Optional;
 
 /**
- * Random contains static methods for
- * getRandom and randomChoice
+ * The random class provides methods that request both structured and unstructured randomness from the Antithesis environment.
+ * <p>
+ * These methods should not be used to seed a conventional PRNG, and should not have their return values stored and used to make a decision at a later time.
+ * Doing either of these things makes it much harder for the Antithesis platform to control the history of your program's execution, and also makes it harder for Antithesis to learn which inputs provided at which times are most fruitful.
+ * Instead, you should call a method from the random class every time your program or <a href="https://antithesis.com/docs/getting_started/workload.html" target="_blank">workload</a> needs to make a decision, at the moment that you need to make the decision.
+ * <p>
+ * These methods are also safe to call outside the Antithesis environment, where
+ * they will fall back on the Java standard class library implementation.
  */
 final public class Random {
 
     /**
      * Default constructor
      */
-    public Random(){}
+    public Random() {
+    }
 
     /**
      * Returns a long value chosen by Antithesis. You should not

sdk/src/main/java/com/antithesis/sdk/internal/Assertion.java

@@ -1,6 +1,6 @@
 package com.antithesis.sdk.internal;
 
-import com.antithesis.sdk.assertions.Assertions;
+import com.antithesis.sdk.Assertions;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.JsonSerializer;
@@ -19,33 +19,6 @@ public final class Assertion {
 
     private static final LocationInfo NoInfo = new LocationInfo(
             "class", "function", "file", 0, 0);
-
-    private static class TrackingInfo {
-        int passCount = 0;
-        int failCount = 0;
-        LocationInfo locInfo;
-
-        public TrackingInfo(final LocationInfo locInfo) {
-            this.locInfo = locInfo;
-        }
-
-        protected void trackPass() {
-            this.passCount++;
-        }
-
-        protected void trackFail() {
-            this.failCount++;
-        }
-
-        protected void setLocationInfo(final LocationInfo locInfo) {
-            this.locInfo = locInfo;
-        }
-
-        protected LocationInfo getLocationInfo() {
-            return this.locInfo;
-        }
-    }
-
     private static final Map<String, TrackingInfo> TRACKER = new ConcurrentHashMap<>();
     private static final ObjectMapper MAPPER;
 
@@ -68,28 +41,20 @@ public void serialize(Assertions.AssertType value, JsonGenerator jsonGen, Serial
 
     @JsonProperty("assert_type")
     final private Assertions.AssertType assertType;
-
     @JsonProperty("display_type")
     final private String displayType;
-
     @JsonProperty("condition")
     final private boolean condition;
-
     @JsonProperty("message")
     final private String message;
-
     @JsonProperty("location")
     final private LocationInfo location;
-
     @JsonProperty("hit")
     final private boolean hit;
-
     @JsonProperty("must_hit")
     final private boolean mustHit;
-
     @JsonProperty("id")
     final private String id;
-
     @JsonProperty("details")
     final private ObjectNode details;
 
@@ -137,6 +102,32 @@ private void emit() {
         Internal.dispatchOutput(MAPPER.valueToTree(this));
     }
 
+    private static class TrackingInfo {
+        int passCount = 0;
+        int failCount = 0;
+        LocationInfo locInfo;
+
+        public TrackingInfo(final LocationInfo locInfo) {
+            this.locInfo = locInfo;
+        }
+
+        protected void trackPass() {
+            this.passCount++;
+        }
+
+        protected void trackFail() {
+            this.failCount++;
+        }
+
+        protected LocationInfo getLocationInfo() {
+            return this.locInfo;
+        }
+
+        protected void setLocationInfo(final LocationInfo locInfo) {
+            this.locInfo = locInfo;
+        }
+    }
+
 }
 
 

sdk/src/main/java/com/antithesis/sdk/internal/HandlerFactory.java

@@ -1,21 +1,20 @@
 package com.antithesis.sdk.internal;
 
+import com.antithesis.ffi.internal.FfiHandler;
+import com.antithesis.ffi.internal.OutputHandler;
+
 import java.io.File;
 import java.io.FileWriter;
 import java.io.IOException;
 import java.util.Optional;
 import java.util.Random;
 
-import com.antithesis.ffi.internal.OutputHandler;
-import com.antithesis.ffi.internal.FfiHandler;
-
 public class HandlerFactory {
 
+    private final static boolean CATALOG_SENT = didLoadCatalog();
     // Will be initialized through the static 'HandlerFactory.get()' function
     private static OutputHandler HANDLER_INSTANCE = null;
 
-    private final static boolean CATALOG_SENT = didLoadCatalog();
-
     private static boolean didLoadCatalog() {
         String className = "com.antithesis.sdk.generated.AssertionCatalog";
         ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
@@ -26,7 +25,8 @@ private static boolean didLoadCatalog() {
         boolean shouldInitialize = true;
         try {
             theClass = Class.forName(className, shouldInitialize, classLoader);
-        } catch (Throwable ignored) {}
+        } catch (Throwable ignored) {
+        }
         return theClass != null;
     }
 
@@ -69,7 +69,6 @@ public long initializeModuleCoverage(long edgeCount, String symbolFilePath) {
 
         @Override
         public void notifyModuleEdge(long edgePlusModule) {
-            return;
         }
     }
 
@@ -119,7 +118,6 @@ public long initializeModuleCoverage(long edgeCount, String symbolFilePath) {
 
         @Override
         public void notifyModuleEdge(long edgePlusModule) {
-            return;
         }
     }
 

sdk/src/main/java/com/antithesis/sdk/internal/Internal.java

@@ -17,7 +17,8 @@ public static void dispatchOutput(final ObjectNode s) {
         try {
             String jsonStr = MAPPER.writeValueAsString(s);
             HandlerFactory.get().output(jsonStr);
-        } catch (IOException ignored) {}
+        } catch (IOException ignored) {
+        }
     }
 
     public static long dispatchInitializeModuleCoverage(long edgeCount, String symbolFilePath) {

sdk/src/test/java/com/antithesis/sdk/assertions/AssertionTest.java → sdk/src/test/java/com/antithesis/sdk/AssertionTest.java

@@ -1,4 +1,4 @@
-package com.antithesis.sdk.assertions;
+package com.antithesis.sdk;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;

sdk/src/test/java/com/antithesis/sdk/lifecycle/LifecycleTest.java → sdk/src/test/java/com/antithesis/sdk/LifecycleTest.java

@@ -1,4 +1,4 @@
-package com.antithesis.sdk.lifecycle;
+package com.antithesis.sdk;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;

sdk/src/test/java/com/antithesis/sdk/random/RandomTest.java → sdk/src/test/java/com/antithesis/sdk/RandomTest.java

@@ -1,4 +1,4 @@
-package com.antithesis.sdk.random;
+package com.antithesis.sdk;
 
 import org.junit.jupiter.api.Test;
 
@@ -46,7 +46,7 @@ void randomFewChoices() {
     @Test
     void getRandom10k() {
         HashSet<Long> random_numbers = new HashSet<Long>();
-        for(int i = 0; i < 10_000; i++) {
+        for (int i = 0; i < 10_000; i++) {
             long rn = Random.getRandom();
             assertFalse(random_numbers.contains(rn));
             random_numbers.add(rn);