Add support for property deprecation

Previously, an item could only have a 'deprecated' boolean flag to
indicate that the property is deprecated. It is desirable to provide an
additional description for the deprecation as well as the name of the
property to use instead.

The `deprecated` boolean flag is now supported. Instead, a `deprecated`
object can be specified with two optional attributes: `reason` to provide
an explanation for the deprecation and `replacement` to refer to the
property that should be used instead. If none of them is present, an
empty deprecation object should be set.

For backward compatibility, the `deprecated` field is still set.

Deprecation information can only set via manual meta-data.

Closes gh-3449

spring-boot-tools/spring-boot-configuration-metadata/src/main/java/org/springframework/boot/configurationmetadata/ConfigurationMetadataProperty.java

@@ -46,7 +46,7 @@ public class ConfigurationMetadataProperty {
 
 	private final List<ValueProvider> valueProviders = new ArrayList<ValueProvider>();
 
-	private boolean deprecated;
+	private Deprecation deprecation;
 
 	/**
 	 * The full identifier of the property, in lowercase dashed form (e.g.
@@ -155,15 +155,25 @@ public class ConfigurationMetadataProperty {
 	}
 
 	/**
-	 * Specify if the property is deprecated.
-	 * @return if the property is deprecated
+	 * The {@link Deprecation} for this property, if any.
+	 * @return the deprecation
+	 * @see #isDeprecated()
 	 */
-	public boolean isDeprecated() {
-		return this.deprecated;
+	public Deprecation getDeprecation() {
+		return deprecation;
 	}
 
-	public void setDeprecated(boolean deprecated) {
-		this.deprecated = deprecated;
+	public void setDeprecation(Deprecation deprecation) {
+		this.deprecation = deprecation;
+	}
+
+	/**
+	 * Specify if the property is deprecated.
+	 * @return if the property is deprecated
+	 * @see #getDeprecation()
+	 */
+	public boolean isDeprecated() {
+		return this.deprecation != null;
 	}
 
 }

spring-boot-tools/spring-boot-configuration-metadata/src/main/java/org/springframework/boot/configurationmetadata/Deprecation.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2012-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.boot.configurationmetadata;
+
+/**
+ * Indicate that a property is deprecated. Provide additional information about the
+ * deprecation.
+ *
+ * @author Stephane Nicoll
+ * @since 1.3.0
+ */
+public class Deprecation {
+
+	private String reason;
+
+	private String replacement;
+
+	/**
+	 * A reason why the related property is deprecated, if any. Can be multi-lines.
+	 * @return the deprecation reason
+	 */
+	public String getReason() {
+		return reason;
+	}
+
+	public void setReason(String reason) {
+		this.reason = reason;
+	}
+
+	/**
+	 * The full name of the property that replaces the related deprecated property, if any.
+	 * @return the replacement property name
+	 */
+	public String getReplacement() {
+		return replacement;
+	}
+
+	public void setReplacement(String replacement) {
+		this.replacement = replacement;
+	}
+
+	@Override
+	public String toString() {
+		return "Deprecation{" + "reason='" + reason + '\'' + ", replacement='" + replacement + '\'' + '}';
+	}
+
+}

spring-boot-tools/spring-boot-configuration-metadata/src/main/java/org/springframework/boot/configurationmetadata/JsonReader.java

@@ -109,7 +109,7 @@ class JsonReader {
 		item.setShortDescription(this.descriptionExtractor
 				.getShortDescription(description));
 		item.setDefaultValue(readItemValue(json.opt("defaultValue")));
-		item.setDeprecated(json.optBoolean("deprecated", false));
+		item.setDeprecation(parseDeprecation(json));
 		item.setSourceType(json.optString("sourceType", null));
 		item.setSourceMethod(json.optString("sourceMethod", null));
 		return item;
@@ -152,6 +152,17 @@ class JsonReader {
 		return hint;
 	}
 
+	private Deprecation parseDeprecation(JSONObject object) {
+		if (object.has("deprecation")) {
+			JSONObject deprecationJsonObject = object.getJSONObject("deprecation");
+			Deprecation deprecation = new Deprecation();
+			deprecation.setReason(deprecationJsonObject.optString("reason", null));
+			deprecation.setReplacement(deprecationJsonObject.optString("replacement", null));
+			return deprecation;
+		}
+		return (object.optBoolean("deprecated") ? new Deprecation() : null);
+	}
+
 	private Object readItemValue(Object value) {
 		if (value instanceof JSONArray) {
 			JSONArray array = (JSONArray) value;

spring-boot-tools/spring-boot-configuration-metadata/src/test/java/org/springframework/boot/configurationmetadata/JsonReaderTests.java

@@ -24,7 +24,9 @@ import org.json.JSONException;
 import org.junit.Test;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
 
 /**
  * Tests for {@link JsonReader}
@@ -130,6 +132,30 @@ public class JsonReaderTests extends AbstractConfigurationMetadataTests {
 		assertProperty(item, "spring.root.name", "spring.root.name", String.class, null);
 	}
 
+	@Test
+	public void deprecatedMetadata() throws IOException {
+		RawConfigurationMetadata rawMetadata = readFor("deprecated");
+		List<ConfigurationMetadataItem> items = rawMetadata.getItems();
+		assertEquals(3, items.size());
+
+		ConfigurationMetadataItem item = items.get(0);
+		assertProperty(item, "server.port", "server.port", Integer.class, null);
+		assertTrue(item.isDeprecated());
+		assertEquals("Server namespace has moved to spring.server", item.getDeprecation().getReason());
+		assertEquals("server.spring.port", item.getDeprecation().getReplacement());
+
+		ConfigurationMetadataItem item2 = items.get(1);
+		assertProperty(item2, "server.cluster-name", "server.cluster-name", String.class, null);
+		assertTrue(item2.isDeprecated());
+		assertEquals(null, item2.getDeprecation().getReason());
+		assertEquals(null, item2.getDeprecation().getReplacement());
+
+		ConfigurationMetadataItem item3 = items.get(2);
+		assertProperty(item3, "spring.server.name", "spring.server.name", String.class, null);
+		assertFalse(item3.isDeprecated());
+		assertEquals(null, item3.getDeprecation());
+	}
+
 	RawConfigurationMetadata readFor(String path) throws IOException {
 		return this.reader.read(getInputStreamFor(path), DEFAULT_CHARSET);
 	}

spring-boot-tools/spring-boot-configuration-metadata/src/test/resources/metadata/configuration-metadata-deprecated.json

@@ -0,0 +1,22 @@
+{
+	"properties": [
+		{
+			"name": "server.port",
+			"type": "java.lang.Integer",
+			"deprecation": {
+				"reason": "Server namespace has moved to spring.server",
+				"replacement": "server.spring.port"
+			}
+		},
+		{
+			"name": "server.cluster-name",
+			"type": "java.lang.String",
+			"deprecated": true
+		},
+		{
+			"name": "spring.server.name",
+			"type": "java.lang.String",
+			"deprecated": false
+		}
+	]
+}