Add JSpecify annotations to commons module.

Signed-off-by: Eric Bottard <[email protected]>

Author: ericbottard

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/vectorstore/SimplePersistentVectorStoreIT.java

@@ -72,7 +72,7 @@ void persist() {
 
 	}
 
-	public class ProductMetadataGenerator implements JsonMetadataGenerator {
+	public static class ProductMetadataGenerator implements JsonMetadataGenerator {
 
 		@Override
 		public Map<String, Object> generate(Map<String, Object> jsonMap) {

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/evaluation/FactCheckingEvaluator.java

@@ -18,11 +18,12 @@
 
 import java.util.Collections;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.evaluation.EvaluationRequest;
 import org.springframework.ai.evaluation.EvaluationResponse;
 import org.springframework.ai.evaluation.Evaluator;
-import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -148,9 +149,9 @@ public static FactCheckingEvaluator.Builder builder(ChatClient.Builder chatClien
 
 	public static final class Builder {
 
-		private ChatClient.Builder chatClientBuilder;
+		private ChatClient.@Nullable Builder chatClientBuilder;
 
-		private String evaluationPrompt;
+		private @Nullable String evaluationPrompt = DEFAULT_EVALUATION_PROMPT_TEXT;
 
 		private Builder() {
 		}
@@ -166,6 +167,8 @@ public FactCheckingEvaluator.Builder evaluationPrompt(String evaluationPrompt) {
 		}
 
 		public FactCheckingEvaluator build() {
+			Assert.state(this.chatClientBuilder != null, "ChatClientBuilder cannot be null");
+			Assert.state(this.evaluationPrompt != null, "EvaluationPrompt cannot be null");
 			return new FactCheckingEvaluator(this.chatClientBuilder, this.evaluationPrompt);
 		}
 

spring-ai-client-chat/src/main/java/org/springframework/ai/chat/evaluation/RelevancyEvaluator.java

@@ -19,12 +19,13 @@
 import java.util.Collections;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.prompt.PromptTemplate;
 import org.springframework.ai.evaluation.EvaluationRequest;
 import org.springframework.ai.evaluation.EvaluationResponse;
 import org.springframework.ai.evaluation.Evaluator;
-import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -93,9 +94,9 @@ public static Builder builder() {
 
 	public static final class Builder {
 
-		private ChatClient.Builder chatClientBuilder;
+		private ChatClient.@Nullable Builder chatClientBuilder;
 
-		private PromptTemplate promptTemplate;
+		private @Nullable PromptTemplate promptTemplate;
 
 		private Builder() {
 		}
@@ -111,6 +112,7 @@ public Builder promptTemplate(PromptTemplate promptTemplate) {
 		}
 
 		public RelevancyEvaluator build() {
+			Assert.state(this.chatClientBuilder != null, "chatClientBuilder cannot be null");
 			return new RelevancyEvaluator(this.chatClientBuilder, this.promptTemplate);
 		}
 

…pringframework/ai/chat/package-info.java …ork/ai/chat/evaluation/package-info.javaspring-ai-client-chat/src/main/java/org/springframework/ai/chat/package-info.java renamed to spring-ai-client-chat/src/main/java/org/springframework/ai/chat/evaluation/package-info.java spring-ai-client-chat/src/main/java/org/springframework/ai/chat/package-info.java renamed to spring-ai-client-chat/src/main/java/org/springframework/ai/chat/evaluation/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,4 +28,7 @@
  * functionalities, maintaining a clear boundary from other contexts within the AI domain.
  */
 
-package org.springframework.ai.chat;
+@NullMarked
+package org.springframework.ai.chat.evaluation;
+
+import org.jspecify.annotations.NullMarked;

spring-ai-client-chat/src/test/java/org/springframework/ai/chat/evaluation/FactCheckingEvaluatorTests.java

@@ -36,21 +36,15 @@ class FactCheckingEvaluatorTests {
 	@SuppressWarnings("deprecation")
 	@Test
 	void whenChatClientBuilderIsNullThenThrow() {
-		assertThatThrownBy(() -> new FactCheckingEvaluator(null, null)).isInstanceOf(IllegalArgumentException.class)
-			.hasMessageContaining("chatClientBuilder cannot be null");
-
-		assertThatThrownBy(() -> FactCheckingEvaluator.builder(null).build())
-			.isInstanceOf(IllegalArgumentException.class)
-			.hasMessageContaining("chatClientBuilder cannot be null");
+		assertThatThrownBy(() -> FactCheckingEvaluator.builder(null).build()).isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("ChatClientBuilder cannot be null");
 	}
 
 	@SuppressWarnings("deprecation")
 	@Test
 	void whenEvaluationPromptIsNullThenUseDefaultEvaluationPromptText() {
-		FactCheckingEvaluator evaluator = new FactCheckingEvaluator(ChatClient.builder(mock(ChatModel.class)), null);
-		assertThat(evaluator).isNotNull();
-
-		evaluator = FactCheckingEvaluator.builder(ChatClient.builder(mock(ChatModel.class))).build();
+		FactCheckingEvaluator evaluator = FactCheckingEvaluator.builder(ChatClient.builder(mock(ChatModel.class)))
+			.build();
 		assertThat(evaluator).isNotNull();
 	}
 

spring-ai-client-chat/src/test/java/org/springframework/ai/chat/evaluation/RelevancyEvaluatorTests.java

@@ -38,7 +38,7 @@ void whenChatClientBuilderIsNullThenThrow() {
 			.hasMessageContaining("chatClientBuilder cannot be null");
 
 		assertThatThrownBy(() -> RelevancyEvaluator.builder().chatClientBuilder(null).build())
-			.isInstanceOf(IllegalArgumentException.class)
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessageContaining("chatClientBuilder cannot be null");
 	}
 

spring-ai-commons/src/main/java/org/springframework/ai/content/Content.java

@@ -18,6 +18,8 @@
 
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Data structure that contains content and metadata. Common parent for the
  * {@link org.springframework.ai.document.Document} and the
@@ -33,7 +35,7 @@ public interface Content {
 	 * Get the content of the message.
 	 * @return the content of the message
 	 */
-	String getText();
+	@Nullable String getText();
 
 	/**
 	 * Get the metadata associated with the content.

spring-ai-commons/src/main/java/org/springframework/ai/content/Media.java

@@ -19,8 +19,9 @@
 import java.io.IOException;
 import java.net.URI;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.core.io.Resource;
-import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.MimeType;
 
@@ -75,8 +76,7 @@ public class Media {
 	 * An Id of the media object, usually defined when the model returns a reference to
 	 * media it has been passed.
 	 */
-	@Nullable
-	private final String id;
+	private final @Nullable String id;
 
 	private final MimeType mimeType;
 
@@ -195,8 +195,7 @@ public byte[] getDataAsByteArray() {
 	 * Get the media id
 	 * @return the media id
 	 */
-	@Nullable
-	public String getId() {
+	public @Nullable String getId() {
 		return this.id;
 	}
 
@@ -209,13 +208,13 @@ public String getName() {
 	 */
 	public static final class Builder {
 
-		private String id;
+		private @Nullable String id;
 
-		private MimeType mimeType;
+		private @Nullable MimeType mimeType;
 
-		private Object data;
+		private @Nullable Object data;
 
-		private String name;
+		private @Nullable String name;
 
 		private Builder() {
 		}
@@ -315,6 +314,8 @@ public Builder name(String name) {
 		 * @throws IllegalArgumentException if mimeType or data are null
 		 */
 		public Media build() {
+			Assert.state(this.mimeType != null, "MimeType must not be null");
+			Assert.state(this.data != null, "Data must not be null");
 			return new Media(this.mimeType, this.data, this.id, this.name);
 		}
 

spring-ai-commons/src/main/java/org/springframework/ai/content/package-info.java

@@ -17,4 +17,7 @@
 /**
  * Core observation abstractions.
  */
+@NullMarked
 package org.springframework.ai.content;
+
+import org.jspecify.annotations.NullMarked;

spring-ai-commons/src/main/java/org/springframework/ai/document/DefaultContentFormatter.java

@@ -111,8 +111,9 @@ public String format(Document document, MetadataMode metadataMode) {
 				.replace(TEMPLATE_VALUE_PLACEHOLDER, metadataEntry.getValue().toString()))
 			.collect(Collectors.joining(this.metadataSeparator));
 
+		var text = document.getText() != null ? document.getText() : "";
 		return this.textTemplate.replace(TEMPLATE_METADATA_STRING_PLACEHOLDER, metadataText)
-			.replace(TEMPLATE_CONTENT_PLACEHOLDER, document.getText());
+			.replace(TEMPLATE_CONTENT_PLACEHOLDER, text);
 	}
 
 	/**