Merge pull request #120 from strykeforce/kotlin-support

Add nullability annotations to Java client library

Author: jhh

client/build.gradle.kts

@@ -14,14 +14,14 @@ repositories {
 }
 
 dependencies {
-    val wpiVersion = "2022.2.1"
-    val slf4jVersion = "1.7.33"
+    val wpiVersion = "2022.4.1"
+    val slf4jVersion = "1.7.36"
     val junitVersion = "5.8.2"
     // This dependency is used internally, and not exposed to consumers on their own compile classpath.
     implementation("com.squareup.moshi:moshi:1.13.0")
     implementation("edu.wpi.first.ntcore:ntcore-java:$wpiVersion")
     implementation("org.slf4j:slf4j-api:$slf4jVersion")
-    implementation("org.jetbrains:annotations:22.0.0")
+    implementation("org.jetbrains:annotations:23.0.0")
 
 
     // Use JUnit Jupiter API for testing.
@@ -33,7 +33,7 @@ dependencies {
     testRuntimeOnly("edu.wpi.first.ntcore:ntcore-jni:$wpiVersion:osxx86-64")
     testRuntimeOnly("edu.wpi.first.ntcore:ntcore-jni:$wpiVersion:linuxx86-64")
     testRuntimeOnly("edu.wpi.first.wpiutil:wpiutil-java:$wpiVersion")
-    testRuntimeOnly("ch.qos.logback:logback-classic:1.2.10")
+    testRuntimeOnly("ch.qos.logback:logback-classic:1.2.11")
 }
 
 java {

client/src/main/java/org/strykeforce/deadeye/Deadeye.java

@@ -41,12 +41,13 @@
 public class Deadeye<T extends TargetData> {
 
   static final Logger logger = LoggerFactory.getLogger(Deadeye.class);
-  private static volatile Link link;
-  private final NetworkTable cameraTable;
-  private final String id;
-  private final DeadeyeJsonAdapter<T> jsonAdapter;
-  private TargetDataListener<T> targetDataListener;
-  private T targetData;
+  private static volatile @Nullable Link link;
+  private final @NotNull NetworkTable cameraTable;
+  private final @NotNull String id;
+  private final @NotNull DeadeyeJsonAdapter<T> jsonAdapter;
+  private @NotNull TargetDataListener<T> targetDataListener = data -> {
+  };
+  private @NotNull T targetData;
 
   /**
    * Constructs an instance of {@code Deadeye} and initializes a connection to the associated
@@ -55,11 +56,10 @@ public class Deadeye<T extends TargetData> {
    * @param id  the camera id, i.e. the Deadeye unit letter followed by the camera number, for
    *            example "A0".
    * @param cls the {@code TargetData} Java class corresponding to the Deadeye pipeline type.
-   * @throws NullPointerException     if the {@code cls} is {@code null}
    * @throws IllegalArgumentException if the {@code id} is not a letter followed by a 0-4 digit
    * @throws IllegalArgumentException if the {@code cls} is not a valid {@code TargetData} class
    */
-  public Deadeye(String id, Class<T> cls) {
+  public Deadeye(@NotNull String id, @NotNull Class<T> cls) {
     this(id, cls, NetworkTableInstance.getDefault(), null);
   }
 
@@ -78,13 +78,12 @@ public Deadeye(String id, Class<T> cls) {
    * @param linkAddress the IP address the Deadeye daemon should send data to. If null, this client
    *                    will reuse a previously configured address or attempt to automatically
    *                    detect the correct IP address.
-   * @throws NullPointerException     if the {@code cls} is {@code null}
    * @throws IllegalArgumentException if the {@code id} is not a letter followed by a 0-4 digit
    * @throws IllegalArgumentException if the {@code cls} is not a valid {@code TargetData} class
    * @throws IllegalArgumentException if the {@code linkAddress} supplied more than once and does
    *                                  not match address already in use
    */
-  public Deadeye(String id, Class<T> cls, String linkAddress) {
+  public Deadeye(@NotNull String id, @NotNull Class<T> cls, @Nullable String linkAddress) {
     this(id, cls, NetworkTableInstance.getDefault(), linkAddress);
   }
 
@@ -98,11 +97,10 @@ public Deadeye(String id, Class<T> cls, String linkAddress) {
    *            example "A0".
    * @param cls the {@code TargetData} Java class corresponding to the Deadeye pipeline type.
    * @param nti the NetworkTables instance to connect through.
-   * @throws NullPointerException     if the {@code cls} or {@code nti} is {@code null}
    * @throws IllegalArgumentException if the {@code id} is not a letter followed by a 0-4 digit
    * @throws IllegalArgumentException if the {@code cls} is not a valid {@code TargetData} class
    */
-  public Deadeye(String id, Class<T> cls, NetworkTableInstance nti) {
+  public Deadeye(@NotNull String id, @NotNull Class<T> cls, @NotNull NetworkTableInstance nti) {
     this(id, cls, nti, null);
   }
 
@@ -121,14 +119,15 @@ public Deadeye(String id, Class<T> cls, NetworkTableInstance nti) {
    * @param nti         the NetworkTables instance to connect through.
    * @param linkAddress the IP address the Deadeye daemon should send data to. If null, this client
    *                    will attempt to automatically detect the correct IP address.
-   * @throws NullPointerException     if the {@code cls} or {@code nti} is {@code null}
    * @throws IllegalArgumentException if the {@code id} is not a letter followed by a 0-4 digit
    * @throws IllegalArgumentException if the {@code cls} is not a valid {@code TargetData} class
    * @throws IllegalArgumentException if the {@code linkAddress} supplied more than once and does
    *                                  not match address already in use
    */
   @SuppressWarnings("unchecked")
-  public Deadeye(String id, Class<T> cls, NetworkTableInstance nti, String linkAddress) {
+  public Deadeye(
+      @NotNull String id, @NotNull Class<T> cls, @NotNull NetworkTableInstance nti,
+      @Nullable String linkAddress) {
     Objects.requireNonNull(cls, "cls must not be null");
     Objects.requireNonNull(nti, "nti must not be null");
     if (!Pattern.matches("^[A-Za-z][0-4]$", id)) {
@@ -143,6 +142,7 @@ public Deadeye(String id, Class<T> cls, NetworkTableInstance nti, String linkAdd
       }
     }
 
+    Link link = Objects.requireNonNull(Deadeye.link);
     if (linkAddress != null && !link.getAddress().equals(linkAddress)) {
       throw new IllegalArgumentException(
           "supplied linkAddress does not match address already in use");
@@ -191,6 +191,7 @@ static JsonAdapter<Capture> getCaptureJsonAdapter() {
    *
    * @return the associated {@code TargetDataListener}.
    */
+  @NotNull
   public TargetDataListener<T> getTargetDataListener() {
     return targetDataListener;
   }
@@ -201,7 +202,7 @@ public TargetDataListener<T> getTargetDataListener() {
    *
    * @param targetDataListener class to receive target data
    */
-  public void setTargetDataListener(TargetDataListener<T> targetDataListener) {
+  public void setTargetDataListener(@NotNull TargetDataListener<T> targetDataListener) {
     this.targetDataListener = targetDataListener;
   }
 
@@ -215,16 +216,15 @@ public void setTargetDataListener(TargetDataListener<T> targetDataListener) {
    */
   public void handleTargetData(BufferedSource source) throws IOException {
     targetData = jsonAdapter.fromJson(source);
-    if (targetDataListener != null) {
-      targetDataListener.onTargetData(targetData);
-    }
+    targetDataListener.onTargetData(targetData);
   }
 
   /**
    * Gets the most recent {@code TargetData} received by this {@code Deadeye} instance.
    *
    * @return the last valid target data update.
    */
+  @NotNull
   public T getTargetData() {
     return targetData;
   }
@@ -323,7 +323,12 @@ public Capture getCapture() {
     return new Capture();
   }
 
-  Link getLink() {
+  /**
+   * Provide Link for testing.
+   *
+   * @return the {@code Link} or {@code null} if a Deadeye unit has not been initialized yet
+   */
+  @Nullable Link getLink() {
     return link;
   }
 
@@ -356,7 +361,7 @@ public Info(boolean logging, String pipeline, String version) {
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
       if (this == o) {
         return true;
       }
@@ -375,7 +380,7 @@ public int hashCode() {
     }
 
     @Override
-    public String toString() {
+    public @NotNull String toString() {
       return "Info{"
           + "logging="
           + logging
@@ -417,7 +422,9 @@ public static class Capture {
     @Json(name = "h")
     public final int height;
 
-    public Capture() {this("ERROR",0,0,0);}
+    public Capture() {
+      this("ERROR", 0, 0, 0);
+    }
 
     public Capture(String type, int frameRate, int width, int height) {
       this.type = type;
@@ -427,7 +434,7 @@ public Capture(String type, int frameRate, int width, int height) {
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
       if (this == o) {
         return true;
       }
@@ -445,7 +452,7 @@ public int hashCode() {
     }
 
     @Override
-    public String toString() {
+    public @NotNull String toString() {
       return "Capture{" +
           "type='" + type + '\'' +
           ", frameRate=" + frameRate +

client/src/main/java/org/strykeforce/deadeye/DeadeyeJsonAdapter.java

@@ -3,6 +3,7 @@
 import okio.BufferedSource;
 
 import java.io.IOException;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * A {@code TargetData} class implements {@code DeadeyeJsonAdapter} to enable
@@ -17,13 +18,13 @@ public interface DeadeyeJsonAdapter<T extends TargetData> {
    * @return a new {@code TargetData} object, initialized with supplied JSON.
    * @throws IOException if a deserialization error occurs.
    */
-  T fromJson(BufferedSource source) throws IOException;
+  @NotNull T fromJson(@NotNull BufferedSource source) throws IOException;
 
   /**
    * Serializes this {@code TargetData} to JSON.
    * @param targetData the object to serialize.
    * @return this object in JSON format.
    * @throws IOException if a serialization error occurs.
    */
-  String toJson(T targetData) throws IOException;
+  @NotNull String toJson(@NotNull T targetData) throws IOException;
 }

client/src/main/java/org/strykeforce/deadeye/Link.java

@@ -90,7 +90,7 @@ public void run() {
    *
    * @return the configured client address.
    */
-  public String getAddress() {
+  String getAddress() {
     return address;
   }
 

client/src/main/java/org/strykeforce/deadeye/LinkConfig.java

@@ -16,15 +16,16 @@
 import java.util.Objects;
 import java.util.stream.Collectors;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 class LinkConfig {
 
   static final LinkConfig DEFAULT = new LinkConfig("10.27.67.2", 5800, true);
   final int port;
   final boolean enabled;
-  final String address;
+  final @Nullable String address;
 
-  LinkConfig(@NotNull String address, int port, boolean enabled) {
+  LinkConfig(@Nullable String address, int port, boolean enabled) {
     this.address = address;
     this.port = port;
     this.enabled = enabled;
@@ -48,6 +49,7 @@ static LinkConfig getConfig(@NotNull NetworkTable deadeyeTable) {
       Link.logger.warn("more than one entry unsupported, using first:\n\t{}", json);
     }
 
+    // only use first config for now
     var config = configs.get(0);
     if (config.address == null || config.port == 0 || !config.address.equals(
         addressToInetAddress(config.address).getHostAddress())) {
@@ -84,6 +86,7 @@ static List<InetAddress> getSiteLocalAddresses() {
     }
   }
 
+  @NotNull
   static InetAddress addressToInetAddress(String address) {
     InetAddress inetAddress = null;
     var invalid = true;
@@ -110,7 +113,7 @@ static private InetAddress getDefaultInetAddress() {
     }
   }
 
-  LinkConfig withAddress(String address) {
+  @NotNull LinkConfig withAddress(@NotNull String address) {
     return new LinkConfig(address, this.port, this.enabled);
   }
 
@@ -137,7 +140,7 @@ boolean isValid() {
     return addressValid && portValid;
   }
 
-  void save(NetworkTable deadeyeTable) {
+  void save(@NotNull NetworkTable deadeyeTable) {
     JsonAdapter<List<LinkConfig>> jsonAdapter = getConfigJsonAdapter();
     deadeyeTable.getEntry(Link.LINK_ENTRY)
         .setString(jsonAdapter.toJson(Collections.singletonList(this)));
@@ -152,8 +155,9 @@ public boolean equals(Object o) {
     if (o == null || getClass() != o.getClass()) {
       return false;
     }
-    LinkConfig config = (LinkConfig) o;
-    return port == config.port && enabled == config.enabled && address.equals(config.address);
+    LinkConfig that = (LinkConfig) o;
+    return port == that.port && enabled == that.enabled && Objects.equals(address,
+        that.address);
   }
 
   @Override
@@ -162,7 +166,7 @@ public int hashCode() {
   }
 
   @Override
-  public String toString() {
+  public @NotNull String toString() {
     return "LinkConfig{" +
         "port=" + port +
         ", enabled=" + enabled +

client/src/main/java/org/strykeforce/deadeye/MinAreaRectTargetData.java

@@ -8,6 +8,7 @@
 import okio.Buffer;
 import okio.BufferedSource;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * A <code>MinAreaRectTargetData</code> represents data returned from a Deadeye
@@ -89,18 +90,19 @@ public MinAreaRectTargetData(
    *
    * @return the area of the bounding box.
    */
+  @SuppressWarnings("unused")
   public double area() {
     return width * height;
   }
 
   @SuppressWarnings("rawtypes")
   @Override
-  public DeadeyeJsonAdapter getJsonAdapter() {
+  public @NotNull DeadeyeJsonAdapter getJsonAdapter() {
     return new JsonAdapterImpl();
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (this == o) {
       return true;
     }
@@ -126,7 +128,7 @@ public int hashCode() {
   }
 
   @Override
-  public String toString() {
+  public @NotNull String toString() {
     return "MinAreaRectTargetData{"
         + "angle="
         + angle
@@ -161,9 +163,9 @@ private static class JsonAdapterImpl implements DeadeyeJsonAdapter<MinAreaRectTa
     private static final JsonReader.Options OPTIONS = JsonReader.Options.of("id", "sn", "v", "d");
 
     @Override
-    public MinAreaRectTargetData fromJson(BufferedSource source) throws IOException {
+    public @NotNull MinAreaRectTargetData fromJson(@NotNull BufferedSource source) throws IOException {
       JsonReader reader = JsonReader.of(source);
-      String id = null;
+      String id = "Z0";
       int serial = -1;
       boolean valid = false;
       double[] data = new double[DATA_LENGTH];
@@ -208,7 +210,7 @@ public MinAreaRectTargetData fromJson(BufferedSource source) throws IOException
     }
 
     @Override
-    public String toJson(MinAreaRectTargetData targetData) throws IOException {
+    public @NotNull String toJson(@NotNull MinAreaRectTargetData targetData) throws IOException {
       Buffer buffer = new Buffer();
       JsonWriter writer = JsonWriter.of(buffer);
       writer.beginObject();