Improve Javadoc for getFilename() & getFilenameExtension() in StringUtils

Closes gh-34932

Author: sbrannen

spring-core/src/main/java/org/springframework/util/StringUtils.java

@@ -614,10 +614,18 @@ private static String changeFirstCharacterCase(String str, boolean capitalize) {
 	}
 
 	/**
-	 * Extract the filename from the given Java resource path,
-	 * for example, {@code "mypath/myfile.txt" → "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 @@ private static String changeFirstCharacterCase(String str, boolean capitalize) {
 	}
 
 	/**
-	 * 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) {

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 @@ void getFilename() {
 		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