Add configuration meta-data parser

Add a new `spring-boot-configuration-metadata` module that provides an
API to manipulate Spring Boot configuration meta-data. Can read meta-data
from arbitrary locations, though the standard
`META-INF/spring-configuration-metadata.json` location must be preferred.

Closes gh-1970

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

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2012-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.boot.configurationmetadata;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.junit.Rule;
+import org.junit.rules.ExpectedException;
+
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.Resource;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+
+/**
+ *
+ * @author Stephane Nicoll
+ */
+public abstract class AbstractConfigurationMetadataTests {
+
+	@Rule
+	public final ExpectedException thrown = ExpectedException.none();
+
+	protected void assertSource(ConfigurationMetadataSource actual, String groupId, String type, String sourceType) {
+		assertNotNull(actual);
+		assertEquals(groupId, actual.getGroupId());
+		assertEquals(type, actual.getType());
+		assertEquals(sourceType, actual.getSourceType());
+	}
+
+	protected void assertProperty(ConfigurationMetadataProperty actual, String id, String name,
+			Class<?> type, Object defaultValue) {
+		assertNotNull(actual);
+		assertEquals(id, actual.getId());
+		assertEquals(name, actual.getName());
+		String typeName = type != null ? type.getName() : null;
+		assertEquals(typeName, actual.getType());
+		assertEquals(defaultValue, actual.getDefaultValue());
+	}
+
+	protected void assertItem(ConfigurationMetadataItem actual, String sourceType) {
+		assertNotNull(actual);
+		assertEquals(sourceType, actual.getSourceType());
+	}
+
+	protected InputStream getInputStreamFor(String name) throws IOException {
+		Resource r = new ClassPathResource("metadata/configuration-metadata-" + name + ".json");
+		return r.getInputStream();
+	}
+}

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

@@ -0,0 +1,200 @@
+/*
+ * Copyright 2012-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.boot.configurationmetadata;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Map;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Tests for {@link ConfigurationMetadataRepository}.
+ *
+ * @author Stephane Nicoll
+ */
+public class ConfigurationMetadataRepositoryJsonBuilderTests extends AbstractConfigurationMetadataTests {
+
+
+	@Test
+	public void nullResource() throws IOException {
+		thrown.expect(IllegalArgumentException.class);
+		ConfigurationMetadataRepositoryJsonBuilder.create().withJsonResource(null);
+	}
+
+	@Test
+	public void simpleRepository() throws IOException {
+		InputStream foo = getInputStreamFor("foo");
+		try {
+			ConfigurationMetadataRepository repo = ConfigurationMetadataRepositoryJsonBuilder.create()
+					.withJsonResource(foo)
+					.build();
+			validateFoo(repo);
+			assertEquals(1, repo.getAllGroups().size());
+
+			contains(repo.getAllProperties(), "spring.foo.name", "spring.foo.description", "spring.foo.counter");
+			assertEquals(3, repo.getAllProperties().size());
+		}
+		finally {
+			foo.close();
+		}
+	}
+
+	@Test
+	public void severalRepositoriesNoConflict() throws IOException {
+		InputStream foo = getInputStreamFor("foo");
+		InputStream bar = getInputStreamFor("bar");
+		try {
+			ConfigurationMetadataRepository repo = ConfigurationMetadataRepositoryJsonBuilder.create()
+					.withJsonResource(foo)
+					.withJsonResource(bar)
+					.build();
+			validateFoo(repo);
+			validateBar(repo);
+			assertEquals(2, repo.getAllGroups().size());
+
+			contains(repo.getAllProperties(), "spring.foo.name", "spring.foo.description", "spring.foo.counter",
+					"spring.bar.name", "spring.bar.description", "spring.bar.counter");
+			assertEquals(6, repo.getAllProperties().size());
+		}
+		finally {
+			foo.close();
+			bar.close();
+		}
+	}
+
+	@Test
+	public void repositoryWithRoot() throws IOException {
+		InputStream foo = getInputStreamFor("foo");
+		InputStream root = getInputStreamFor("root");
+		try {
+			ConfigurationMetadataRepository repo = ConfigurationMetadataRepositoryJsonBuilder.create()
+					.withJsonResource(foo)
+					.withJsonResource(root)
+					.build();
+			validateFoo(repo);
+			assertEquals(2, repo.getAllGroups().size());
+
+			contains(repo.getAllProperties(), "spring.foo.name", "spring.foo.description", "spring.foo.counter",
+					"spring.root.name", "spring.root2.name");
+			assertEquals(5, repo.getAllProperties().size());
+		}
+		finally {
+			foo.close();
+			root.close();
+		}
+	}
+
+	@Test
+	public void severalRepositoriesIdenticalGroups() throws IOException {
+		InputStream foo = getInputStreamFor("foo");
+		InputStream foo2 = getInputStreamFor("foo2");
+		try {
+			ConfigurationMetadataRepository repo = ConfigurationMetadataRepositoryJsonBuilder.create()
+					.withJsonResource(foo)
+					.withJsonResource(foo2)
+					.build();
+			assertEquals(1, repo.getAllGroups().size());
+			ConfigurationMetadataGroup group = repo.getAllGroups().get("spring.foo");
+			contains(group.getSources(), "org.acme.Foo", "org.acme.Foo2", "org.springframework.boot.FooProperties");
+			assertEquals(3, group.getSources().size());
+			contains(group.getProperties(), "spring.foo.name", "spring.foo.description", "spring.foo.counter",
+					"spring.foo.enabled", "spring.foo.type");
+			assertEquals(5, group.getProperties().size());
+			contains(repo.getAllProperties(), "spring.foo.name", "spring.foo.description", "spring.foo.counter",
+					"spring.foo.enabled", "spring.foo.type");
+			assertEquals(5, repo.getAllProperties().size());
+		}
+		finally {
+			foo.close();
+			foo2.close();
+		}
+	}
+
+	@Test
+	public void builderInstancesAreIsolated() throws IOException {
+		InputStream foo = getInputStreamFor("foo");
+		InputStream bar = getInputStreamFor("bar");
+		try {
+			ConfigurationMetadataRepositoryJsonBuilder builder = ConfigurationMetadataRepositoryJsonBuilder.create();
+			ConfigurationMetadataRepository firstRepo = builder
+					.withJsonResource(foo)
+					.build();
+			validateFoo(firstRepo);
+
+			ConfigurationMetadataRepository secondRepo = builder
+					.withJsonResource(bar)
+					.build();
+			validateFoo(secondRepo);
+			validateBar(secondRepo);
+
+			// first repo not impacted by second build
+			assertNotEquals(firstRepo, secondRepo);
+			assertEquals(1, firstRepo.getAllGroups().size());
+			assertEquals(3, firstRepo.getAllProperties().size());
+			assertEquals(2, secondRepo.getAllGroups().size());
+			assertEquals(6, secondRepo.getAllProperties().size());
+		}
+		finally {
+			foo.close();
+			bar.close();
+		}
+	}
+
+	private void validateFoo(ConfigurationMetadataRepository repo) {
+		ConfigurationMetadataGroup group = repo.getAllGroups().get("spring.foo");
+		contains(group.getSources(), "org.acme.Foo", "org.springframework.boot.FooProperties");
+		ConfigurationMetadataSource source = group.getSources().get("org.acme.Foo");
+		contains(source.getProperties(), "spring.foo.name", "spring.foo.description");
+		assertEquals(2, source.getProperties().size());
+		ConfigurationMetadataSource source2 = group.getSources().get("org.springframework.boot.FooProperties");
+		contains(source2.getProperties(), "spring.foo.name", "spring.foo.counter");
+		assertEquals(2, source2.getProperties().size());
+		validatePropertyHints(repo.getAllProperties().get("spring.foo.name"), 0, 0);
+		validatePropertyHints(repo.getAllProperties().get("spring.foo.description"), 0, 0);
+		validatePropertyHints(repo.getAllProperties().get("spring.foo.counter"), 1, 1);
+	}
+
+	private void validateBar(ConfigurationMetadataRepository repo) {
+		ConfigurationMetadataGroup group = repo.getAllGroups().get("spring.bar");
+		contains(group.getSources(), "org.acme.Bar", "org.springframework.boot.BarProperties");
+		ConfigurationMetadataSource source = group.getSources().get("org.acme.Bar");
+		contains(source.getProperties(), "spring.bar.name", "spring.bar.description");
+		assertEquals(2, source.getProperties().size());
+		ConfigurationMetadataSource source2 = group.getSources().get("org.springframework.boot.BarProperties");
+		contains(source2.getProperties(), "spring.bar.name", "spring.bar.counter");
+		assertEquals(2, source2.getProperties().size());
+		validatePropertyHints(repo.getAllProperties().get("spring.bar.name"), 0, 0);
+		validatePropertyHints(repo.getAllProperties().get("spring.bar.description"), 2, 2);
+		validatePropertyHints(repo.getAllProperties().get("spring.bar.counter"), 0, 0);
+	}
+
+	private void validatePropertyHints(ConfigurationMetadataProperty property, int valueHints, int valueProviders) {
+		assertEquals(valueHints, property.getValueHints().size());
+		assertEquals(valueProviders, property.getValueHints().size());
+	}
+
+	private void contains(Map<String, ?> source, String... keys) {
+		for (String key : keys) {
+			assertTrue("Item '" + key + "' not found. Got " + source.keySet(), source.containsKey(key));
+		}
+	}
+}

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

@@ -0,0 +1,172 @@
+/*
+ * Copyright 2012-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.boot.configurationmetadata;
+
+import java.io.IOException;
+import java.nio.charset.Charset;
+import java.util.List;
+
+import org.json.JSONException;
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+
+/**
+ * Tests for {@link JsonReader}
+ *
+ * @author Stephane Nicoll
+ */
+public class JsonReaderTests extends AbstractConfigurationMetadataTests {
+
+	private static final Charset DEFAULT_CHARSET = Charset.forName("UTF-8");
+
+	private final JsonReader reader = new JsonReader();
+
+	@Test
+	public void emptyMetadata() throws IOException {
+		RawConfigurationMetadata rawMetadata = readFor("empty");
+		assertEquals(0, rawMetadata.getSources().size());
+		assertEquals(0, rawMetadata.getItems().size());
+	}
+
+	@Test
+	public void invalidMetadata() throws IOException {
+		thrown.expect(JSONException.class);
+		readFor("invalid");
+	}
+
+	@Test
+	public void simpleMetadata() throws IOException {
+		RawConfigurationMetadata rawMetadata = readFor("foo");
+		List<ConfigurationMetadataSource> sources = rawMetadata.getSources();
+		assertEquals(2, sources.size());
+		List<ConfigurationMetadataItem> items = rawMetadata.getItems();
+		assertEquals(4, items.size());
+		List<ConfigurationMetadataHint> hints = rawMetadata.getHints();
+		assertEquals(1, hints.size());
+
+		ConfigurationMetadataSource source = sources.get(0);
+		assertSource(source, "spring.foo", "org.acme.Foo", "org.acme.config.FooApp");
+		assertEquals("foo()", source.getSourceMethod());
+		assertEquals("This is Foo.", source.getDescription());
+		assertEquals("This is Foo.", source.getShortDescription());
+
+		ConfigurationMetadataItem item = items.get(0);
+		assertProperty(item, "spring.foo.name", "name", String.class, null);
+		assertItem(item, "org.acme.Foo");
+		ConfigurationMetadataItem item2 = items.get(1);
+		assertProperty(item2, "spring.foo.description", "description", String.class, "FooBar");
+		assertEquals("Foo description.", item2.getDescription());
+		assertEquals("Foo description.", item2.getShortDescription());
+		assertNull(item2.getSourceMethod());
+		assertItem(item2, "org.acme.Foo");
+
+		ConfigurationMetadataHint hint = hints.get(0);
+		assertEquals("spring.foo.counter", hint.getId());
+		assertEquals(1, hint.getValueHints().size());
+		ValueHint valueHint = hint.getValueHints().get(0);
+		assertEquals(42, valueHint.getValue());
+		assertEquals("Because that's the answer to any question, choose it. \nReally.",
+				valueHint.getDescription());
+		assertEquals("Because that's the answer to any question, choose it.",
+				valueHint.getShortDescription());
+		assertEquals(1, hint.getValueProviders().size());
+		ValueProvider valueProvider = hint.getValueProviders().get(0);
+		assertEquals("handle-as", valueProvider.getName());
+		assertEquals(1, valueProvider.getParameters().size());
+		assertEquals(Integer.class.getName(), valueProvider.getParameters().get("target"));
+	}
+
+	@Test
+	public void metadataHints() throws IOException {
+		RawConfigurationMetadata rawMetadata = readFor("bar");
+		List<ConfigurationMetadataHint> hints = rawMetadata.getHints();
+		assertEquals(1, hints.size());
+
+		ConfigurationMetadataHint hint = hints.get(0);
+		assertEquals("spring.bar.description", hint.getId());
+		assertEquals(2, hint.getValueHints().size());
+		ValueHint valueHint = hint.getValueHints().get(0);
+		assertEquals("one", valueHint.getValue());
+		assertEquals("One.", valueHint.getDescription());
+		ValueHint valueHint2 = hint.getValueHints().get(1);
+		assertEquals("two", valueHint2.getValue());
+		assertEquals(null, valueHint2.getDescription());
+
+		assertEquals(2, hint.getValueProviders().size());
+		ValueProvider valueProvider = hint.getValueProviders().get(0);
+		assertEquals("handle-as", valueProvider.getName());
+		assertEquals(1, valueProvider.getParameters().size());
+		assertEquals(String.class.getName(), valueProvider.getParameters().get("target"));
+		ValueProvider valueProvider2 = hint.getValueProviders().get(1);
+		assertEquals("any", valueProvider2.getName());
+		assertEquals(0, valueProvider2.getParameters().size());
+	}
+
+	@Test
+	public void rootMetadata() throws IOException {
+		RawConfigurationMetadata rawMetadata = readFor("root");
+		List<ConfigurationMetadataSource> sources = rawMetadata.getSources();
+		assertEquals(0, sources.size());
+		List<ConfigurationMetadataItem> items = rawMetadata.getItems();
+		assertEquals(2, items.size());
+
+		ConfigurationMetadataItem item = items.get(0);
+		assertProperty(item, "spring.root.name", "spring.root.name", String.class, null);
+	}
+
+	@Test
+	public void extractShortDescription() {
+		assertEquals("My short description.", JsonReader.extractShortDescription(
+				"My short description. More stuff."));
+	}
+
+	@Test
+	public void extractShortDescriptionNewLineBeforeDot() {
+		assertEquals("My short description.", JsonReader.extractShortDescription(
+				"My short\ndescription.\nMore stuff."));
+	}
+
+	@Test
+	public void extractShortDescriptionNewLineBeforeDotWithSpaces() {
+		assertEquals("My short description.", JsonReader.extractShortDescription(
+				"My short  \n description.  \nMore stuff."));
+	}
+
+	@Test
+	public void extractShortDescriptionNoDot() {
+		assertEquals("My short description", JsonReader.extractShortDescription(
+				"My short description"));
+	}
+
+	@Test
+	public void extractShortDescriptionNoDotMultipleLines() {
+		assertEquals("My short description", JsonReader.extractShortDescription(
+				"My short description  \n More stuff"));
+	}
+
+	@Test
+	public void extractShortDescriptionNull() {
+		assertEquals(null, JsonReader.extractShortDescription(null));
+	}
+
+	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-bar.json

@@ -0,0 +1,65 @@
+{
+  "groups": [
+    {
+      "name": "spring.bar",
+      "type": "org.acme.Bar",
+      "sourceType": "org.acme.config.BarApp",
+      "sourceMethod": "bar()",
+      "description": "This is Bar."
+    },
+    {
+      "name": "spring.bar",
+      "type": "org.springframework.boot.BarProperties"
+    }
+  ],
+  "properties": [
+    {
+      "name": "spring.bar.name",
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Bar"
+    },
+    {
+      "name": "spring.bar.description",
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Bar",
+      "description": "Bar description.",
+      "defaultValue": "BarFoo"
+    },
+    {
+      "name": "spring.bar.name",
+      "type": "java.lang.String",
+      "sourceType": "org.springframework.boot.BarProperties"
+    },
+    {
+      "name": "spring.bar.counter",
+      "type": "java.lang.Integer",
+      "sourceType": "org.springframework.boot.BarProperties",
+      "defaultValue": 0
+    }
+  ],
+  "hints": [
+    {
+      "name": "spring.bar.description",
+      "values": [
+        {
+          "value": "one",
+          "description": "One."
+        },
+        {
+          "value": "two"
+        }
+      ],
+      "providers": [
+        {
+          "name": "handle-as",
+          "parameters": {
+            "target": "java.lang.String"
+          }
+        },
+        {
+          "name": "any"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "foo": "bar"
+}

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

@@ -0,0 +1,59 @@
+{
+  "groups": [
+    {
+      "name": "spring.foo",
+      "type": "org.acme.Foo",
+      "sourceType": "org.acme.config.FooApp",
+      "sourceMethod": "foo()",
+      "description": "This is Foo."
+    },
+    {
+      "name": "spring.foo",
+      "type": "org.springframework.boot.FooProperties"
+    }
+  ],
+  "properties": [
+    {
+      "name": "spring.foo.name",
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Foo"
+    },
+    {
+      "name": "spring.foo.description",
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Foo",
+      "description": "Foo description.",
+      "defaultValue": "FooBar"
+    },
+    {
+      "name": "spring.foo.name",
+      "type": "java.lang.String",
+      "sourceType": "org.springframework.boot.FooProperties"
+    },
+    {
+      "name": "spring.foo.counter",
+      "type": "java.lang.Integer",
+      "sourceType": "org.springframework.boot.FooProperties",
+      "defaultValue": 0
+    }
+  ],
+  "hints": [
+    {
+      "name": "spring.foo.counter",
+      "values": [
+        {
+          "value": 42,
+          "description": "Because that's the answer to any question, choose it. \nReally."
+        }
+      ],
+      "providers": [
+        {
+          "name": "handle-as",
+          "parameters": {
+            "target": "java.lang.Integer"
+          }
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "groups": [
+    {
+      "name": "spring.foo",
+      "type": "org.acme.Foo2",
+      "sourceType": "org.acme.config.FooApp",
+      "sourceMethod": "foo2()",
+      "description": "This is Foo2."
+    }
+  ],
+  "properties": [
+    {
+      "name": "spring.foo.enabled",
+      "type": "java.lang.Boolean",
+      "sourceType": "org.acme.Foo2"
+    },
+    {
+      "name": "spring.foo.type",
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Foo2"
+    }
+  ]
+}

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

@@ -0,0 +1,8 @@
+{
+  "properties": [
+    {
+      "type": "java.lang.String",
+      "sourceType": "org.acme.Invalid"
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+{
+  "properties": [
+    {
+      "name": "spring.root.name",
+      "type": "java.lang.String"
+    },
+    {
+      "name": "spring.root2.name"
+    }
+  ]
+}