Polish contribution

This commit makes sure that each dependency link is HAL compliant (like
the project types in the metadata). Links are grouped by relation with
well known relations to be defined (i.e. 'how-to', 'reference', 'home'
and so forth).

Each link can be "templated" (in the HAL sense) and only `{bootVersion}`
is supported at the moment. This is useful if a precise documentation
section should reference to the actual Stpring Boot version chosen by the
user.

Closes gh-279

initializr-generator/src/main/groovy/io/spring/initializr/metadata/Dependency.groovy

@@ -91,8 +91,6 @@ class Dependency extends MetadataElement {
 
 	String repository
 
-	List<Link> links = []
-
 	@JsonInclude(JsonInclude.Include.NON_DEFAULT)
 	int weight
 
@@ -104,6 +102,8 @@ class Dependency extends MetadataElement {
 
 	List<String> keywords = []
 
+	List<Link> links = []
+
 	void setScope(String scope) {
 		if (!SCOPE_ALL.contains(scope)) {
 			throw new InvalidInitializrMetadataException("Invalid scope $scope must be one of $SCOPE_ALL")
@@ -163,6 +163,9 @@ class Dependency extends MetadataElement {
 						"Invalid dependency, id should have the form groupId:artifactId[:version] but got $id")
 			}
 		}
+		links.forEach { l ->
+			l.resolve()
+		}
 		updateVersionRanges(VersionParser.DEFAULT)
 	}
 

initializr-generator/src/main/groovy/io/spring/initializr/metadata/Link.groovy

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2015 the original author or authors.
+ * Copyright 2012-2017 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.
@@ -16,16 +16,92 @@
 
 package io.spring.initializr.metadata
 
+import com.fasterxml.jackson.annotation.JsonIgnore
+import com.fasterxml.jackson.annotation.JsonInclude
+import groovy.transform.ToString
+
 /**
- * @author Dave Syer
+ * Metadata for a link. Each link has a "relation" that potentially attaches a strong
+ * semantic to the nature of the link. The URI of the link itself can be templated by
+ * including variables in the form `{variableName}`.
+ * <p>
+ * An actual {@code URI} can be generated using {@code expand}, providing a mapping for
+ * those variables.
  *
+ * @author Dave Syer
+ * @author Stephane Nicoll
  */
+@ToString(ignoreNulls = true, includePackage = false)
 class Link {
-	
-	String id
-	
-	URL url
-	
+
+	private static final String VARIABLE_REGEX = "\\{(\\w+)\\}";
+
+	/**
+	 * The relation of the link.
+	 */
+	String rel;
+
+	/**
+	 * The URI the link is pointing to.
+	 */
+	String href
+
+	/**
+	 * Specify if the URI is templated.
+	 */
+	@JsonInclude(JsonInclude.Include.NON_DEFAULT)
+	boolean templated
+
+	@JsonIgnore
+	final Set<String> templateVariables = []
+
+	/**
+	 * A description of the link.
+	 */
+	@JsonInclude(JsonInclude.Include.NON_NULL)
 	String description
 
+	Set<String> getTemplateVariables() {
+		Collections.unmodifiableSet(templateVariables)
+	}
+
+	void setHref(String href) {
+		this.href = href
+	}
+
+	void resolve() {
+		if (!rel) {
+			throw new InvalidInitializrMetadataException(
+					"Invalid link $this: rel attribute is mandatory")
+		}
+		if (!href) {
+			throw new InvalidInitializrMetadataException(
+					"Invalid link $this: href attribute is mandatory")
+		}
+		def matcher = (href =~ VARIABLE_REGEX)
+		while (matcher.find()) {
+			def variable = matcher.group(1)
+			this.templateVariables << variable
+		}
+		this.templated = this.templateVariables
+	}
+
+	/**
+	 * Expand the link using the specified parameters.
+	 * @param parameters the parameters value
+	 * @return an URI where all variables have been expanded
+	 */
+	URI expand(Map<String, String> parameters) {
+		String result = href
+		templateVariables.forEach { var ->
+			Object value = parameters[var]
+			if (!value) {
+				throw new IllegalArgumentException(
+						"Could not explan $href, missing value for '$var'")
+			}
+			result = result.replace("{$var}", value.toString())
+		}
+		new URI(result)
+	}
+
 }

initializr-generator/src/test/groovy/io/spring/initializr/metadata/DependencyTests.groovy

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2016 the original author or authors.
+ * Copyright 2012-2017 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.
@@ -123,6 +123,15 @@ class DependencyTests {
 		dependency.resolve()
 	}
 
+	@Test
+	void invalidLink() {
+		def dependency = new Dependency(id : 'foo')
+		dependency.links << new Link(href: 'https://example.com')
+
+		thrown.expect(InvalidInitializrMetadataException)
+		dependency.resolve()
+	}
+
 	@Test
 	void generateIdWithNoGroupId() {
 		def dependency = new Dependency()

initializr-generator/src/test/groovy/io/spring/initializr/metadata/LinkTests.groovy

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2012-2017 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 io.spring.initializr.metadata
+
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.ExpectedException
+
+/**
+ * Tests for {@link Link}.
+ *
+ * @author Stephane Nicoll
+ */
+class LinkTests {
+
+	@Rule
+	public final ExpectedException thrown = ExpectedException.none()
+
+	@Test
+	void resolveInvalidLinkNoRel() {
+		def link = new Link(href: 'https://example.com')
+		thrown.expect(InvalidInitializrMetadataException)
+		link.resolve()
+	}
+
+	@Test
+	void resolveInvalidLinkNoHref() {
+		def link = new Link(rel: 'reference', description: 'foo doc')
+
+		thrown.expect(InvalidInitializrMetadataException)
+		link.resolve()
+	}
+
+	@Test
+	void resolveLinkNoVariables() {
+		def link = new Link(rel: 'reference', href: 'https://example.com/2')
+		link.resolve()
+		assert !link.templated
+		assert link.templateVariables.size() == 0
+	}
+
+	@Test
+	void resolveLinkWithVariables() {
+		def link = new Link(rel: 'reference', href: 'https://example.com/{a}/2/{b}')
+		link.resolve()
+		assert link.templated
+		assert link.templateVariables.size() == 2
+		assert link.templateVariables.contains('a')
+		assert link.templateVariables.contains('b')
+	}
+
+	@Test
+	void expandLink() {
+		def link = new Link(rel: 'reference', href: 'https://example.com/{a}/2/{b}')
+		link.resolve()
+		assert link.expand(['a': 'test', 'b': 'another']) ==
+				new URI('https://example.com/test/2/another')
+	}
+
+	@Test
+	void expandLinkWithSameAttributeAtTwoPlaces() {
+		def link = new Link(rel: 'reference', href: 'https://example.com/{a}/2/{a}')
+		link.resolve()
+		assert link.expand(['a': 'test', 'b': 'another']) ==
+				new URI('https://example.com/test/2/test')
+	}
+
+	@Test
+	void expandLinkMissingVariable() {
+		def link = new Link(rel: 'reference', href: 'https://example.com/{a}/2/{b}')
+		link.resolve()
+
+		thrown.expect(IllegalArgumentException)
+		thrown.expectMessage("missing value for 'b'")
+		link.expand(['a': 'test'])
+	}
+
+}

initializr-generator/src/test/resources/application-test-default.yml

@@ -39,6 +39,12 @@ initializr:
           description: Web dependency description
           facets:
             - web
+          links:
+            - rel: guide
+              href: https://example.com/guide
+              description: Building a RESTful Web Service
+            - rel: reference
+              href: https://example.com/doc
         - name: Security
           id: security
         - name: Data JPA
@@ -55,6 +61,14 @@ initializr:
           keywords:
             - thefoo
             - dafoo
+          links:
+            - rel: guide
+              href: https://example.com/guide1
+            - rel: reference
+              href: https://example.com/{bootVersion}/doc
+            - rel: guide
+              href: https://example.com/guide2
+              description: Some guide for foo
         - name: Bar
           id: org.acme:bar
           version: 2.1.0