mark nullable

neowu · neowu · commit b30bed0e091e · 2025-12-01T14:38:59.000+08:00
Signed-off-by: neo &lt;1100909+neowu@users.noreply.github.com&gt;
diff --git a/core-ng/src/main/java/core/framework/internal/validate/Validator.java b/core-ng/src/main/java/core/framework/internal/validate/Validator.java
@@ -35,14 +35,14 @@ private Validator(Class<T> beanClass) {
         this.validator = builder.build();
     }
 
-    public void validate(T bean, boolean partial) {
+    public void validate(@Nullable T bean, boolean partial) {
         Map<String, String> errors = errors(bean, partial);
         if (errors != null) throw new ValidationException(errors);
     }
 
     // used only internally, for places don't want to catch exception
     @Nullable
-    public Map<String, String> errors(T bean, boolean partial) {
+    public Map<String, String> errors(@Nullable T bean, boolean partial) {
         if (bean == null) {
             return Map.of("bean", "bean must not be null");
         }
diff --git a/core-ng/src/main/java/core/framework/internal/web/bean/QueryParamHelper.java b/core-ng/src/main/java/core/framework/internal/web/bean/QueryParamHelper.java
@@ -3,6 +3,7 @@
 import core.framework.internal.web.service.PathParamHelper;
 import core.framework.json.JSON;
 import core.framework.web.exception.BadRequestException;
+import org.jspecify.annotations.Nullable;
 
 import java.math.BigDecimal;
 import java.time.LocalDate;
@@ -16,57 +17,68 @@
  * @author neo
  */
 final class QueryParamHelper {   // used by generated QueryParamMapper
-    public static String toString(Number value) {
+    @Nullable
+    public static String toString(@Nullable Number value) {
         if (value == null) return null;
         return value.toString();
     }
 
-    public static String toString(Boolean value) {
+    @Nullable
+    public static String toString(@Nullable Boolean value) {
         if (value == null) return null;
         return value.toString();
     }
 
-    public static String toString(LocalDateTime dateTime) {
+    @Nullable
+    public static String toString(@Nullable LocalDateTime dateTime) {
         if (dateTime == null) return null;
         return DateTimeFormatter.ISO_LOCAL_DATE_TIME.format(dateTime);
     }
 
-    public static String toString(LocalDate date) {
+    @Nullable
+    public static String toString(@Nullable LocalDate date) {
         if (date == null) return null;
         return DateTimeFormatter.ISO_LOCAL_DATE.format(date);
     }
 
-    public static String toString(LocalTime time) {
+    @Nullable
+    public static String toString(@Nullable LocalTime time) {
         if (time == null) return null;
         return DateTimeFormatter.ISO_LOCAL_TIME.format(time);
     }
 
-    public static String toString(ZonedDateTime dateTime) {
+    @Nullable
+    public static String toString(@Nullable ZonedDateTime dateTime) {
         if (dateTime == null) return null;
         return DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(dateTime);
     }
 
-    public static <T extends Enum<?>> String toString(T enumValue) {
+    @Nullable
+    public static <T extends Enum<?>> String toString(@Nullable T enumValue) {
         if (enumValue == null) return null;
         return JSON.toEnumValue(enumValue);
     }
 
     // deserialization helpers
+    @Nullable
     public static String toString(String value) {
         if (value.isEmpty()) return null;
         return value;
     }
 
+    @Nullable
     public static Integer toInt(String value) {
         if (value.isEmpty()) return null;
         return PathParamHelper.toInt(value);
     }
 
+    @Nullable
     public static Long toLong(String value) {
         if (value.isEmpty()) return null;
         return PathParamHelper.toLong(value);
     }
 
+    @Nullable
     public static Double toDouble(String value) {
         if (value.isEmpty()) return null;
         try {
@@ -76,6 +88,7 @@ public static Double toDouble(String value) {
         }
     }
 
+    @Nullable
     public static BigDecimal toBigDecimal(String value) {
         if (value.isEmpty()) return null;
         try {
@@ -85,16 +98,19 @@ public static BigDecimal toBigDecimal(String value) {
         }
     }
 
+    @Nullable
     public static Boolean toBoolean(String value) {
         if (value.isEmpty()) return null;
         return Boolean.valueOf(value);  // Boolean.parseBoolean does not throw exception
     }
 
+    @Nullable
     public static <T extends Enum<?>> T toEnum(String value, Class<T> valueClass) {
         if (value.isEmpty()) return null;
         return PathParamHelper.toEnum(value, valueClass);
     }
 
+    @Nullable
     public static ZonedDateTime toZonedDateTime(String value) {
         if (value.isEmpty()) return null;
         try {
@@ -104,6 +120,7 @@ public static ZonedDateTime toZonedDateTime(String value) {
         }
     }
 
+    @Nullable
     public static LocalDateTime toDateTime(String value) {
         if (value.isEmpty()) return null;
         try {
@@ -113,6 +130,7 @@ public static LocalDateTime toDateTime(String value) {
         }
     }
 
+    @Nullable
     public static LocalTime toTime(String value) {
         if (value.isEmpty()) return null;
         try {
@@ -122,6 +140,7 @@ public static LocalTime toTime(String value) {
         }
     }
 
+    @Nullable
     public static LocalDate toDate(String value) {
         if (value.isEmpty()) return null;
         try {
diff --git a/core-ng/src/main/java/core/framework/internal/web/bean/ResponseBeanReader.java b/core-ng/src/main/java/core/framework/internal/web/bean/ResponseBeanReader.java
@@ -7,6 +7,7 @@
 import core.framework.internal.validate.Validator;
 import core.framework.internal.web.service.InternalErrorResponse;
 import core.framework.util.Maps;
+import org.jspecify.annotations.Nullable;
 
 import java.io.IOException;
 import java.lang.reflect.Type;
@@ -36,6 +37,7 @@ public void register(Type responseType, BeanClassValidator validator) {
         }
     }
 
+    @Nullable
     public Object fromJSON(Type responseType, byte[] body) throws IOException {
         if (void.class == responseType) return null;
 
diff --git a/core-ng/src/main/java/core/framework/internal/web/bean/package-info.java b/core-ng/src/main/java/core/framework/internal/web/bean/package-info.java
@@ -0,0 +1,4 @@
+@NullMarked
+package core.framework.internal.web.bean;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core-ng/src/main/java/core/framework/internal/web/service/InternalErrorResponse.java b/core-ng/src/main/java/core/framework/internal/web/service/InternalErrorResponse.java
@@ -1,17 +1,20 @@
 package core.framework.internal.web.service;
 
 import core.framework.api.json.Property;
+import org.jspecify.annotations.Nullable;
 
 /**
  * @author neo
  */
 public class InternalErrorResponse {    // keep compatible with ErrorResponse with additional severity/stackTrace fields
+    @Nullable
     @Property(name = "id")
     public String id;
 
     @Property(name = "severity")
     public String severity;
 
+    @Nullable
     @Property(name = "errorCode")
     public String errorCode;
 
diff --git a/core-ng/src/main/java/core/framework/internal/web/service/WebServiceClient.java b/core-ng/src/main/java/core/framework/internal/web/service/WebServiceClient.java
@@ -17,6 +17,7 @@
 import core.framework.util.Maps;
 import core.framework.web.service.RemoteServiceException;
 import core.framework.web.service.WebServiceClientInterceptor;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -51,6 +52,7 @@ static HTTPStatus parseHTTPStatus(int statusCode) {
     private final HTTPClient httpClient;
     private final RequestBeanWriter writer;
     private final ResponseBeanReader reader;
+    @Nullable
     private WebServiceClientInterceptor interceptor;
 
     public WebServiceClient(String serviceURL, HTTPClient httpClient, RequestBeanWriter writer, ResponseBeanReader reader) {
@@ -61,7 +63,8 @@ public WebServiceClient(String serviceURL, HTTPClient httpClient, RequestBeanWri
     }
 
     // used by generated code, must be public
-    public <T> Object execute(HTTPMethod method, String path, Class<T> requestBeanClass, T requestBean, Type responseType) {
+    @Nullable
+    public <T> Object execute(HTTPMethod method, String path, @Nullable Class<T> requestBeanClass, T requestBean, Type responseType) {
         var request = new HTTPRequest(method, serviceURL + path);
         request.accept(ContentType.APPLICATION_JSON);
         linkContext(request);
@@ -155,7 +158,7 @@ private InternalErrorResponse errorResponse(HTTPResponse response) {
         }
     }
 
-    private Severity parseSeverity(String severity) {
+    private Severity parseSeverity(@Nullable String severity) {
         if (severity == null) return Severity.ERROR;
         return Severity.valueOf(severity);
     }
diff --git a/core-ng/src/main/java/core/framework/internal/web/service/WebServiceInterfaceValidator.java b/core-ng/src/main/java/core/framework/internal/web/service/WebServiceInterfaceValidator.java
@@ -21,6 +21,7 @@
 import core.framework.util.Maps;
 import core.framework.util.Sets;
 import core.framework.util.Strings;
+import org.jspecify.annotations.Nullable;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
@@ -37,9 +38,13 @@
 public class WebServiceInterfaceValidator {
     private final Class<?> serviceInterface;
     private final BeanClassValidator validator;
+    @Nullable
     public RequestBeanReader requestBeanReader;
+    @Nullable
     public RequestBeanWriter requestBeanWriter;
+    @Nullable
     public ResponseBeanReader responseBeanReader;
+    @Nullable
     public ResponseBeanWriter responseBeanWriter;
 
     public WebServiceInterfaceValidator(Class<?> serviceInterface, BeanClassValidator validator) {
diff --git a/core-ng/src/main/java/core/framework/internal/web/service/package-info.java b/core-ng/src/main/java/core/framework/internal/web/service/package-info.java
@@ -0,0 +1,4 @@
+@NullMarked
+package core.framework.internal.web.service;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core-ng/src/main/java/core/framework/log/message/package-info.java b/core-ng/src/main/java/core/framework/log/message/package-info.java
@@ -0,0 +1,4 @@
+@NullMarked
+package core.framework.log.message;
+
+import org.jspecify.annotations.NullMarked;

Original file line number	Diff line number	Diff line change
`@@ -35,14 +35,14 @@ private Validator(Class<T> beanClass) {`
`35`	`35`	`this.validator = builder.build();`
`36`	`36`	`}`
`37`	`37`
`38`		`- public void validate(T bean, boolean partial) {`
	`38`	`+ public void validate(@Nullable T bean, boolean partial) {`
`39`	`39`	`Map<String, String> errors = errors(bean, partial);`
`40`	`40`	`if (errors != null) throw new ValidationException(errors);`
`41`	`41`	`}`
`42`	`42`
`43`	`43`	`// used only internally, for places don't want to catch exception`
`44`	`44`	`@Nullable`
`45`		`- public Map<String, String> errors(T bean, boolean partial) {`
	`45`	`+ public Map<String, String> errors(@Nullable T bean, boolean partial) {`
`46`	`46`	`if (bean == null) {`
`47`	`47`	`return Map.of("bean", "bean must not be null");`
`48`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`	`import core.framework.internal.web.service.PathParamHelper;`
`4`	`4`	`import core.framework.json.JSON;`
`5`	`5`	`import core.framework.web.exception.BadRequestException;`
	`6`	`+import org.jspecify.annotations.Nullable;`
`6`	`7`
`7`	`8`	`import java.math.BigDecimal;`
`8`	`9`	`import java.time.LocalDate;`
`@@ -16,57 +17,68 @@`
`16`	`17`	`* @author neo`
`17`	`18`	`*/`
`18`	`19`	`final class QueryParamHelper { // used by generated QueryParamMapper`
`19`		`- public static String toString(Number value) {`
	`20`	`+ @Nullable`
	`21`	`+ public static String toString(@Nullable Number value) {`
`20`	`22`	`if (value == null) return null;`
`21`	`23`	`return value.toString();`
`22`	`24`	`}`
`23`	`25`
`24`		`- public static String toString(Boolean value) {`
	`26`	`+ @Nullable`
	`27`	`+ public static String toString(@Nullable Boolean value) {`
`25`	`28`	`if (value == null) return null;`
`26`	`29`	`return value.toString();`
`27`	`30`	`}`
`28`	`31`
`29`		`- public static String toString(LocalDateTime dateTime) {`
	`32`	`+ @Nullable`
	`33`	`+ public static String toString(@Nullable LocalDateTime dateTime) {`
`30`	`34`	`if (dateTime == null) return null;`
`31`	`35`	`return DateTimeFormatter.ISO_LOCAL_DATE_TIME.format(dateTime);`
`32`	`36`	`}`
`33`	`37`
`34`		`- public static String toString(LocalDate date) {`
	`38`	`+ @Nullable`
	`39`	`+ public static String toString(@Nullable LocalDate date) {`
`35`	`40`	`if (date == null) return null;`
`36`	`41`	`return DateTimeFormatter.ISO_LOCAL_DATE.format(date);`
`37`	`42`	`}`
`38`	`43`
`39`		`- public static String toString(LocalTime time) {`
	`44`	`+ @Nullable`
	`45`	`+ public static String toString(@Nullable LocalTime time) {`
`40`	`46`	`if (time == null) return null;`
`41`	`47`	`return DateTimeFormatter.ISO_LOCAL_TIME.format(time);`
`42`	`48`	`}`
`43`	`49`
`44`		`- public static String toString(ZonedDateTime dateTime) {`
	`50`	`+ @Nullable`
	`51`	`+ public static String toString(@Nullable ZonedDateTime dateTime) {`
`45`	`52`	`if (dateTime == null) return null;`
`46`	`53`	`return DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(dateTime);`
`47`	`54`	`}`
`48`	`55`
`49`		`- public static <T extends Enum<?>> String toString(T enumValue) {`
	`56`	`+ @Nullable`
	`57`	`+ public static <T extends Enum<?>> String toString(@Nullable T enumValue) {`
`50`	`58`	`if (enumValue == null) return null;`
`51`	`59`	`return JSON.toEnumValue(enumValue);`
`52`	`60`	`}`
`53`	`61`
`54`	`62`	`// deserialization helpers`
	`63`	`+ @Nullable`
`55`	`64`	`public static String toString(String value) {`
`56`	`65`	`if (value.isEmpty()) return null;`
`57`	`66`	`return value;`
`58`	`67`	`}`
`59`	`68`
	`69`	`+ @Nullable`
`60`	`70`	`public static Integer toInt(String value) {`
`61`	`71`	`if (value.isEmpty()) return null;`
`62`	`72`	`return PathParamHelper.toInt(value);`
`63`	`73`	`}`
`64`	`74`
	`75`	`+ @Nullable`
`65`	`76`	`public static Long toLong(String value) {`
`66`	`77`	`if (value.isEmpty()) return null;`
`67`	`78`	`return PathParamHelper.toLong(value);`
`68`	`79`	`}`
`69`	`80`
	`81`	`+ @Nullable`
`70`	`82`	`public static Double toDouble(String value) {`
`71`	`83`	`if (value.isEmpty()) return null;`
`72`	`84`	`try {`
`@@ -76,6 +88,7 @@ public static Double toDouble(String value) {`
`76`	`88`	`}`
`77`	`89`	`}`
`78`	`90`
	`91`	`+ @Nullable`
`79`	`92`	`public static BigDecimal toBigDecimal(String value) {`
`80`	`93`	`if (value.isEmpty()) return null;`
`81`	`94`	`try {`
`@@ -85,16 +98,19 @@ public static BigDecimal toBigDecimal(String value) {`
`85`	`98`	`}`
`86`	`99`	`}`
`87`	`100`
	`101`	`+ @Nullable`
`88`	`102`	`public static Boolean toBoolean(String value) {`
`89`	`103`	`if (value.isEmpty()) return null;`
`90`	`104`	`return Boolean.valueOf(value); // Boolean.parseBoolean does not throw exception`
`91`	`105`	`}`
`92`	`106`
	`107`	`+ @Nullable`
`93`	`108`	`public static <T extends Enum<?>> T toEnum(String value, Class<T> valueClass) {`
`94`	`109`	`if (value.isEmpty()) return null;`
`95`	`110`	`return PathParamHelper.toEnum(value, valueClass);`
`96`	`111`	`}`
`97`	`112`
	`113`	`+ @Nullable`
`98`	`114`	`public static ZonedDateTime toZonedDateTime(String value) {`
`99`	`115`	`if (value.isEmpty()) return null;`
`100`	`116`	`try {`
`@@ -104,6 +120,7 @@ public static ZonedDateTime toZonedDateTime(String value) {`
`104`	`120`	`}`
`105`	`121`	`}`
`106`	`122`
	`123`	`+ @Nullable`
`107`	`124`	`public static LocalDateTime toDateTime(String value) {`
`108`	`125`	`if (value.isEmpty()) return null;`
`109`	`126`	`try {`
`@@ -113,6 +130,7 @@ public static LocalDateTime toDateTime(String value) {`
`113`	`130`	`}`
`114`	`131`	`}`
`115`	`132`
	`133`	`+ @Nullable`
`116`	`134`	`public static LocalTime toTime(String value) {`
`117`	`135`	`if (value.isEmpty()) return null;`
`118`	`136`	`try {`
`@@ -122,6 +140,7 @@ public static LocalTime toTime(String value) {`
`122`	`140`	`}`
`123`	`141`	`}`
`124`	`142`
	`143`	`+ @Nullable`
`125`	`144`	`public static LocalDate toDate(String value) {`
`126`	`145`	`if (value.isEmpty()) return null;`
`127`	`146`	`try {`
Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,7 @@`
`7`	`7`	`import core.framework.internal.validate.Validator;`
`8`	`8`	`import core.framework.internal.web.service.InternalErrorResponse;`
`9`	`9`	`import core.framework.util.Maps;`
	`10`	`+import org.jspecify.annotations.Nullable;`
`10`	`11`
`11`	`12`	`import java.io.IOException;`
`12`	`13`	`import java.lang.reflect.Type;`
`@@ -36,6 +37,7 @@ public void register(Type responseType, BeanClassValidator validator) {`
`36`	`37`	`}`
`37`	`38`	`}`
`38`	`39`
	`40`	`+ @Nullable`
`39`	`41`	`public Object fromJSON(Type responseType, byte[] body) throws IOException {`
`40`	`42`	`if (void.class == responseType) return null;`
`41`	`43`