refactor: declare org.testng.xml null-marked

testng-core-api/src/main/java/org/testng/xml/DefaultXmlWeaver.java

@@ -16,6 +16,7 @@
 import java.util.Map;
 import java.util.Properties;
 import javax.xml.XMLConstants;
+import org.jspecify.annotations.Nullable;
 import org.testng.TestNGException;
 import org.testng.internal.Utils;
 import org.testng.reporters.XMLStringBuffer;
@@ -80,7 +81,7 @@ public class DefaultXmlWeaver implements IWeaveXml {
   /** Immutable, so a single instance can serve every {@code asXmlFragment} call. */
   private static final DefaultXmlWeaver LEGACY_FRAGMENT_WEAVER = new DefaultXmlWeaver();
 
-  private final String defaultComment;
+  private final @Nullable String defaultComment;
 
   /** Writes the name of each named tag as a trailing XML comment, as TestNG always has. */
   public DefaultXmlWeaver() {
@@ -92,7 +93,7 @@ public DefaultXmlWeaver() {
    *     tag's own {@code name} attribute. Pass the empty string to write no comment at all, which
    *     is what {@link CommentDisabledXmlWeaver} does.
    */
-  protected DefaultXmlWeaver(String defaultComment) {
+  protected DefaultXmlWeaver(@Nullable String defaultComment) {
     this.defaultComment = defaultComment;
   }
 

testng-core-api/src/main/java/org/testng/xml/XmlClass.java

@@ -4,6 +4,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import org.jspecify.annotations.Nullable;
 import org.testng.TestNGException;
 import org.testng.collections.Objects;
 import org.testng.internal.ClassHelper;
@@ -13,22 +14,24 @@ public class XmlClass implements Cloneable {
 
   private List<XmlInclude> m_includedMethods = new ArrayList<>();
   private List<String> m_excludedMethods = new ArrayList<>();
-  private String m_name = null;
-  private Class m_class = null;
+  // Assigned by init, which every constructor calls directly: NullAway traces an initializer
+  // helper one hop only, so reaching init through a delegating overload stops it seeing this.
+  private String m_name;
+  private @Nullable Class m_class;
   /** The index of this class in the &lt;test&gt; tag */
   private int m_index;
   /** True if the classes need to be loaded */
   private boolean m_loadClasses = true;
 
   private Map<String, String> m_parameters = new HashMap<>();
-  private XmlTest m_xmlTest;
+  private @Nullable XmlTest m_xmlTest;
 
   public XmlClass() {
     init("", null, 0, false /* load classes */);
   }
 
   public XmlClass(String name) {
-    init(name, null, 0);
+    init(name, null, 0, true /* load classes */);
   }
 
   public XmlClass(String name, boolean loadClasses) {
@@ -51,11 +54,7 @@ public XmlClass(String className, int index, boolean loadClasses) {
     init(className, null, index, loadClasses);
   }
 
-  private void init(String className, Class cls, int index) {
-    init(className, cls, index, true /* load classes */);
-  }
-
-  private void init(String className, Class cls, int index, boolean resolveClass) {
+  private void init(String className, @Nullable Class cls, int index, boolean resolveClass) {
     m_name = className;
     m_class = cls;
     m_index = index;
@@ -65,20 +64,21 @@ private void init(String className, Class cls, int index, boolean resolveClass)
     }
   }
 
-  private void loadClass() {
-    m_class = ClassHelper.forName(m_name);
+  /** Resolves {@link #m_name}, caches it in {@link #m_class} and hands it back. */
+  private Class<?> loadClass() {
+    Class<?> cls = ClassHelper.forName(m_name);
 
-    if (null == m_class) {
+    if (null == cls) {
       throw new TestNGException("Cannot find class in classpath: " + m_name);
     }
+    m_class = cls;
+    return cls;
   }
 
   /** @return Returns the className. */
   public Class<?> getSupportClass() {
-    if (m_class == null) {
-      loadClass();
-    }
-    return m_class;
+    Class<?> cls = m_class;
+    return cls == null ? loadClass() : cls;
   }
 
   /** @param className The className to set. */

testng-core-api/src/main/java/org/testng/xml/XmlDefine.java

@@ -2,16 +2,17 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import org.jspecify.annotations.Nullable;
 
 public class XmlDefine {
 
-  private String m_name;
+  private @Nullable String m_name;
 
-  public void setName(String name) {
+  public void setName(@Nullable String name) {
     m_name = name;
   }
 
-  public String getName() {
+  public @Nullable String getName() {
     return m_name;
   }
 

testng-core-api/src/main/java/org/testng/xml/XmlGroups.java

@@ -2,11 +2,12 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import org.jspecify.annotations.Nullable;
 
 public class XmlGroups {
 
   private List<XmlDefine> m_defines = new ArrayList<>();
-  private XmlRun m_run;
+  private @Nullable XmlRun m_run;
   private List<XmlDependencies> m_dependencies = new ArrayList<>();
 
   public List<XmlDefine> getDefines() {
@@ -21,11 +22,15 @@ public void setDefines(List<XmlDefine> defines) {
     m_defines = defines;
   }
 
-  public XmlRun getRun() {
+  /**
+   * @return the {@code <run>} element, or {@code null} when none has been set. A {@code <groups>}
+   *     can legitimately carry only {@code <define>} or {@code <dependencies>} elements.
+   */
+  public @Nullable XmlRun getRun() {
     return m_run;
   }
 
-  public void setRun(XmlRun run) {
+  public void setRun(@Nullable XmlRun run) {
     m_run = run;
   }
 

testng-core-api/src/main/java/org/testng/xml/XmlInclude.java

@@ -7,6 +7,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeSet;
+import org.jspecify.annotations.Nullable;
 
 public class XmlInclude {
 
@@ -17,10 +18,10 @@ public class XmlInclude {
   // out as "17 1". The generated suite should not depend on that.
   private final Set<Integer> m_factoryInstances = new TreeSet<>();
   private final int m_index;
-  private String m_description;
+  private @Nullable String m_description;
   private final Map<String, String> m_parameters = new HashMap<>();
 
-  private XmlClass m_xmlClass;
+  private @Nullable XmlClass m_xmlClass;
 
   public XmlInclude() {
     this("", 0);
@@ -40,7 +41,7 @@ public XmlInclude(String n, List<Integer> list, int index) {
     m_index = index;
   }
 
-  public void setDescription(String description) {
+  public void setDescription(@Nullable String description) {
     m_description = description;
   }
 
@@ -49,7 +50,7 @@ public void setParameters(Map<String, String> parameters) {
     m_parameters.putAll(parameters);
   }
 
-  public String getDescription() {
+  public @Nullable String getDescription() {
     return m_description;
   }
 

testng-core-api/src/main/java/org/testng/xml/XmlMethodSelector.java

@@ -1,24 +1,26 @@
 package org.testng.xml;
 
+import org.jspecify.annotations.Nullable;
+
 /** This class describes the tag <code>&lt;method-selector&gt;</code> in testng.xml. */
 public class XmlMethodSelector {
 
   /** The priority assumed when the {@code priority} attribute is absent from the suite file. */
   public static final int DEFAULT_PRIORITY = 0;
 
   // Either this:
-  private String m_className;
+  private @Nullable String m_className;
   private int m_priority = DEFAULT_PRIORITY;
 
   // Or that:
-  private XmlScript m_script;
+  private @Nullable XmlScript m_script;
 
   // For YAML
-  public void setClassName(String s) {
+  public void setClassName(@Nullable String s) {
     m_className = s;
   }
 
-  public String getClassName() {
+  public @Nullable String getClassName() {
     return m_className;
   }
 
@@ -32,11 +34,11 @@ public void setName(String name) {
     m_className = name;
   }
 
-  public XmlScript getScript() {
+  public @Nullable XmlScript getScript() {
     return m_script;
   }
 
-  public void setScript(XmlScript script) {
+  public void setScript(@Nullable XmlScript script) {
     m_script = script;
   }
 

testng-core-api/src/main/java/org/testng/xml/XmlPackage.java

@@ -3,17 +3,18 @@
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
+import org.jspecify.annotations.Nullable;
 import org.testng.internal.PackageUtils;
 import org.testng.internal.Utils;
 import org.testng.internal.protocols.UnhandledIOException;
 
 /** This class describes the tag <code>&lt;package&gt;</code> in testng.xml. */
 public class XmlPackage {
 
-  private String m_name;
+  private @Nullable String m_name;
   private List<String> m_include = new ArrayList<>();
   private List<String> m_exclude = new ArrayList<>();
-  private List<XmlClass> m_xmlClasses = null;
+  private @Nullable List<XmlClass> m_xmlClasses;
 
   public XmlPackage() {}
 
@@ -43,21 +44,23 @@ public void setInclude(List<String> include) {
   }
 
   /** @return the name */
-  public String getName() {
+  public @Nullable String getName() {
     return m_name;
   }
 
   /** @param name the name to set */
-  public void setName(String name) {
+  public void setName(@Nullable String name) {
     m_name = name;
   }
 
   public List<XmlClass> getXmlClasses() {
-    if (null == m_xmlClasses) {
-      m_xmlClasses = initializeXmlClasses();
+    List<XmlClass> xmlClasses = m_xmlClasses;
+    if (null == xmlClasses) {
+      xmlClasses = initializeXmlClasses();
+      m_xmlClasses = xmlClasses;
     }
 
-    return m_xmlClasses;
+    return xmlClasses;
   }
 
   private List<XmlClass> initializeXmlClasses() {

testng-core-api/src/main/java/org/testng/xml/XmlScript.java

@@ -1,23 +1,25 @@
 package org.testng.xml;
 
+import org.jspecify.annotations.Nullable;
+
 public class XmlScript {
 
-  private String language;
-  private String expression;
+  private @Nullable String language;
+  private @Nullable String expression;
 
-  public void setLanguage(String language) {
+  public void setLanguage(@Nullable String language) {
     this.language = language;
   }
 
-  public void setExpression(String expression) {
+  public void setExpression(@Nullable String expression) {
     this.expression = expression;
   }
 
-  public String getExpression() {
+  public @Nullable String getExpression() {
     return expression;
   }
 
-  public String getLanguage() {
+  public @Nullable String getLanguage() {
     return language;
   }
 }