Reintroduce JSpecify annotations.

JSpecify 1.0.0 has been released, so I'm hoping that
#1362 is no longer a
concern. (If there are remaining concerns, please do let me know.)

This reverts commit 8138f46 (aka
#1364) with a few
changes:

- This commit uses JSpecify 1.0.0 instead of 0.2.0.
- As a result, it uses `org.jspecify.annotations` instead of
  `org.jspecify.nullness`.
- It no longer touches `Structs`, since that was deleted in
  #1501.

Author: cpovirk

google-cloud-logging/pom.xml

@@ -98,6 +98,11 @@
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-core</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+      <version>1.0.0</version>
+    </dependency>
     <dependency>
       <groupId>com.google.errorprone</groupId>
       <artifactId>error_prone_annotations</artifactId>

google-cloud-logging/src/main/java/com/google/cloud/logging/Instrumentation.java

@@ -29,6 +29,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import org.jspecify.annotations.Nullable;
 
 public final class Instrumentation {
   public static final String DIAGNOSTIC_INFO_KEY = "logging.googleapis.com/diagnostic";
@@ -102,7 +103,7 @@ public static Tuple<Boolean, Iterable<LogEntry>> populateInstrumentationInfo(
    * @return The new array of oprions containing WriteOption.OptionType.PARTIAL_SUCCESS flag set to
    *     true
    */
-  public static WriteOption[] addPartialSuccessOption(WriteOption[] options) {
+  public static WriteOption @Nullable [] addPartialSuccessOption(WriteOption[] options) {
     if (options == null) {
       return options;
     }

google-cloud-logging/src/main/java/com/google/cloud/logging/LogDestinationName.java

@@ -21,6 +21,7 @@
 
 import com.google.logging.v2.LogName;
 import java.util.Map;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Class for specifying resource name of the log to which this log entry belongs (see 'logName'
@@ -87,7 +88,7 @@ public static LogDestinationName billingAccount(String id) {
   }
 
   /** Creates a {@code LogEntry} object for given log ID. */
-  public LogName toLogName(String logId) {
+  public @Nullable LogName toLogName(String logId) {
     if (logId == null) {
       return null;
     }
@@ -120,7 +121,7 @@ public DestinationType getDestinationType() {
   }
 
   /** Creates a {@code LogDestinationName} object from given {@code LogName}. */
-  public static LogDestinationName fromLogName(LogName logName) {
+  public static @Nullable LogDestinationName fromLogName(LogName logName) {
     if (logName == null) {
       return null;
     }

google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntry.java

@@ -38,6 +38,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A Cloud Logging log entry. All log entries are represented via objects of this class. Log entries
@@ -368,7 +369,7 @@ public MonitoredResource getResource() {
    * @return timestamp in milliseconds
    */
   @Deprecated
-  public Long getTimestamp() {
+  public @Nullable Long getTimestamp() {
     return timestamp != null ? timestamp.toEpochMilli() : null;
   }
 
@@ -389,7 +390,7 @@ public Instant getInstantTimestamp() {
    * @return timestamp in milliseconds
    */
   @Deprecated
-  public Long getReceiveTimestamp() {
+  public @Nullable Long getReceiveTimestamp() {
     return receiveTimestamp != null ? receiveTimestamp.toEpochMilli() : null;
   }
 
@@ -437,13 +438,13 @@ public Operation getOperation() {
    * Returns the resource name of the trace associated with the log entry, if any. If it contains a
    * relative resource name, the name is assumed to be relative to `//tracing.googleapis.com`.
    */
-  public String getTrace() {
+  public @Nullable String getTrace() {
     // For backwards compatibility return null when trace not set instead of "null".
     return trace == null ? null : trace;
   }
 
   /** Returns the ID of the trace span associated with the log entry, if any. */
-  public String getSpanId() {
+  public @Nullable String getSpanId() {
     // For backwards compatibility return null when spanId not set instead of "null".
     return spanId == null ? null : spanId;
   }

google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingHandler.java

@@ -36,6 +36,7 @@
 import java.util.logging.LogRecord;
 import java.util.logging.Logger;
 import java.util.logging.SimpleFormatter;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A logging handler that outputs logs generated with {@link java.util.logging.Logger} to Cloud
@@ -356,7 +357,7 @@ public void publish(LogRecord record) {
     }
   }
 
-  private MonitoredResource getMonitoredResource() {
+  private @Nullable MonitoredResource getMonitoredResource() {
     Optional<WriteOption> resourceOption =
         stream(defaultWriteOptions)
             .filter(o -> o.getOptionType() == WriteOption.OptionType.RESOURCE)

google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java

@@ -100,6 +100,7 @@
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
+import org.jspecify.annotations.Nullable;
 
 class LoggingImpl extends BaseService<LoggingOptions> implements Logging {
   protected static final String RESOURCE_NAME_FORMAT = "projects/%s/traces/%s";
@@ -792,7 +793,7 @@ private static WriteLogEntriesRequest writeLogEntriesRequest(
     return builder.build();
   }
 
-  private static LogName getLogName(
+  private static @Nullable LogName getLogName(
       String projectId, String logName, LogDestinationName destination) {
     if (logName == null) {
       return null;
@@ -932,7 +933,7 @@ public void flush() {
    * @param resource A {@see MonitoredResource} describing environment metadata.
    * @return A formatted trace id string.
    */
-  private String getFormattedTrace(String traceId, MonitoredResource resource) {
+  private @Nullable String getFormattedTrace(String traceId, MonitoredResource resource) {
     if (traceId == null) {
       return null;
     }

google-cloud-logging/src/main/java/com/google/cloud/logging/MetadataLoader.java

@@ -24,6 +24,7 @@
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.function.Supplier;
+import org.jspecify.annotations.Nullable;
 
 public final class MetadataLoader {
   public static final String ENV_FLEXIBLE = "flex";
@@ -67,7 +68,7 @@ public MetadataLoader(ResourceTypeEnvironmentGetter getter) {
    * @param label A resource metadata label of type {@see MonitoredResourceUtil.Label}
    * @return A string with metadata value or {@code null} if the label is not supported.
    */
-  public String getValue(MonitoredResourceUtil.Label label) {
+  public @Nullable String getValue(MonitoredResourceUtil.Label label) {
     Supplier<String> lambda = labelResolvers.get(label);
     if (lambda != null) {
       return lambda.get();
@@ -198,7 +199,7 @@ private String getProjectId() {
    *
    * @return region string id
    */
-  private String getRegion() {
+  private @Nullable String getRegion() {
     String loc = getter.getAttribute("instance/region");
     if (loc != null) {
       return loc.substring(loc.lastIndexOf('/') + 1);
@@ -223,7 +224,7 @@ private String getVersionId() {
    *
    * @return zone string id
    */
-  private String getZone() {
+  private @Nullable String getZone() {
     String loc = getter.getAttribute("instance/zone");
     if (loc != null) {
       return loc.substring(loc.lastIndexOf('/') + 1);

google-cloud-logging/src/main/java/com/google/cloud/logging/ResourceTypeEnvironmentGetterImpl.java

@@ -17,11 +17,12 @@
 package com.google.cloud.logging;
 
 import com.google.cloud.MetadataConfig;
+import org.jspecify.annotations.Nullable;
 
 final class ResourceTypeEnvironmentGetterImpl implements ResourceTypeEnvironmentGetter {
 
   @Override
-  public String getEnv(String name) {
+  public @Nullable String getEnv(String name) {
     // handle exception thrown if a security manager exists and blocks access to the
     // process environment
     try {

google-cloud-logging/src/main/java/com/google/cloud/logging/SinkInfo.java

@@ -25,6 +25,7 @@
 import java.util.Objects;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Cloud Logging sinks can be used to control the export of your logs. Each sink specifies the
@@ -477,7 +478,7 @@ LogSink.VersionFormat toPb() {
       return versionPb;
     }
 
-    static VersionFormat fromPb(LogSink.VersionFormat versionPb) {
+    static @Nullable VersionFormat fromPb(LogSink.VersionFormat versionPb) {
       switch (versionPb) {
         case V1:
           return VersionFormat.V1;

google-cloud-logging/src/main/java/com/google/cloud/logging/SourceLocation.java

@@ -24,6 +24,7 @@
 import com.google.logging.v2.LogEntrySourceLocation;
 import java.io.Serializable;
 import java.util.Objects;
+import org.jspecify.annotations.Nullable;
 
 /** Additional information about the source code location that produced the log entry. */
 public final class SourceLocation implements Serializable {
@@ -173,7 +174,7 @@ static SourceLocation fromPb(LogEntrySourceLocation sourceLocationPb) {
    * @return a new instance of {@link SourceLocation} populated with file name, method and line
    *     number information.
    */
-  static SourceLocation fromCurrentContext(String... exclusionClassPaths) {
+  static @Nullable SourceLocation fromCurrentContext(String... exclusionClassPaths) {
     StackTraceElement[] stackTrace = new Exception().getStackTrace();
 
     for (int level = 1; level < stackTrace.length; level++) {