From efea28953d5542cb5a17072f48967ab90d4b2979 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Thu, 22 May 2025 17:03:09 +0200
Subject: [PATCH] Improve Javadoc for getFilename() & getFilenameExtension() in
 StringUtils

Closes gh-34932
---
 .../org/springframework/util/StringUtils.java | 30 +++++++++++++++----
 .../util/StringUtilsTests.java                |  6 ++--
 2 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/util/StringUtils.java b/spring-core/src/main/java/org/springframework/util/StringUtils.java
index 900fadf7b4..abfc9663cf 100644
--- a/spring-core/src/main/java/org/springframework/util/StringUtils.java
+++ b/spring-core/src/main/java/org/springframework/util/StringUtils.java
@@ -614,10 +614,18 @@ public abstract class StringUtils {
 	}
 
 	/**
-	 * Extract the filename from the given Java resource path,
-	 * for example, {@code "mypath/myfile.txt" &rarr; "myfile.txt"}.
+	 * Extract the filename from the given Java resource path.
+	 * <p>Examples:
+	 * <ul>
+	 * <li>{@code "my/path/myfile.txt"} &rarr; {@code "myfile.txt"}
+	 * <li>{@code "myfolder"} &rarr; {@code "myfolder"}
+	 * <li>{@code "myfile.txt"} &rarr; {@code "myfile.txt"}
+	 * <li>{@code ""} &rarr; {@code ""}
+	 * <li>{@code null} &rarr; {@code null}
+	 * </ul>
 	 * @param path the file path (may be {@code null})
-	 * @return the extracted filename, or {@code null} if none
+	 * @return the extracted filename, the original path if it does not contain a
+	 * forward slash ({@code "/"}), or {@code null} if the supplied path is {@code null}
 	 */
 	@Contract("null -> null; !null -> !null")
 	public static @Nullable String getFilename(@Nullable String path) {
@@ -630,10 +638,20 @@ public abstract class StringUtils {
 	}
 
 	/**
-	 * Extract the filename extension from the given Java resource path,
-	 * for example, "mypath/myfile.txt" &rarr; "txt".
+	 * Extract the filename extension from the given Java resource path.
+	 * <p>Examples:
+	 * <ul>
+	 * <li>{@code "my/path/myfile.txt"} &rarr; {@code "txt"}
+	 * <li>{@code "myfile.txt"} &rarr; {@code "txt"}
+	 * <li>{@code "my/path/myfile."} &rarr; {@code ""}
+	 * <li>{@code "myfile"} &rarr; {@code null}
+	 * <li>{@code ""} &rarr; {@code null}
+	 * <li>{@code null} &rarr; {@code null}
+	 * </ul>
 	 * @param path the file path (may be {@code null})
-	 * @return the extracted filename extension, or {@code null} if none
+	 * @return the extracted filename extension (potentially an empty string), or
+	 * {@code null} if the provided path is {@code null} or does not contain a dot
+	 * ({@code "."})
 	 */
 	public static @Nullable String getFilenameExtension(@Nullable String path) {
 		if (path == null) {
diff --git a/spring-core/src/test/java/org/springframework/util/StringUtilsTests.java b/spring-core/src/test/java/org/springframework/util/StringUtilsTests.java
index c5e321188e..297b5128db 100644
--- a/spring-core/src/test/java/org/springframework/util/StringUtilsTests.java
+++ b/spring-core/src/test/java/org/springframework/util/StringUtilsTests.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-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.
@@ -359,11 +359,11 @@ class StringUtilsTests {
 		assertThat(StringUtils.getFilename(null)).isNull();
 		assertThat(StringUtils.getFilename("")).isEmpty();
 		assertThat(StringUtils.getFilename("myfile")).isEqualTo("myfile");
-		assertThat(StringUtils.getFilename("mypath/myfile")).isEqualTo("myfile");
+		assertThat(StringUtils.getFilename("my/path/myfile")).isEqualTo("myfile");
 		assertThat(StringUtils.getFilename("myfile.")).isEqualTo("myfile.");
 		assertThat(StringUtils.getFilename("mypath/myfile.")).isEqualTo("myfile.");
 		assertThat(StringUtils.getFilename("myfile.txt")).isEqualTo("myfile.txt");
-		assertThat(StringUtils.getFilename("mypath/myfile.txt")).isEqualTo("myfile.txt");
+		assertThat(StringUtils.getFilename("my/path/myfile.txt")).isEqualTo("myfile.txt");
 	}
 
 	@Test