spring-projectsGH-10083: Apply Nullability to file module

Related to: spring-projects#10083

* The change in the `file.dsl` package has affected the `ComponentsRegistration` contract in the core module.
And that one has led to respective fixes in the `AMQP`, `JPA`, `Kafka` modules for DSL packages
* Fix `SimpleJsonSerializer` contract to return an empty JSON instead of `null`.
Something similar to what Jackson 3 provides for us by default.
* Rework a `WatchServiceDirectoryScanner` logic to initialize its internals in the ctor to avoid null-away errors
* Fix `FileWritingMessageHandler`, `HeadDirectoryScanner`, and `RecursiveDirectoryScanner` code style and logic according to IDE suggestions and new Nullability functionality
* Fix classes in the `file.config` package according to new Nullability logic
* Implement Nullability for `FileListFilter` abstraction and its implementations
* Fix `FileChannelCache` for a proper constant name.
* Respectively, fix the `NioFileLockerTests` to use a new `FileChannelCache.CHANNEL_CACHE` constant
* The remote directory could be null for some protocol operations.
Therefore implement that respectively in the `FileInfo`, `Session` and `RemoteFileOperations`

The change might look big, but it is inevitable and pretty straightforward

* Remove redundant FQCN for `@Nullable` on the `FileReadingMessageSource.doReceive()`.
That was a first JSpecify annotation changed in this class without replacing existing import for deprecated one from SF
* Fix `FileTransferringMessageHandler.handleMessageInternal()` logic to fail when file could not be transferred to remote dir.
Previously it returned silently.
The error was only logged in the `RemoteFileTemplate`

* Fix language in `AbstractInboundFileSynchronizingMessageSource.doReceive()` JavaDoc
* Bring back a proper JavaDoc for `RemoteFileOperations.rename()`
* Extract pattern variable for the `if` in the `FileWritingMessageHandler.handleRequestMessage()`
* Fix indents in the `HeadDirectoryScanner.HeadFilter` record

Author: artembilan

spring-integration-amqp/src/main/java/org/springframework/integration/amqp/dsl/AmqpInboundChannelAdapterSpec.java

@@ -19,6 +19,8 @@
 import java.util.Collections;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.amqp.rabbit.listener.MessageListenerContainer;
 import org.springframework.integration.amqp.inbound.AmqpInboundChannelAdapter;
 import org.springframework.integration.dsl.ComponentsRegistration;
@@ -48,8 +50,9 @@ protected AmqpInboundChannelAdapterSpec(MessageListenerContainerSpec<?, C> liste
 	}
 
 	@Override
-	public Map<Object, String> getComponentsToRegister() {
-		return Collections.singletonMap(this.listenerContainerSpec.getObject(), this.listenerContainerSpec.getId());
+	public Map<Object, @Nullable String> getComponentsToRegister() {
+		return Collections.<Object, @Nullable String>singletonMap(
+				this.listenerContainerSpec.getObject(), this.listenerContainerSpec.getId());
 	}
 
 }

spring-integration-amqp/src/main/java/org/springframework/integration/amqp/dsl/AmqpInboundGatewaySpec.java

@@ -19,6 +19,8 @@
 import java.util.Collections;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.amqp.core.AmqpTemplate;
 import org.springframework.amqp.rabbit.listener.AbstractMessageListenerContainer;
 import org.springframework.integration.amqp.inbound.AmqpInboundGateway;
@@ -61,8 +63,9 @@ protected AmqpInboundGatewaySpec(AbstractMessageListenerContainerSpec<?, C> list
 	}
 
 	@Override
-	public Map<Object, String> getComponentsToRegister() {
-		return Collections.singletonMap(this.listenerContainerSpec.getObject(), this.listenerContainerSpec.getId());
+	public Map<Object, @Nullable String> getComponentsToRegister() {
+		return Collections.<Object, @Nullable String>singletonMap(
+				this.listenerContainerSpec.getObject(), this.listenerContainerSpec.getId());
 	}
 
 }

spring-integration-core/src/main/java/org/springframework/integration/dsl/ComponentsRegistration.java

@@ -18,6 +18,8 @@
 
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * The marker interface for the {@link IntegrationComponentSpec} implementation,
  * when there is need to register as beans not only the target spec's components,
@@ -33,6 +35,6 @@
 @FunctionalInterface
 public interface ComponentsRegistration {
 
-	Map<Object, String> getComponentsToRegister();
+	Map<Object, @Nullable String> getComponentsToRegister();
 
 }

spring-integration-core/src/main/java/org/springframework/integration/json/SimpleJsonSerializer.java

@@ -87,7 +87,7 @@ public static String toJson(Object bean, String... propertiesToExclude) {
 		stringBuilder.setLength(stringBuilder.length() - 1);
 		stringBuilder.append("}");
 		if (stringBuilder.length() == 1) {
-			return null;
+			return "{}";
 		}
 		else {
 			return stringBuilder.toString();

spring-integration-file/src/main/java/org/springframework/integration/file/DefaultDirectoryScanner.java

@@ -21,6 +21,8 @@
 import java.util.Arrays;
 import java.util.List;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.integration.file.filters.AcceptOnceFileListFilter;
 import org.springframework.integration.file.filters.CompositeFileListFilter;
 import org.springframework.integration.file.filters.FileListFilter;
@@ -39,9 +41,9 @@
  */
 public class DefaultDirectoryScanner implements DirectoryScanner {
 
-	private volatile FileListFilter<File> filter;
+	private volatile @Nullable FileListFilter<File> filter;
 
-	private volatile FileLocker locker;
+	private volatile @Nullable FileLocker locker;
 
 	/**
 	 * Initialize {@link DefaultDirectoryScanner#filter} with a default list of
@@ -63,7 +65,7 @@ public void setFilter(FileListFilter<File> filter) {
 		this.filter = filter;
 	}
 
-	protected FileListFilter<File> getFilter() {
+	protected @Nullable FileListFilter<File> getFilter() {
 		return this.filter;
 	}
 
@@ -72,7 +74,7 @@ public final void setLocker(FileLocker locker) {
 		this.locker = locker;
 	}
 
-	protected FileLocker getLocker() {
+	protected @Nullable FileLocker getLocker() {
 		return this.locker;
 	}
 
@@ -82,17 +84,19 @@ protected FileLocker getLocker() {
 	 */
 	@Override
 	public boolean tryClaim(File file) {
-		return (this.locker == null) || this.locker.lock(file);
+		FileLocker lockerToUse = this.locker;
+		return (lockerToUse == null) || lockerToUse.lock(file);
 	}
 
 	@Override
 	public List<File> listFiles(File directory) throws IllegalArgumentException {
-		File[] files = listEligibleFiles(directory);
+		File @Nullable [] files = listEligibleFiles(directory);
 		if (files == null) {
 			throw new MessagingException("The path [" + directory
 					+ "] does not denote a properly accessible directory.");
 		}
-		return (this.filter != null) ? this.filter.filterFiles(files) : Arrays.asList(files);
+		FileListFilter<File> filterToUse = this.filter;
+		return (filterToUse != null) ? filterToUse.filterFiles(files) : Arrays.asList(files);
 	}
 
 	/**
@@ -101,7 +105,7 @@ public List<File> listFiles(File directory) throws IllegalArgumentException {
 	 * @param directory root directory to use for listing
 	 * @return the files this scanner should consider
 	 */
-	protected File[] listEligibleFiles(File directory) {
+	protected File @Nullable [] listEligibleFiles(File directory) {
 		return directory.listFiles();
 	}
 

spring-integration-file/src/main/java/org/springframework/integration/file/DefaultFileNameGenerator.java

@@ -43,6 +43,7 @@
  */
 public class DefaultFileNameGenerator extends AbstractExpressionEvaluator implements FileNameGenerator {
 
+	@SuppressWarnings("NullAway") // Does not see Nullability on the generics.
 	private volatile Expression expression =
 			new FunctionExpression<Message<?>>((message) -> message.getHeaders().get(FileHeaders.FILENAME));
 
@@ -61,6 +62,7 @@ public void setExpression(String expression) {
 	 * The default is defined by {@link FileHeaders#FILENAME}.
 	 * @param headerName The header name.
 	 */
+	@SuppressWarnings("NullAway") // Does not see Nullability on the generics.
 	public void setHeaderName(String headerName) {
 		Assert.notNull(headerName, "'headerName' must not be null");
 		this.expression = new FunctionExpression<Message<?>>((message) -> message.getHeaders().get(headerName));

spring-integration-file/src/main/java/org/springframework/integration/file/FileReadingMessageSource.java

@@ -43,14 +43,15 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Predicate;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.context.Lifecycle;
 import org.springframework.integration.endpoint.AbstractMessageSource;
 import org.springframework.integration.file.filters.DiscardAwareFileListFilter;
 import org.springframework.integration.file.filters.FileListFilter;
 import org.springframework.integration.file.filters.ResettableFileListFilter;
 import org.springframework.integration.support.AbstractIntegrationMessageBuilder;
 import org.springframework.integration.support.management.ManageableLifecycle;
-import org.springframework.lang.Nullable;
 import org.springframework.messaging.Message;
 import org.springframework.util.Assert;
 
@@ -107,6 +108,7 @@ public class FileReadingMessageSource extends AbstractMessageSource<File> implem
 	 */
 	private final Queue<File> toBeReceived;
 
+	@SuppressWarnings("NullAway.Init")
 	private File directory;
 
 	private DirectoryScanner scanner = new DefaultDirectoryScanner();
@@ -117,9 +119,9 @@ public class FileReadingMessageSource extends AbstractMessageSource<File> implem
 
 	private boolean scanEachPoll = false;
 
-	private FileListFilter<File> filter;
+	private @Nullable FileListFilter<File> filter;
 
-	private FileLocker locker;
+	private @Nullable FileLocker locker;
 
 	private boolean useWatchService;
 
@@ -370,7 +372,7 @@ protected void onInit() {
 	}
 
 	@Override
-	protected AbstractIntegrationMessageBuilder<File> doReceive() {
+	protected @Nullable AbstractIntegrationMessageBuilder<File> doReceive() {
 		// rescan only if needed or explicitly configured
 		if (this.scanEachPoll || this.toBeReceived.isEmpty()) {
 			scanInputDirectory();
@@ -433,11 +435,19 @@ private final class WatchServiceDirectoryScanner extends DefaultDirectoryScanner
 
 		private final ConcurrentMap<Path, WatchKey> pathKeys = new ConcurrentHashMap<>();
 
+		private final WatchEvent.Kind<?>[] kinds;
+
 		private final Set<File> filesToPoll = ConcurrentHashMap.newKeySet();
 
+		@SuppressWarnings("NullAway.Init")
 		private WatchService watcher;
 
-		private WatchEvent.Kind<?>[] kinds;
+		WatchServiceDirectoryScanner() {
+			this.kinds =
+					Arrays.stream(FileReadingMessageSource.this.watchEvents)
+							.map(watchEventType -> watchEventType.kind)
+							.toArray(WatchEvent.Kind<?>[]::new);
+		}
 
 		@Override
 		public void setFilter(FileListFilter<File> filter) {
@@ -451,27 +461,19 @@ public void setFilter(FileListFilter<File> filter) {
 		public void start() {
 			try {
 				this.watcher = FileSystems.getDefault().newWatchService();
+				Set<File> initialFiles = walkDirectory(FileReadingMessageSource.this.directory.toPath(), null);
+				initialFiles.addAll(filesFromEvents());
+				this.filesToPoll.addAll(initialFiles);
 			}
 			catch (IOException ex) {
 				logger.error(ex, () -> "Failed to create watcher for " + FileReadingMessageSource.this.directory);
 			}
-
-			this.kinds = new WatchEvent.Kind<?>[FileReadingMessageSource.this.watchEvents.length];
-
-			for (int i = 0; i < FileReadingMessageSource.this.watchEvents.length; i++) {
-				this.kinds[i] = FileReadingMessageSource.this.watchEvents[i].kind;
-			}
-
-			Set<File> initialFiles = walkDirectory(FileReadingMessageSource.this.directory.toPath(), null);
-			initialFiles.addAll(filesFromEvents());
-			this.filesToPoll.addAll(initialFiles);
 		}
 
 		@Override
 		public void stop() {
 			try {
 				this.watcher.close();
-				this.watcher = null;
 				this.pathKeys.clear();
 			}
 			catch (IOException ex) {
@@ -486,8 +488,6 @@ public boolean isRunning() {
 
 		@Override
 		protected File[] listEligibleFiles(File directory) {
-			Assert.state(this.watcher != null, "The WatchService hasn't been started");
-
 			Set<File> files = new LinkedHashSet<>();
 
 			for (Iterator<File> iterator = this.filesToPoll.iterator(); iterator.hasNext(); ) {
@@ -576,7 +576,7 @@ private void processFilesFromOverflowEvent(Set<File> files, WatchEvent<?> event)
 			}
 		}
 
-		private Set<File> walkDirectory(Path directory, final WatchEvent.Kind<?> kind) {
+		private Set<File> walkDirectory(Path directory, WatchEvent.@Nullable Kind<?> kind) {
 			final Set<File> walkedFiles = new LinkedHashSet<>();
 			try {
 				registerWatch(directory);