Include charset in EncodedResource.equals()

Prior to this commit, the implementation of equals() in EncodedResource
was based solely on the resource and encoding. Thus, if a Charset were
specified instead of an encoding, invocations of equals() would not
work as expected.

This commit addresses this issue by including the charset in the
implementation of equals() and introducing corresponding tests in a new
EncodedResourceTests class. Furthermore, this commit makes
EncodedResource immutable and updates all Javadoc to reflect support
for the encoding and charset properties.

Issue: SPR-12767
(cherry picked from commit 93c70b7440)

spring-core/src/main/java/org/springframework/core/io/support/EncodedResource.java

@@ -1,5 +1,5 @@
 /*
- * 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.
@@ -27,69 +27,73 @@ import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
 
 /**
- * Holder that combines a {@link org.springframework.core.io.Resource}
- * with a specific encoding to be used for reading from the resource.
+ * Holder that combines a {@link Resource} descriptor with a specific encoding
+ * or {@code Charset} to be used for reading from the resource.
  *
- * <p>Used as argument for operations that support to read content with
- * a specific encoding (usually through a {@code java.io.Reader}.
+ * <p>Used as an argument for operations that support reading content with
+ * a specific encoding, typically via a {@code java.io.Reader}.
  *
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 1.2.6
  * @see java.io.Reader
+ * @see java.nio.charset.Charset
  */
 public class EncodedResource {
 
 	private final Resource resource;
 
-	private String encoding;
+	private final String encoding;
 
-	private Charset charset;
+	private final Charset charset;
 
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * not specifying a specific encoding.
-	 * @param resource the Resource to hold
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * not specifying an explicit encoding or {@code Charset}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
 	 */
 	public EncodedResource(Resource resource) {
-		Assert.notNull(resource, "Resource must not be null");
-		this.resource = resource;
+		this(resource, null, null);
 	}
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * using the specified encoding.
-	 * @param resource the Resource to hold
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * using the specified {@code encoding}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
 	 * @param encoding the encoding to use for reading from the resource
 	 */
 	public EncodedResource(Resource resource, String encoding) {
-		Assert.notNull(resource, "Resource must not be null");
-		this.resource = resource;
-		this.encoding = encoding;
+		this(resource, encoding, null);
 	}
 
 	/**
-	 * Create a new EncodedResource for the given Resource,
-	 * using the specified encoding.
-	 * @param resource the Resource to hold
-	 * @param charset the charset to use for reading from the resource
+	 * Create a new {@code EncodedResource} for the given {@code Resource},
+	 * using the specified {@code Charset}.
+	 * @param resource the {@code Resource} to hold; never {@code null}
+	 * @param charset the {@code Charset} to use for reading from the resource
 	 */
 	public EncodedResource(Resource resource, Charset charset) {
+		this(resource, null, charset);
+	}
+
+	private EncodedResource(Resource resource, String encoding, Charset charset) {
+		super();
 		Assert.notNull(resource, "Resource must not be null");
 		this.resource = resource;
+		this.encoding = encoding;
 		this.charset = charset;
 	}
 
-
 	/**
-	 * Return the Resource held.
+	 * Return the {@code Resource} held by this {@code EncodedResource}.
 	 */
 	public final Resource getResource() {
 		return this.resource;
 	}
 
 	/**
-	 * Return the encoding to use for reading from the resource,
+	 * Return the encoding to use for reading from the {@linkplain #getResource() resource},
 	 * or {@code null} if none specified.
 	 */
 	public final String getEncoding() {
@@ -97,17 +101,17 @@ public class EncodedResource {
 	}
 
 	/**
-	 * Return the charset to use for reading from the resource,
+	 * Return the {@code Charset} to use for reading from the {@linkplain #getResource() resource},
 	 * or {@code null} if none specified.
 	 */
 	public final Charset getCharset() {
 		return this.charset;
 	}
 
-
 	/**
 	 * Determine whether a {@link Reader} is required as opposed to an {@link InputStream},
-	 * i.e. whether an encoding or a charset has been specified.
+	 * i.e. whether an {@linkplain #getEncoding() encoding} or a {@link #getCharset() Charset}
+	 * has been specified.
 	 * @see #getReader()
 	 * @see #getInputStream()
 	 */
@@ -116,10 +120,12 @@ public class EncodedResource {
 	}
 
 	/**
-	 * Open a {@code java.io.Reader} for the specified resource,
-	 * using the specified encoding (if any).
+	 * Open a {@code java.io.Reader} for the specified resource, using the specified
+	 * {@link #getCharset() Charset} or {@linkplain #getEncoding() encoding}
+	 * (if any).
 	 * @throws IOException if opening the Reader failed
 	 * @see #requiresReader()
+	 * @see #getInputStream()
 	 */
 	public Reader getReader() throws IOException {
 		if (this.charset != null) {
@@ -134,10 +140,11 @@ public class EncodedResource {
 	}
 
 	/**
-	 * Open an {@code java.io.InputStream} for the specified resource,
-	 * typically assuming that there is no specific encoding to use.
+	 * Open a {@code java.io.InputStream} for the specified resource, ignoring any
+	 * specified {@link #getCharset() Charset} or {@linkplain #getEncoding() encoding}.
 	 * @throws IOException if opening the InputStream failed
 	 * @see #requiresReader()
+	 * @see #getReader()
 	 */
 	public InputStream getInputStream() throws IOException {
 		return this.resource.getInputStream();
@@ -150,9 +157,10 @@ public class EncodedResource {
 			return true;
 		}
 		if (obj instanceof EncodedResource) {
-			EncodedResource otherRes = (EncodedResource) obj;
-			return (this.resource.equals(otherRes.resource) &&
-					ObjectUtils.nullSafeEquals(this.encoding, otherRes.encoding));
+			EncodedResource that = (EncodedResource) obj;
+			return (this.resource.equals(that.resource) &&
+					ObjectUtils.nullSafeEquals(this.charset, that.charset) &&
+					ObjectUtils.nullSafeEquals(this.encoding, that.encoding));
 		}
 		return false;
 	}

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

@@ -0,0 +1,83 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://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.core.io.support;
+
+import java.nio.charset.Charset;
+
+import org.junit.Test;
+import org.springframework.core.io.DescriptiveResource;
+import org.springframework.core.io.Resource;
+
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for {@link EncodedResource}.
+ *
+ * @author Sam Brannen
+ * @since 3.2.14
+ */
+public class EncodedResourceTests {
+
+	private static final String UTF8 = "UTF-8";
+	private static final String UTF16 = "UTF-16";
+	private static final Charset UTF8_CS = Charset.forName(UTF8);
+	private static final Charset UTF16_CS = Charset.forName(UTF16);
+
+	private final Resource resource = new DescriptiveResource("test");
+
+
+	@Test
+	public void equalsWithNullOtherObject() {
+		assertFalse(new EncodedResource(resource).equals(null));
+	}
+
+	@Test
+	public void equalsWithSameEncoding() {
+		EncodedResource er1 = new EncodedResource(resource, UTF8);
+		EncodedResource er2 = new EncodedResource(resource, UTF8);
+		assertEquals(er1, er2);
+	}
+
+	@Test
+	public void equalsWithDifferentEncoding() {
+		EncodedResource er1 = new EncodedResource(resource, UTF8);
+		EncodedResource er2 = new EncodedResource(resource, UTF16);
+		assertNotEquals(er1, er2);
+	}
+
+	@Test
+	public void equalsWithSameCharset() {
+		EncodedResource er1 = new EncodedResource(resource, UTF8_CS);
+		EncodedResource er2 = new EncodedResource(resource, UTF8_CS);
+		assertEquals(er1, er2);
+	}
+
+	@Test
+	public void equalsWithDifferentCharset() {
+		EncodedResource er1 = new EncodedResource(resource, UTF8_CS);
+		EncodedResource er2 = new EncodedResource(resource, UTF16_CS);
+		assertNotEquals(er1, er2);
+	}
+
+	@Test
+	public void equalsWithEncodingAndCharset() {
+		EncodedResource er1 = new EncodedResource(resource, UTF8);
+		EncodedResource er2 = new EncodedResource(resource, UTF8_CS);
+		assertNotEquals(er1, er2);
+	}
+
+}