GH-10162: The full file path for PersistentAcceptOnceFileListFilter (#10420)

GH-10162: The full file path for `PersistentAcceptOnceFileListFilter`

Fixes: #10162

The `AbstractPersistentAcceptOnceFileListFilter` may cause a problem with entries
in the `MetadataStore` when the same file name is used from different directories.
Let's imagine a scenario when remote directories are created every day with respective timestamp,
e.g. today `20250828`, tomorrow `20250829`.
 The files in those directories are based on customer names: `customer1.xml`, `customer2.xml` etc.
Since most of the `AbstractPersistentAcceptOnceFileListFilter` implementations do just something like this:
`return file.getName();` that would lead to the same key for the `MetadataStore` operations.

* Fix `SmbPersistentAcceptOnceFileListFilter` to use `SmbFile.getUncPath()` as a notation of the full path file
* Fix `SftpPersistentAcceptOnceFileListFilter` to use `SftpClient.DirEntry.getLongFilename()` if it is not empty.
* Fix `SftpSession.list()` to populated the mentioned `longFileName` into a new `SftpClient.DirEntry` instance based on just fetched
* Introduce an `EnhancedFTPFile` adapter to delegate to the original `FTPFile` and populate an additional `longFileName` property
* Check for this new class in the `FtpPersistentAcceptOnceFileListFilter` to extract its `longFileName` property

* Fix Checkstyle violation: remove unused import

* Fix typos in docs
* Improve `FtpSession.list()` to use a new array instead of `LinkedList`
* Also, use `.` as a working directory placeholder and always populate a long file name

Author: artembilan

spring-integration-ftp/src/main/java/org/springframework/integration/ftp/filters/FtpPersistentAcceptOnceFileListFilter.java

@@ -19,13 +19,16 @@
 import org.apache.commons.net.ftp.FTPFile;
 
 import org.springframework.integration.file.filters.AbstractPersistentAcceptOnceFileListFilter;
+import org.springframework.integration.ftp.session.EnhancedFTPFile;
 import org.springframework.integration.metadata.ConcurrentMetadataStore;
+import org.springframework.util.StringUtils;
 
 /**
  * Persistent file list filter using the server's file timestamp to detect if we've already
  * 'seen' this file.
  *
  * @author Gary Russell
+ * @author Artem Bilan
  *
  * @since 3.0
  *
@@ -43,6 +46,13 @@ protected long modified(FTPFile file) {
 
 	@Override
 	protected String fileName(FTPFile file) {
+		if (file instanceof EnhancedFTPFile enhancedFTPFile) {
+			String longFileName = enhancedFTPFile.getLongFileName();
+			if (StringUtils.hasText(longFileName)) {
+				return longFileName;
+			}
+		}
+
 		return file.getName();
 	}
 

spring-integration-ftp/src/main/java/org/springframework/integration/ftp/session/EnhancedFTPFile.java

@@ -0,0 +1,202 @@
+/*
+ * Copyright 2025-present 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.ftp.session;
+
+import java.io.Serial;
+import java.time.Instant;
+import java.util.Calendar;
+
+import org.apache.commons.net.ftp.FTPFile;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * The {@link FTPFile} extension to provide additional information,
+ * e.g., long file name with directory included.
+ * The instance of this class is based on the original {@link FTPFile}
+ * with delegation from all the methods.
+ *
+ * @author Artem Bilan
+ *
+ * @since 7.0
+ */
+public class EnhancedFTPFile extends FTPFile {
+
+	@Serial
+	private static final long serialVersionUID = 9010790363003271996L;
+
+	private final FTPFile delegate;
+
+	private @Nullable String longFileName;
+
+	public EnhancedFTPFile(FTPFile delegate) {
+		this.delegate = delegate;
+	}
+
+	@Override
+	public String getGroup() {
+		return this.delegate.getGroup();
+	}
+
+	@Override
+	public int getHardLinkCount() {
+		return this.delegate.getHardLinkCount();
+	}
+
+	@Override
+	public String getLink() {
+		return this.delegate.getLink();
+	}
+
+	@Override
+	public String getName() {
+		return this.delegate.getName();
+	}
+
+	@Override
+	public String getRawListing() {
+		return this.delegate.getRawListing();
+	}
+
+	@Override
+	public long getSize() {
+		return this.delegate.getSize();
+	}
+
+	@Override
+	public Calendar getTimestamp() {
+		return this.delegate.getTimestamp();
+	}
+
+	@Override
+	public Instant getTimestampInstant() {
+		return this.delegate.getTimestampInstant();
+	}
+
+	@Override
+	public int getType() {
+		return this.delegate.getType();
+	}
+
+	@Override
+	public String getUser() {
+		return this.delegate.getUser();
+	}
+
+	@Override
+	public boolean hasPermission(int access, int permission) {
+		return this.delegate.hasPermission(access, permission);
+	}
+
+	@Override
+	public boolean isDirectory() {
+		return this.delegate.isDirectory();
+	}
+
+	@Override
+	public boolean isFile() {
+		return this.delegate.isFile();
+	}
+
+	@Override
+	public boolean isSymbolicLink() {
+		return this.delegate.isSymbolicLink();
+	}
+
+	@Override
+	public boolean isUnknown() {
+		return this.delegate.isUnknown();
+	}
+
+	@Override
+	public boolean isValid() {
+		return this.delegate.isValid();
+	}
+
+	@Override
+	public void setGroup(String group) {
+		this.delegate.setGroup(group);
+	}
+
+	@Override
+	public void setHardLinkCount(int hardLinkCount) {
+		this.delegate.setHardLinkCount(hardLinkCount);
+	}
+
+	@Override
+	public void setLink(String link) {
+		this.delegate.setLink(link);
+	}
+
+	@Override
+	public void setName(String name) {
+		this.delegate.setName(name);
+	}
+
+	@Override
+	public void setPermission(int access, int permission, boolean value) {
+		this.delegate.setPermission(access, permission, value);
+	}
+
+	@Override
+	public void setRawListing(String rawListing) {
+		this.delegate.setRawListing(rawListing);
+	}
+
+	@Override
+	public void setSize(long size) {
+		this.delegate.setSize(size);
+	}
+
+	@Override
+	public void setTimestamp(Calendar calendar) {
+		this.delegate.setTimestamp(calendar);
+	}
+
+	@Override
+	public void setType(int type) {
+		this.delegate.setType(type);
+	}
+
+	@Override
+	public void setUser(String user) {
+		this.delegate.setUser(user);
+	}
+
+	@Override
+	public String toFormattedString() {
+		return this.delegate.toFormattedString();
+	}
+
+	@Override
+	public String toFormattedString(String timezone) {
+		return this.delegate.toFormattedString(timezone);
+	}
+
+	@Override
+	public String toString() {
+		return this.delegate.toString();
+	}
+
+	public @Nullable String getLongFileName() {
+		return this.longFileName;
+	}
+
+	public void setLongFileName(@Nullable String longFileName) {
+		this.longFileName = longFileName;
+	}
+
+}

spring-integration-ftp/src/main/java/org/springframework/integration/ftp/session/FtpSession.java

@@ -31,6 +31,7 @@
 import org.springframework.integration.file.remote.session.Session;
 import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
+import org.springframework.util.StringUtils;
 
 /**
  * Implementation of {@link Session} for FTP.
@@ -71,7 +72,17 @@ public boolean remove(String path) throws IOException {
 
 	@Override
 	public FTPFile[] list(@Nullable String path) throws IOException {
-		return this.client.listFiles(path);
+		FTPFile[] ftpFiles = this.client.listFiles(path);
+		String remoteDir = StringUtils.hasText(path) ? path : ".";
+		EnhancedFTPFile[] enhancedFtpFiles = new EnhancedFTPFile[ftpFiles.length];
+		for (int i = 0; i < ftpFiles.length; i++) {
+			FTPFile ftpFile = ftpFiles[i];
+			EnhancedFTPFile enhancedFTPFile = new EnhancedFTPFile(ftpFile);
+			enhancedFTPFile.setLongFileName(remoteDir + '/' + ftpFile.getName());
+			enhancedFtpFiles[i] = enhancedFTPFile;
+		}
+
+		return enhancedFtpFiles;
 	}
 
 	@Override

spring-integration-ftp/src/test/java/org/springframework/integration/ftp/inbound/FtpInboundRemoteFileSystemSynchronizerTests.java

@@ -24,6 +24,7 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
+import java.util.Properties;
 
 import org.apache.commons.net.ftp.FTPClient;
 import org.apache.commons.net.ftp.FTPFile;
@@ -69,7 +70,7 @@
  */
 public class FtpInboundRemoteFileSystemSynchronizerTests implements TestApplicationContextAware {
 
-	private static FTPClient ftpClient = mock(FTPClient.class);
+	private static final FTPClient ftpClient = mock(FTPClient.class);
 
 	@BeforeEach
 	@AfterEach
@@ -85,7 +86,7 @@ public void testCopyFileToLocalDir() throws Exception {
 		TestFtpSessionFactory ftpSessionFactory = new TestFtpSessionFactory();
 		ftpSessionFactory.setUsername("kermit");
 		ftpSessionFactory.setPassword("frog");
-		ftpSessionFactory.setHost("foo.com");
+		ftpSessionFactory.setHost("some-host.com");
 		FtpInboundFileSynchronizer synchronizer = spy(new FtpInboundFileSynchronizer(ftpSessionFactory));
 		synchronizer.setDeleteRemoteFiles(true);
 		synchronizer.setPreserveTimestamp(true);
@@ -97,7 +98,7 @@ public void testCopyFileToLocalDir() throws Exception {
 		store.setBaseDirectory("test");
 		store.afterPropertiesSet();
 		FtpPersistentAcceptOnceFileListFilter persistFilter =
-				new FtpPersistentAcceptOnceFileListFilter(store, "foo");
+				new FtpPersistentAcceptOnceFileListFilter(store, "someKey/");
 		List<FileListFilter<FTPFile>> filters = new ArrayList<>();
 		filters.add(persistFilter);
 		filters.add(patternFilter);
@@ -166,6 +167,10 @@ public void testCopyFileToLocalDir() throws Exception {
 
 		Map<?, ?> metadata = TestUtils.getPropertyValue(remoteFileMetadataStore, "metadata", Map.class);
 		assertThat(metadata).isEmpty();
+
+		Properties metadataProperties = TestUtils.getPropertyValue(store, "metadata", Properties.class);
+		metadataProperties.stringPropertyNames()
+				.forEach(name -> assertThat(name).startsWith("someKey/remote-test-dir/"));
 	}
 
 	@Test

spring-integration-ftp/src/test/java/org/springframework/integration/ftp/outbound/FtpServerOutboundTests.java

@@ -68,6 +68,7 @@
 import org.springframework.integration.ftp.server.PathRemovedEvent;
 import org.springframework.integration.ftp.server.SessionClosedEvent;
 import org.springframework.integration.ftp.server.SessionOpenedEvent;
+import org.springframework.integration.ftp.session.EnhancedFTPFile;
 import org.springframework.integration.ftp.session.FtpRemoteFileTemplate;
 import org.springframework.integration.support.MessageBuilder;
 import org.springframework.integration.support.PartialSuccessException;
@@ -516,7 +517,7 @@ public void testMgetPartial() throws Exception {
 			FTPFile[] files = (FTPFile[]) invocation.callRealMethod();
 			// add an extra file where the get will fail
 			files = Arrays.copyOf(files, files.length + 1);
-			FTPFile bogusFile = new FTPFile();
+			FTPFile bogusFile = new EnhancedFTPFile(new FTPFile());
 			bogusFile.setName("bogus.txt");
 			files[files.length - 1] = bogusFile;
 			return files;
@@ -542,7 +543,7 @@ public void testMgetRecursivePartial() throws Exception {
 			FTPFile[] files = (FTPFile[]) invocation.callRealMethod();
 			// add an extra file where the get will fail
 			files = Arrays.copyOf(files, files.length + 1);
-			FTPFile bogusFile = new FTPFile();
+			FTPFile bogusFile = new EnhancedFTPFile(new FTPFile());
 			bogusFile.setName("bogus.txt");
 			bogusFile.setTimestamp(Calendar.getInstance());
 			files[files.length - 1] = bogusFile;

spring-integration-sftp/src/main/java/org/springframework/integration/sftp/filters/SftpPersistentAcceptOnceFileListFilter.java

@@ -20,6 +20,7 @@
 
 import org.springframework.integration.file.filters.AbstractPersistentAcceptOnceFileListFilter;
 import org.springframework.integration.metadata.ConcurrentMetadataStore;
+import org.springframework.util.StringUtils;
 
 /**
  * Persistent file list filter using the server's file timestamp to detect if we've already
@@ -46,7 +47,8 @@ protected long modified(SftpClient.DirEntry file) {
 
 	@Override
 	protected String fileName(SftpClient.DirEntry file) {
-		return file.getFilename();
+		String longFilename = file.getLongFilename();
+		return StringUtils.hasText(longFilename) ? longFilename : file.getFilename();
 	}
 
 	@Override

spring-integration-sftp/src/main/java/org/springframework/integration/sftp/session/SftpSession.java

@@ -126,8 +126,17 @@ public Stream<SftpClient.DirEntry> doList(@Nullable String path) throws IOExcept
 			}
 		}
 		remoteDir = normalizePath(remoteDir);
-		return StreamSupport.stream(this.sftpClient.readDir(remoteDir).spliterator(), false)
-				.filter((entry) -> !isPattern || PatternMatchUtils.simpleMatch(remoteFile, entry.getFilename()));
+		String remoteDirToUse = remoteDir;
+		return StreamSupport.stream(this.sftpClient.readDir(remoteDirToUse).spliterator(), false)
+				.filter((entry) -> !isPattern || PatternMatchUtils.simpleMatch(remoteFile, entry.getFilename()))
+				.map((entry) -> {
+					String longFilename = entry.getLongFilename();
+					if (StringUtils.hasText(longFilename)) {
+						return entry;
+					}
+					String filename = entry.getFilename();
+					return new SftpClient.DirEntry(filename, remoteDirToUse + '/' + filename, entry.getAttributes());
+				});
 	}
 
 	@Override