GsonBuilderUtils for programmatic Base64 serialization setup; common Base64Utils class adapts between Java 8 and Commons Codec

Issue: SPR-9488

Author: jhoeller

build.gradle

@@ -293,6 +293,7 @@ project("spring-core") {
 
 		compile(files(cglibRepackJar))
 		compile("commons-logging:commons-logging:1.1.3")
+		optional("commons-codec:commons-codec:1.9")
 		optional("org.aspectj:aspectjweaver:${aspectjVersion}")
 		optional("net.sf.jopt-simple:jopt-simple:4.6")
 		optional("log4j:log4j:1.2.17")
@@ -625,7 +626,6 @@ project("spring-web") {
 		optional("org.apache.httpcomponents:httpasyncclient:4.0.1")
 		optional("com.fasterxml.jackson.core:jackson-databind:${jackson2Version}")
 		optional("com.google.code.gson:gson:${gsonVersion}")
-		optional("commons-codec:commons-codec:1.9")
 		optional("rome:rome:1.0")
 		optional("org.eclipse.jetty:jetty-servlet:${jettyVersion}") {
 			exclude group: "javax.servlet", module: "javax.servlet-api"

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

@@ -0,0 +1,165 @@
+/*
+ * Copyright 2002-2014 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.util;
+
+import java.nio.charset.Charset;
+import java.util.Base64;
+
+/**
+ * A simple utility class for Base64 encoding and decoding.
+ *
+ * <p>Adapts to either Java 8's {@link java.util.Base64} class or Apache
+ * Commons Codec's {@link org.apache.commons.codec.binary.Base64} class.
+ * With neither Java 8 nor Commons Codec present, encode/decode calls
+ * will fail with an IllegalStateException.
+ *
+ * @author Juergen Hoeller
+ * @since 4.1
+ * @see java.util.Base64
+ * @see org.apache.commons.codec.binary.Base64
+ */
+public abstract class Base64Utils {
+
+	private static final Charset DEFAULT_CHARSET = Charset.forName("UTF-8");
+
+
+	private static final Base64Delegate delegate;
+
+	static {
+		Base64Delegate delegateToUse = null;
+		// JDK 8's java.util.Base64 class present?
+		if (ClassUtils.isPresent("java.util.Base64", Base64Utils.class.getClassLoader())) {
+			delegateToUse = new JdkBase64Delegate();
+		}
+		// Apache Commons Codec present on the classpath?
+		else if (ClassUtils.isPresent("org.apache.commons.codec.binary.Base64", Base64Utils.class.getClassLoader())) {
+			delegateToUse = new CommonsCodecBase64Delegate();
+		}
+		delegate = delegateToUse;
+	}
+
+	/**
+	 * Assert that Byte64 encoding is actually supported.
+	 * @throws IllegalStateException if neither Java 8 nor Apache Commons Codec is present
+	 */
+	private static void assertSupported() {
+		Assert.state(delegate != null, "Neither Java 8 nor Apache Commons Codec found - Base64 encoding not supported");
+	}
+
+
+	/**
+	 * Base64-encode the given byte array.
+	 * @param src the original byte array (may be {@code null})
+	 * @return the encoded byte array (or {@code null} if the input was {@code null})
+	 * @throws IllegalStateException if Base64 encoding is not supported,
+	 * i.e. neither Java 8 nor Apache Commons Codec is present at runtime
+	 */
+	public static byte[] encode(byte[] src) {
+		assertSupported();
+		return delegate.encode(src);
+	}
+
+	/**
+	 * Base64-encode the given byte array to a String.
+	 * @param src the original byte array (may be {@code null})
+	 * @return the encoded byte array as a UTF-8 String
+	 * (or {@code null} if the input was {@code null})
+	 * @throws IllegalStateException if Base64 encoding is not supported,
+	 * i.e. neither Java 8 nor Apache Commons Codec is present at runtime
+	 */
+	public static String encodeToString(byte[] src) {
+		assertSupported();
+		if (src == null) {
+			return null;
+		}
+		if (src.length == 0) {
+			return "";
+		}
+		return new String(delegate.encode(src), DEFAULT_CHARSET);
+	}
+
+	/**
+	 * Base64-decode the given byte array.
+	 * @param src the encoded byte array (may be {@code null})
+	 * @return the original byte array (or {@code null} if the input was {@code null})
+	 * @throws IllegalStateException if Base64 encoding is not supported,
+	 * i.e. neither Java 8 nor Apache Commons Codec is present at runtime
+	 */
+	public static byte[] decode(byte[] src) {
+		assertSupported();
+		return delegate.decode(src);
+	}
+
+	/**
+	 * Base64-decode the given byte array from an UTF-8 String.
+	 * @param src the encoded UTF-8 String (may be {@code null})
+	 * @return the original byte array (or {@code null} if the input was {@code null})
+	 * @throws IllegalStateException if Base64 encoding is not supported,
+	 * i.e. neither Java 8 nor Apache Commons Codec is present at runtime
+	 */
+	public static byte[] decodeFromString(String src) {
+		assertSupported();
+		if (src == null) {
+			return null;
+		}
+		if (src.length() == 0) {
+			return new byte[0];
+		}
+		return delegate.decode(src.getBytes(DEFAULT_CHARSET));
+	}
+
+
+	private interface Base64Delegate {
+
+		byte[] encode(byte[] src);
+
+		byte[] decode(byte[] src);
+	}
+
+
+	private static class JdkBase64Delegate implements Base64Delegate {
+
+		public byte[] encode(byte[] src) {
+			if (src == null || src.length == 0) {
+				return src;
+			}
+			return Base64.getEncoder().encode(src);
+		}
+
+		public byte[] decode(byte[] src) {
+			if (src == null || src.length == 0) {
+				return src;
+			}
+			return Base64.getDecoder().decode(src);
+		}
+	}
+
+
+	private static class CommonsCodecBase64Delegate implements Base64Delegate {
+
+		private final org.apache.commons.codec.binary.Base64 base64 = new org.apache.commons.codec.binary.Base64();
+
+		public byte[] encode(byte[] src) {
+			return this.base64.encode(src);
+		}
+
+		public byte[] decode(byte[] src) {
+			return this.base64.decode(src);
+		}
+	}
+
+}

spring-web/src/main/java/org/springframework/http/converter/json/GsonBase64ByteArrayJsonTypeAdapter.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2002-2014 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.http.converter.json;
+
+import java.lang.reflect.Type;
+
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonDeserializationContext;
+import com.google.gson.JsonDeserializer;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonPrimitive;
+import com.google.gson.JsonSerializationContext;
+import com.google.gson.JsonSerializer;
+
+import org.springframework.util.Base64Utils;
+
+/**
+ * A simple utility class for obtaining a Google Gson 2.x {@link GsonBuilder}
+ * which Base64-encodes {@code byte[]} properties when reading and writing JSON.
+ *
+ * @author Juergen Hoeller
+ * @author Roy Clarkson
+ * @since 4.1
+ * @see GsonFactoryBean#setBase64EncodeByteArrays
+ * @see org.springframework.util.Base64Utils
+ */
+public abstract class GsonBuilderUtils {
+
+	/**
+	 * Obtain a {@link GsonBuilder} which Base64-encodes {@code byte[]}
+	 * properties when reading and writing JSON.
+	 * <p>A custom {@link com.google.gson.TypeAdapter} will be registered via
+	 * {@link GsonBuilder#registerTypeHierarchyAdapter(Class, Object)} which
+	 * serializes a {@code byte[]} property to and from a Base64-encoded String
+	 * instead of a JSON array.
+	 * <p><strong>NOTE:</strong> Use of this option requires the presence of the
+	 * Apache Commons Codec library on the classpath when running on Java 6 or 7.
+	 * On Java 8, the standard {@link java.util.Base64} facility is used instead.
+	 */
+	public static GsonBuilder gsonBuilderWithBase64EncodedByteArrays() {
+		// Assert that Base64 support is available, as long we're not on Java 8+
+		Base64Utils.encode(null);
+
+		// Now, construct a pre-configured GsonBuilder...
+		GsonBuilder builder = new GsonBuilder();
+		builder.registerTypeHierarchyAdapter(byte[].class, new Base64TypeAdapter());
+		return builder;
+	}
+
+
+	private static class Base64TypeAdapter implements JsonSerializer<byte[]>, JsonDeserializer<byte[]> {
+
+		@Override
+		public JsonElement serialize(byte[] src, Type typeOfSrc, JsonSerializationContext context) {
+			return new JsonPrimitive(Base64Utils.encodeToString(src));
+		}
+
+		@Override
+		public byte[] deserialize(JsonElement json, Type type, JsonDeserializationContext cxt) {
+			return Base64Utils.decodeFromString(json.getAsString());
+		}
+	}
+
+}