Implement description consistently across Resources

This commit ensures Resources have consistent, non-empty, meaningful
implementations for getDescription(), thus ensuring that calls to
toString() (e.g., in log statements) no longer return an empty String.

This commit also polishes the Javadoc for various Resource
implementations.

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

 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -23,7 +23,7 @@ import java.util.Arrays;
 
 /**
  * {@link Resource} implementation for a given byte array.
- * Creates a ByteArrayInputStreams for the given byte array.
+ * <p>Creates a {@link ByteArrayInputStream} for the given byte array.
  *
  * <p>Useful for loading content from any given byte array,
  * without having to resort to a single-use {@link InputStreamResource}.
@@ -31,6 +31,7 @@ import java.util.Arrays;
  * where JavaMail needs to be able to read the stream multiple times.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 1.2.3
  * @see java.io.ByteArrayInputStream
  * @see InputStreamResource
@@ -99,11 +100,12 @@ public class ByteArrayResource extends AbstractResource {
 	}
 
 	/**
-	 * This implementation returns the passed-in description, if any.
+	 * This implementation returns a description that includes the passed-in
+	 * {@code description}, if any.
 	 */
 	@Override
 	public String getDescription() {
-		return this.description;
+		return "Byte array resource [" + this.description + "]";
 	}
 
 

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

 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -20,17 +20,19 @@ import java.io.IOException;
 import java.io.InputStream;
 
 /**
- * {@link Resource} implementation for a given InputStream. Should only
- * be used if no specific Resource implementation is applicable.
- * In particular, prefer {@link ByteArrayResource} or any of the
- * file-based Resource implementations where possible.
+ * {@link Resource} implementation for a given {@link InputStream}.
+ * <p>Should only be used if no other specific {@code Resource} implementation
+ * is applicable. In particular, prefer {@link ByteArrayResource} or any of the
+ * file-based {@code Resource} implementations where possible.
  *
- * <p>In contrast to other Resource implementations, this is a descriptor
- * for an <i>already opened</i> resource - therefore returning "true" from
- * {@code isOpen()}. Do not use it if you need to keep the resource
- * descriptor somewhere, or if you need to read a stream multiple times.
+ * <p>In contrast to other {@code Resource} implementations, this is a descriptor
+ * for an <i>already opened</i> resource - therefore returning {@code true} from
+ * {@link #isOpen()}. Do not use an {@code InputStreamResource} if you need to
+ * keep the resource descriptor somewhere, or if you need to read from a stream
+ * multiple times.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 28.12.2003
  * @see ByteArrayResource
  * @see ClassPathResource
@@ -99,11 +101,12 @@ public class InputStreamResource extends AbstractResource {
 	}
 
 	/**
-	 * This implementation returns the passed-in description, if any.
+	 * This implementation returns a description that includes the passed-in
+	 * description, if any.
 	 */
 	@Override
 	public String getDescription() {
-		return this.description;
+		return "InputStream resource [" + this.description + "]";
 	}
 
 

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

 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -33,8 +33,8 @@ import org.springframework.util.Assert;
 
 /**
  * {@link Resource} implementation for {@code java.nio.file.Path} handles.
- * Supports resolution as File, and also as URL.
- * Implements the extended {@link WritableResource} interface.
+ * <p>Supports resolution as File, and also as URL.
+ * <p>Implements the extended {@link WritableResource} interface.
  *
  * @author Philippe Marschall
  * @since 4.0

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

 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -32,8 +32,8 @@ import org.springframework.util.StringUtils;
 
 /**
  * {@link Resource} implementation for {@code java.net.URL} locators.
- * Obviously supports resolution as URL, and also as File in case of
- * the "file:" protocol.
+ * <p>Supports resolution as a {@code URL} and also as a {@code File} in
+ * case of the {@code "file:"} protocol.
  *
  * @author Juergen Hoeller
  * @since 28.12.2003
@@ -58,7 +58,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 
 
 	/**
-	 * Create a new UrlResource based on the given URI object.
+	 * Create a new {@code UrlResource} based on the given URI object.
 	 * @param uri a URI
 	 * @throws MalformedURLException if the given URL path is not valid
 	 */
@@ -70,7 +70,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 	}
 
 	/**
-	 * Create a new UrlResource based on the given URL object.
+	 * Create a new {@code UrlResource} based on the given URL object.
 	 * @param url a URL
 	 */
 	public UrlResource(URL url) {
@@ -81,7 +81,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 	}
 
 	/**
-	 * Create a new UrlResource based on a URL path.
+	 * Create a new {@code UrlResource} based on a URL path.
 	 * <p>Note: The given path needs to be pre-encoded if necessary.
 	 * @param path a URL path
 	 * @throws MalformedURLException if the given URL path is not valid
@@ -95,7 +95,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 	}
 
 	/**
-	 * Create a new UrlResource based on a URI specification.
+	 * Create a new {@code UrlResource} based on a URI specification.
 	 * <p>The given parts will automatically get encoded if necessary.
 	 * @param protocol the URL protocol to use (e.g. "jar" or "file" - without colon);
 	 * also known as "scheme"
@@ -109,7 +109,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 	}
 
 	/**
-	 * Create a new UrlResource based on a URI specification.
+	 * Create a new {@code UrlResource} based on a URI specification.
 	 * <p>The given parts will automatically get encoded if necessary.
 	 * @param protocol the URL protocol to use (e.g. "jar" or "file" - without colon);
 	 * also known as "scheme"
@@ -154,7 +154,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 
 	/**
 	 * This implementation opens an InputStream for the given URL.
-	 * It sets the "UseCaches" flag to {@code false},
+	 * <p>It sets the {@code useCaches} flag to {@code false},
 	 * mainly to avoid jar file locking on Windows.
 	 * @see java.net.URL#openConnection()
 	 * @see java.net.URLConnection#setUseCaches(boolean)
@@ -214,7 +214,7 @@ public class UrlResource extends AbstractFileResolvingResource {
 	}
 
 	/**
-	 * This implementation creates a UrlResource, applying the given path
+	 * This implementation creates a {@code UrlResource}, applying the given path
 	 * relative to the path of the underlying URL of this resource descriptor.
 	 * @see java.net.URL#URL(java.net.URL, String)
 	 */

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

 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -35,6 +35,7 @@ import org.springframework.util.Assert;
  * @author Ales Justin
  * @author Juergen Hoeller
  * @author Costin Leau
+ * @author Sam Brannen
  * @since 3.0
  * @see org.jboss.vfs.VirtualFile
  */
@@ -120,7 +121,7 @@ public class VfsResource extends AbstractResource {
 
 	@Override
 	public String getDescription() {
-		return this.resource.toString();
+		return "VFS resource [" + this.resource + "]";
 	}
 
 	@Override

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

 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -32,8 +32,11 @@ import static org.hamcrest.CoreMatchers.*;
 import static org.junit.Assert.*;
 
 /**
+ * Unit tests for various {@link Resource} implementations.
+ *
  * @author Juergen Hoeller
  * @author Chris Beams
+ * @author Sam Brannen
  * @since 09.09.2004
  */
 public class ResourceTests {
@@ -55,7 +58,7 @@ public class ResourceTests {
 		assertFalse(resource.isOpen());
 		String content = FileCopyUtils.copyToString(new InputStreamReader(resource.getInputStream()));
 		assertEquals("testString", content);
-		assertEquals("my description", resource.getDescription());
+		assertTrue(resource.getDescription().contains("my description"));
 		assertEquals(resource, new ByteArrayResource("testString".getBytes()));
 	}
 
@@ -78,7 +81,7 @@ public class ResourceTests {
 		assertTrue(resource.isOpen());
 		String content = FileCopyUtils.copyToString(new InputStreamReader(resource.getInputStream()));
 		assertEquals("testString", content);
-		assertEquals("my description", resource.getDescription());
+		assertTrue(resource.getDescription().contains("my description"));
 		assertEquals(resource, new InputStreamResource(is));
 	}
 
@@ -114,7 +117,6 @@ public class ResourceTests {
 		assertEquals(resource, new ClassPathResource("Resource.class", getClass()));
 	}
 
-	@Ignore // passes under eclipse, fails under ant
 	@Test
 	public void testFileSystemResource() throws IOException {
 		Resource resource = new FileSystemResource(getClass().getResource("Resource.class").getFile());

spring-core/src/test/java/org/springframework/core/io/support/ResourcePropertySourceTests.java

 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -31,6 +31,7 @@ import static org.junit.Assert.*;
  * Unit tests for {@link ResourcePropertySource}.
  *
  * @author Chris Beams
+ * @author Sam Brannen
  * @since 3.1
  */
 public class ResourcePropertySourceTests {
@@ -46,57 +47,57 @@ public class ResourcePropertySourceTests {
 	@Test
 	public void withLocationAndGeneratedName() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource(PROPERTIES_LOCATION);
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is(PROPERTIES_RESOURCE_DESCRIPTION));
 	}
 
 	@Test
 	public void xmlWithLocationAndGeneratedName() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource(XML_PROPERTIES_LOCATION);
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is(XML_PROPERTIES_RESOURCE_DESCRIPTION));
 	}
 
 	@Test
 	public void withLocationAndExplicitName() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource("ps1", PROPERTIES_LOCATION);
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is("ps1"));
 	}
 
 	@Test
 	public void withLocationAndExplicitNameAndExplicitClassLoader() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource("ps1", PROPERTIES_LOCATION, getClass().getClassLoader());
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is("ps1"));
 	}
 
 	@Test
 	public void withLocationAndGeneratedNameAndExplicitClassLoader() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource(PROPERTIES_LOCATION, getClass().getClassLoader());
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is(PROPERTIES_RESOURCE_DESCRIPTION));
 	}
 
 	@Test
 	public void withResourceAndGeneratedName() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource(new ClassPathResource(PROPERTIES_PATH));
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is(PROPERTIES_RESOURCE_DESCRIPTION));
 	}
 
 	@Test
 	public void withResourceAndExplicitName() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource("ps1", new ClassPathResource(PROPERTIES_PATH));
-		assertEquals(ps.getProperty("foo"), "bar");
+		assertEquals("bar", ps.getProperty("foo"));
 		assertThat(ps.getName(), is("ps1"));
 	}
 
 	@Test
-	public void withResourceHavingNoDescriptionAndGeneratedName() throws IOException {
+	public void withResourceHavingNoDescription() throws IOException {
 		PropertySource<?> ps = new ResourcePropertySource(new ByteArrayResource("foo=bar".getBytes(), ""));
-		assertEquals(ps.getProperty("foo"), "bar");
-		assertTrue(ps.getName().startsWith("ByteArrayResource@"));
+		assertEquals("bar", ps.getProperty("foo"));
+		assertEquals("Byte array resource []", ps.getName());
 	}
 
 }