Add support for property hint

Create a new section in the meta-data called "hints" where users can
provide hints about a given property. The most basic use case for now
is to provide a list of values that a property can have. Each value may
have a description.

This sample JSON provides a basic example for a property called `foo.mode`
that exposes 3 values: "auto", "basic" and "advanced".

```
 "hints": [
    {
      "id": "foo.mode",
      "values": [
        {
          "value": "auto",
          "description": "Some smart description."
        },
        {
          "name": "basic"
        },
        {
          "name": "advanced"
        }
      ]
    }
]
```

This information can be read by tools (such as IDE) and offer an
auto-completion with the list of values.

Closes gh-2054

spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataAnnotationProcessorTests.java

@@ -27,6 +27,7 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.TemporaryFolder;
 import org.springframework.boot.configurationprocessor.metadata.ConfigurationMetadata;
+import org.springframework.boot.configurationprocessor.metadata.ItemHint;
 import org.springframework.boot.configurationsample.incremental.BarProperties;
 import org.springframework.boot.configurationsample.incremental.FooProperties;
 import org.springframework.boot.configurationsample.incremental.RenamedBarProperties;
@@ -58,6 +59,7 @@ import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
 import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsGroup;
+import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsHint;
 import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsProperty;
 import static org.springframework.boot.configurationprocessor.MetadataStore.METADATA_PATH;
 
@@ -324,12 +326,8 @@ public class ConfigurationMetadataAnnotationProcessorTests {
 	}
 
 	@Test
-	public void mergingOfAdditionalMetadata() throws Exception {
-		File metaInfFolder = new File(this.compiler.getOutputLocation(), "META-INF");
-		metaInfFolder.mkdirs();
-		File additionalMetadataFile = new File(metaInfFolder,
-				"additional-spring-configuration-metadata.json");
-		additionalMetadataFile.createNewFile();
+	public void mergingOfAdditionalProperty() throws Exception {
+		File additionalMetadataFile = createAdditionalMetadataFile();
 
 		JSONObject property = new JSONObject();
 		property.put("name", "foo");
@@ -339,10 +337,8 @@ public class ConfigurationMetadataAnnotationProcessorTests {
 		properties.put(property);
 		JSONObject additionalMetadata = new JSONObject();
 		additionalMetadata.put("properties", properties);
-		FileWriter writer = new FileWriter(additionalMetadataFile);
-		additionalMetadata.write(writer);
-		writer.flush();
 
+		writeMetadata(additionalMetadataFile, additionalMetadata);
 		ConfigurationMetadata metadata = compile(SimpleProperties.class);
 
 		assertThat(metadata, containsProperty("simple.comparator"));
@@ -352,6 +348,28 @@ public class ConfigurationMetadataAnnotationProcessorTests {
 						.fromSource(AdditionalMetadata.class));
 	}
 
+	@Test
+	public void mergingOfSimpleHint() throws Exception {
+		writeAdditionalHints(
+				ItemHint.newHint("simple.the-name", new ItemHint.ValueHint("boot", "Bla bla"),
+						new ItemHint.ValueHint("spring", null)));
+
+		ConfigurationMetadata metadata = compile(SimpleProperties.class);
+		assertThat(metadata, containsHint("simple.the-name")
+				.withValue(0, "boot", "Bla bla")
+				.withValue(1, "spring", null));
+	}
+
+	@Test
+	public void mergingOfHintWithNonCanonicalName() throws Exception {
+		writeAdditionalHints(
+				ItemHint.newHint("simple.theName", new ItemHint.ValueHint("boot", "Bla bla")));
+
+		ConfigurationMetadata metadata = compile(SimpleProperties.class);
+		assertThat(metadata, containsHint("simple.the-name")
+				.withValue(0, "boot", "Bla bla"));
+	}
+
 	@Test
 	public void incrementalBuild() throws Exception {
 		TestProject project = new TestProject(this.temporaryFolder, FooProperties.class,
@@ -448,6 +466,50 @@ public class ConfigurationMetadataAnnotationProcessorTests {
 		return processor.getMetadata();
 	}
 
+	private void writeAdditionalHints(ItemHint... hints) throws IOException {
+		File additionalMetadataFile = createAdditionalMetadataFile();
+
+		JSONArray hintsArray = new JSONArray();
+		for (ItemHint hint : hints) {
+			JSONObject jsonObject = new JSONObject();
+			jsonObject.put("name", hint.getName());
+			JSONArray valuesArray = new JSONArray();
+			for (ItemHint.ValueHint valueHint : hint.getValues()) {
+				JSONObject valueJsonObject = new JSONObject();
+				valueJsonObject.put("value", valueHint.getValue());
+				String description = valueHint.getDescription();
+				if (description != null) {
+					valueJsonObject.put("description", description);
+				}
+				valuesArray.put(valueJsonObject);
+			}
+			jsonObject.put("values", valuesArray);
+			hintsArray.put(jsonObject);
+		}
+		JSONObject additionalMetadata = new JSONObject();
+		additionalMetadata.put("hints", hints);
+		writeMetadata(additionalMetadataFile, additionalMetadata);
+	}
+
+	private File createAdditionalMetadataFile() throws IOException {
+		File metaInfFolder = new File(this.compiler.getOutputLocation(), "META-INF");
+		metaInfFolder.mkdirs();
+		File additionalMetadataFile = new File(metaInfFolder,
+				"additional-spring-configuration-metadata.json");
+		additionalMetadataFile.createNewFile();
+		return additionalMetadataFile;
+	}
+
+	private void writeMetadata(File metadataFile, JSONObject metadata) throws IOException {
+		FileWriter writer = new FileWriter(metadataFile);
+		try {
+			metadata.write(writer);
+		}
+		finally {
+			writer.close();
+		}
+	}
+
 	private static class AdditionalMetadata {
 
 	}

spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataMatchers.java

@@ -16,10 +16,14 @@
 
 package org.springframework.boot.configurationprocessor;
 
+import java.util.ArrayList;
+import java.util.List;
+
 import org.hamcrest.BaseMatcher;
 import org.hamcrest.Description;
 import org.hamcrest.Matcher;
 import org.springframework.boot.configurationprocessor.metadata.ConfigurationMetadata;
+import org.springframework.boot.configurationprocessor.metadata.ItemHint;
 import org.springframework.boot.configurationprocessor.metadata.ItemMetadata;
 import org.springframework.boot.configurationprocessor.metadata.ItemMetadata.ItemType;
 
@@ -27,6 +31,7 @@ import org.springframework.boot.configurationprocessor.metadata.ItemMetadata.Ite
  * Hamcrest {@link Matcher} to help test {@link ConfigurationMetadata}.
  *
  * @author Phillip Webb
+ * @author Stephane Nicoll
  */
 public class ConfigurationMetadataMatchers {
 
@@ -54,6 +59,10 @@ public class ConfigurationMetadataMatchers {
 		return new ContainsItemMatcher(ItemType.PROPERTY, name).ofType(type);
 	}
 
+	public static ContainsHintMatcher containsHint(String name) {
+		return new ContainsHintMatcher(name);
+	}
+
 	public static class ContainsItemMatcher extends BaseMatcher<ConfigurationMetadata> {
 
 		private final ItemType itemType;
@@ -89,7 +98,7 @@ public class ConfigurationMetadataMatchers {
 		@Override
 		public boolean matches(Object item) {
 			ConfigurationMetadata metadata = (ConfigurationMetadata) item;
-			ItemMetadata itemMetadata = getFirstPropertyWithName(metadata, this.name);
+			ItemMetadata itemMetadata = getFirstItemWithName(metadata, this.name);
 			if (itemMetadata == null) {
 				return false;
 			}
@@ -117,7 +126,7 @@ public class ConfigurationMetadataMatchers {
 		@Override
 		public void describeMismatch(Object item, Description description) {
 			ConfigurationMetadata metadata = (ConfigurationMetadata) item;
-			ItemMetadata property = getFirstPropertyWithName(metadata, this.name);
+			ItemMetadata property = getFirstItemWithName(metadata, this.name);
 			if (property == null) {
 				description.appendText("missing "
 						+ this.itemType.toString().toLowerCase() + " " + this.name);
@@ -179,7 +188,7 @@ public class ConfigurationMetadataMatchers {
 					this.sourceType, this.description, this.defaultValue, true);
 		}
 
-		private ItemMetadata getFirstPropertyWithName(ConfigurationMetadata metadata,
+		private ItemMetadata getFirstItemWithName(ConfigurationMetadata metadata,
 				String name) {
 			for (ItemMetadata item : metadata.getItems()) {
 				if (item.isOfItemType(this.itemType) && name.equals(item.getName())) {
@@ -191,4 +200,127 @@ public class ConfigurationMetadataMatchers {
 
 	}
 
+	public static class ContainsHintMatcher extends BaseMatcher<ConfigurationMetadata> {
+
+		private final String name;
+
+		private final List<ValueHintMatcher> values;
+
+		public ContainsHintMatcher(String name) {
+			this(name, new ArrayList<ValueHintMatcher>());
+		}
+
+		public ContainsHintMatcher(String name, List<ValueHintMatcher> values) {
+			this.name = name;
+			this.values = values;
+		}
+
+		@Override
+		public boolean matches(Object item) {
+			ConfigurationMetadata metadata = (ConfigurationMetadata) item;
+			ItemHint itemHint = getFirstHintWithName(metadata, this.name);
+			if (itemHint == null) {
+				return false;
+			}
+			if (this.name != null && !this.name.equals(itemHint.getName())) {
+				return false;
+			}
+			for (ValueHintMatcher value : this.values) {
+				if (!value.matches(itemHint)) {
+					return false;
+				}
+			}
+			return true;
+		}
+
+		@Override
+		public void describeMismatch(Object item, Description description) {
+			ConfigurationMetadata metadata = (ConfigurationMetadata) item;
+			ItemHint itemHint = getFirstHintWithName(metadata, this.name);
+			if (itemHint == null) {
+				description.appendText("missing hint " + this.name);
+			}
+			else {
+				description.appendText(
+						"was hint ").appendValue(itemHint);
+			}
+		}
+
+		@Override
+		public void describeTo(Description description) {
+			description.appendText("hints for " + this.name);
+			if (this.values != null) {
+				description.appendText(" values ").appendValue(this.values);
+			}
+		}
+
+		public ContainsHintMatcher withValue(int index, Object value, String description) {
+			List<ValueHintMatcher> values = new ArrayList<ValueHintMatcher>(this.values);
+			values.add(new ValueHintMatcher(index, value, description));
+			return new ContainsHintMatcher(this.name, values);
+		}
+
+		private ItemHint getFirstHintWithName(ConfigurationMetadata metadata,
+				String name) {
+			for (ItemHint hint : metadata.getHints()) {
+				if (name.equals(hint.getName())) {
+					return hint;
+				}
+			}
+			return null;
+		}
+
+	}
+
+	public static class ValueHintMatcher extends BaseMatcher<ItemHint> {
+		private final int index;
+		private final Object value;
+		private final String description;
+
+		public ValueHintMatcher(int index, Object value, String description) {
+			this.index = index;
+			this.value = value;
+			this.description = description;
+		}
+
+		@Override
+		public boolean matches(Object item) {
+			ItemHint hint = (ItemHint) item;
+			if (this.index + 1 > hint.getValues().size()) {
+				return false;
+			}
+			ItemHint.ValueHint valueHint = hint.getValues().get(this.index);
+			if (this.value != null
+				&& !this.value.equals(valueHint.getValue())) {
+				return false;
+			}
+			if (this.description != null
+				&& !this.description.equals(valueHint.getDescription())) {
+				return false;
+			}
+			return true;
+		}
+
+		@Override
+		public void describeTo(Description description) {
+			description.appendText("value hint at index '"+this.index+"'");
+			if (this.value != null) {
+				description.appendText(" value ").appendValue(this.value);
+			}
+			if (this.description != null) {
+				description.appendText(" description ").appendValue(this.description);
+			}
+		}
+
+		private ItemHint.ValueHint getValueHint(ItemHint hint) {
+			for (ItemHint.ValueHint valueHint : hint.getValues()) {
+				if (this.value.equals(valueHint.getValue())) {
+					return valueHint;
+				}
+			}
+			return null;
+		}
+
+	}
+
 }

spring-boot-tools/spring-boot-configuration-processor/src/test/java/org/springframework/boot/configurationprocessor/metadata/JsonMarshallerTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * 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.
@@ -26,6 +26,7 @@ import org.junit.Test;
 import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsGroup;
+import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsHint;
 import static org.springframework.boot.configurationprocessor.ConfigurationMetadataMatchers.containsProperty;
 
 /**
@@ -52,6 +53,9 @@ public class JsonMarshallerTests {
 		metadata.add(ItemMetadata.newProperty("f", null, null, null, null, null,
 				new Boolean[] { true, false }, false));
 		metadata.add(ItemMetadata.newGroup("d", null, null, null));
+		metadata.add(ItemHint.newHint("a.b"));
+		metadata.add(ItemHint.newHint("c", new ItemHint.ValueHint(123, "hey"),
+				new ItemHint.ValueHint(456, null)));
 		ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
 		JsonMarshaller marshaller = new JsonMarshaller();
 		marshaller.write(metadata, outputStream);
@@ -69,6 +73,8 @@ public class JsonMarshallerTests {
 		assertThat(read,
 				containsProperty("f").withDefaultValue(is(new boolean[] { true, false })));
 		assertThat(read, containsGroup("d"));
+		assertThat(read, containsHint("a.b"));
+		assertThat(read, containsHint("c").withValue(0, 123, "hey").withValue(1, 456, null));
 	}
 
 }