Un-deprecate PathResource (for NIO Path resolution in createRelative)

Includes aligned createRelative signature and dedicated java.io.File test.

Closes gh-24211

spring-core/src/main/java/org/springframework/core/io/FileSystemResource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -49,6 +49,7 @@ import org.springframework.util.StringUtils;
  *
  * @author Juergen Hoeller
  * @since 28.12.2003
+ * @see #FileSystemResource(String)
  * @see #FileSystemResource(File)
  * @see #FileSystemResource(Path)
  * @see java.io.File
@@ -108,6 +109,15 @@ public class FileSystemResource extends AbstractResource implements WritableReso
 	 * <p>In contrast to {@link PathResource}, this variant strictly follows the
 	 * general {@link FileSystemResource} conventions, in particular in terms of
 	 * path cleaning and {@link #createRelative(String)} handling.
+	 * <p>Note: When building relative resources via {@link #createRelative},
+	 * the relative path will apply <i>at the same directory level</i>:
+	 * e.g. Paths.get("C:/dir1"), relative path "dir2" -> "C:/dir2"!
+	 * If you prefer to have relative paths built underneath the given root directory,
+	 * use the {@link #FileSystemResource(String) constructor with a file path}
+	 * to append a trailing slash to the root path: "C:/dir1/", which indicates
+	 * this directory as root for all relative paths. Alternatively, consider
+	 * using {@link PathResource#PathResource(Path)} for {@code java.nio.path.Path}
+	 * resolution in {@code createRelative}, always nesting relative paths.
 	 * @param filePath a Path handle to a file
 	 * @since 5.1
 	 * @see #FileSystemResource(File)

spring-core/src/main/java/org/springframework/core/io/PathResource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -45,15 +45,16 @@ import org.springframework.util.Assert;
  * in {@link FileSystemResource#FileSystemResource(Path) FileSystemResource},
  * applying Spring's standard String-based path transformations but
  * performing all operations via the {@link java.nio.file.Files} API.
+ * This {@code PathResource} is effectively a pure {@code java.nio.path.Path}
+ * based alternative with different {@code createRelative} behavior.
  *
  * @author Philippe Marschall
  * @author Juergen Hoeller
  * @since 4.0
  * @see java.nio.file.Path
  * @see java.nio.file.Files
- * @deprecated as of 5.1.1, in favor of {@link FileSystemResource#FileSystemResource(Path)}
+ * @see FileSystemResource
  */
-@Deprecated
 public class PathResource extends AbstractResource implements WritableResource {
 
 	private final Path path;
@@ -253,7 +254,7 @@ public class PathResource extends AbstractResource implements WritableResource {
 	 * @see java.nio.file.Path#resolve(String)
 	 */
 	@Override
-	public Resource createRelative(String relativePath) throws IOException {
+	public Resource createRelative(String relativePath) {
 		return new PathResource(this.path.resolve(relativePath));
 	}
 

spring-core/src/test/java/org/springframework/core/io/ResourceTests.java

@@ -17,6 +17,7 @@
 package org.springframework.core.io;
 
 import java.io.ByteArrayInputStream;
+import java.io.File;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
@@ -130,6 +131,14 @@ class ResourceTests {
 		assertThat(resource).isEqualTo(new FileSystemResource(file));
 	}
 
+	@Test
+	void fileSystemResourceWithFile() throws IOException {
+		File file = new File(getClass().getResource("Resource.class").getFile());
+		Resource resource = new FileSystemResource(file);
+		doTestResource(resource);
+		assertThat(resource).isEqualTo(new FileSystemResource(file));
+	}
+
 	@Test
 	void fileSystemResourceWithFilePath() throws Exception {
 		Path filePath = Paths.get(getClass().getResource("Resource.class").toURI());