#833 - Migrate packages.

Changed the package structure to better reflect the different modules of the library. All client related code now lives in the client package, server related APIs in server with their respective WebMVC and WebFlux implementations in sub-packages.

Added migration script to allow users to easily migrate to the new structure and added reference documentation section on the migration.

Traversons built in defaulting to HAL HttpMessageConverters and LinkDiscoverer implementation now caused a cyclic relationship between the client and mediatype.hal packages. This has be fixed by looking up the defaults via a SpringFactories interface.

src/main/java/org/springframework/hateoas/client/JsonPathLinkDiscoverer.java

@@ -0,0 +1,180 @@
+/*
+ * Copyright 2012-2019 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.hateoas.client;
+
+import net.minidev.json.JSONArray;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Arrays;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.LinkRelation;
+import org.springframework.hateoas.Links;
+import org.springframework.http.MediaType;
+import org.springframework.util.Assert;
+
+import com.jayway.jsonpath.InvalidPathException;
+import com.jayway.jsonpath.JsonPath;
+
+/**
+ * {@link LinkDiscoverer} that uses {@link JsonPath} to find links inside a representation.
+ *
+ * @author Oliver Gierke
+ * @author Greg Turnquist
+ */
+public class JsonPathLinkDiscoverer implements LinkDiscoverer {
+
+	private final String pathTemplate;
+	private final List<MediaType> mediaTypes;
+
+	/**
+	 * Creates a new {@link JsonPathLinkDiscoverer} using the given path template supporting the given {@link MediaType}.
+	 * The template has to contain a single {@code %s} placeholder which will be replaced by the relation type.
+	 *
+	 * @param pathTemplate must not be {@literal null} or empty and contain a single placeholder.
+	 * @param mediaTypes the {@link MediaType}s to support.
+	 */
+	public JsonPathLinkDiscoverer(String pathTemplate, MediaType... mediaTypes) {
+
+		Assert.hasText(pathTemplate, "Path template must not be null!");
+		Assert.notNull(mediaTypes, "Primary MediaType must not be null!");
+
+		this.pathTemplate = pathTemplate;
+		this.mediaTypes = Arrays.asList(mediaTypes);
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.hateoas.LinkDiscoverer#findLinkWithRel(org.springframework.hateoas.LinkRelation, java.lang.String)
+	 */
+	@Override
+	public Optional<Link> findLinkWithRel(LinkRelation relation, String representation) {
+		return firstOrEmpty(findLinksWithRel(relation, representation));
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.hateoas.LinkDiscoverer#findLinkWithRel(org.springframework.hateoas.LinkRelation, java.io.InputStream)
+	 */
+	@Override
+	public Optional<Link> findLinkWithRel(LinkRelation relation, InputStream representation) {
+		return firstOrEmpty(findLinksWithRel(relation, representation));
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.hateoas.LinkDiscoverer#findLinksWithRel(org.springframework.hateoas.LinkRelation, java.lang.String)
+	 */
+	@Override
+	public Links findLinksWithRel(LinkRelation relation, String representation) {
+
+		Assert.notNull(relation, "LinkRelation must not be null!");
+
+		try {
+			Object parseResult = getExpression(relation).read(representation);
+			return createLinksFrom(parseResult, relation);
+		} catch (InvalidPathException e) {
+			return Links.NONE;
+		}
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.hateoas.LinkDiscoverer#findLinksWithRel(org.springframework.hateoas.LinkRelation, java.io.InputStream)
+	 */
+	@Override
+	public Links findLinksWithRel(LinkRelation relation, InputStream representation) {
+
+		Assert.notNull(relation, "LinkRelation must not be null!");
+
+		try {
+			Object parseResult = getExpression(relation).read(representation);
+			return createLinksFrom(parseResult, relation);
+		} catch (IOException e) {
+			throw new RuntimeException(e);
+		}
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.plugin.core.Plugin#supports(java.lang.Object)
+	 */
+	@Override
+	public boolean supports(MediaType delimiter) {
+
+		return this.mediaTypes.stream() //
+				.anyMatch(mediaType -> mediaType.isCompatibleWith(delimiter));
+	}
+
+	/**
+	 * Callback for each {@link LinkDiscoverer} to extract relevant attributes and generate a {@link Link}.
+	 *
+	 * @param element
+	 * @param rel
+	 * @return link
+	 */
+	protected Link extractLink(Object element, LinkRelation rel) {
+		return new Link(element.toString(), rel);
+	}
+
+	/**
+	 * Returns the {@link JsonPath} to find links with the given relation type.
+	 *
+	 * @param rel
+	 * @return
+	 */
+	private JsonPath getExpression(LinkRelation rel) {
+		return JsonPath.compile(String.format(pathTemplate, rel.value()));
+	}
+
+	/**
+	 * Creates {@link Link} instances from the given parse result.
+	 *
+	 * @param parseResult the result originating from parsing the source content using the JSON path expression.
+	 * @param rel the relation type that was parsed for.
+	 * @return
+	 */
+	private Links createLinksFrom(Object parseResult, LinkRelation rel) {
+
+		if (parseResult instanceof JSONArray) {
+
+			JSONArray jsonArray = (JSONArray) parseResult;
+
+			return jsonArray.stream() //
+					.flatMap(it -> JSONArray.class.isInstance(it) ? ((JSONArray) it).stream() : Stream.of(it)) //
+					.map(it -> extractLink(it, rel)) //
+					.collect(Collectors.collectingAndThen(Collectors.toList(), Links::of));
+		}
+
+		return Links.of(parseResult instanceof Map //
+				? extractLink(parseResult, rel) //
+				: new Link(parseResult.toString(), rel));
+	}
+
+	private static <T> Optional<T> firstOrEmpty(Iterable<T> source) {
+
+		Iterator<T> iterator = source.iterator();
+
+		return iterator.hasNext() ? Optional.of(iterator.next()) : Optional.empty();
+	}
+}

src/main/java/org/springframework/hateoas/client/LinkDiscoverer.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2012-2019 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.hateoas.client;
+
+import java.io.InputStream;
+import java.util.Optional;
+
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.LinkRelation;
+import org.springframework.hateoas.Links;
+import org.springframework.http.MediaType;
+import org.springframework.plugin.core.Plugin;
+
+/**
+ * Interface to allow discovering links by relation type from some source.
+ *
+ * @author Oliver Gierke
+ */
+public interface LinkDiscoverer extends Plugin<MediaType> {
+
+	/**
+	 * Finds a single link with the given relation type in the given {@link String} representation.
+	 *
+	 * @param rel must not be {@literal null} or empty.
+	 * @param representation must not be {@literal null}.
+	 * @return the first link with the given relation type found, or {@literal null} if none was found.
+	 */
+	default Optional<Link> findLinkWithRel(String rel, String representation) {
+		return findLinkWithRel(LinkRelation.of(rel), representation);
+	}
+
+	Optional<Link> findLinkWithRel(LinkRelation rel, String representation);
+
+	/**
+	 * Finds a single link with the given relation type in the given {@link InputStream} representation.
+	 *
+	 * @param rel must not be {@literal null} or empty.
+	 * @param representation must not be {@literal null}.
+	 * @return the first link with the given relation type found, or {@literal null} if none was found.
+	 */
+	default Optional<Link> findLinkWithRel(String rel, InputStream representation) {
+		return findLinkWithRel(LinkRelation.of(rel), representation);
+	}
+
+	/**
+	 * Finds a single link with the given {@link LinkRelation} in the given {@link InputStream} representation.
+	 *
+	 * @param rel must not be {@literal null}.
+	 * @param representation must not be {@literal null}.
+	 * @return the first link with the given relation type found, or {@literal null} if none was found.
+	 */
+	Optional<Link> findLinkWithRel(LinkRelation rel, InputStream representation);
+
+	/**
+	 * Returns all links with the given link relation found in the given {@link String} representation.
+	 *
+	 * @param rel must not be {@literal null} or empty.
+	 * @param representation must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 */
+	default Links findLinksWithRel(String rel, String representation) {
+		return findLinksWithRel(LinkRelation.of(rel), representation);
+	}
+
+	/**
+	 * Returns all links with the given {@link LinkRelation} found in the given {@link String} representation.
+	 *
+	 * @param rel must not be {@literal null}.
+	 * @param representation must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 */
+	Links findLinksWithRel(LinkRelation rel, String representation);
+
+	/**
+	 * Returns all links with the given link relation found in the given {@link InputStream} representation.
+	 *
+	 * @param rel must not be {@literal null} or empty.
+	 * @param representation must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 */
+	default Links findLinksWithRel(String rel, InputStream representation) {
+		return findLinksWithRel(LinkRelation.of(rel), representation);
+	}
+
+	/**
+	 * Returns all links with the given {@link LinkRelation} found in the given {@link InputStream} representation.
+	 *
+	 * @param rel must not be {@literal null}.
+	 * @param representation must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 */
+	Links findLinksWithRel(LinkRelation rel, InputStream representation);
+}

src/main/java/org/springframework/hateoas/client/LinkDiscoverers.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2013 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.hateoas.client;
+
+import java.util.Optional;
+
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.http.MediaType;
+import org.springframework.plugin.core.PluginRegistry;
+import org.springframework.util.Assert;
+
+/**
+ * Value object to wrap a {@link PluginRegistry} for {@link LinkDiscoverer} so that it's easier to inject them into
+ * clients wanting to lookup a {@link LinkDiscoverer} for a given {@link MediaTypes}.
+ *
+ * @author Oliver Gierke
+ */
+public class LinkDiscoverers {
+
+	private final PluginRegistry<LinkDiscoverer, MediaType> discoverers;
+
+	/**
+	 * Creates a new {@link LinkDiscoverers} instance with the given {@link PluginRegistry}.
+	 *
+	 * @param discoverers must not be {@literal null}.
+	 */
+	public LinkDiscoverers(PluginRegistry<LinkDiscoverer, MediaType> discoverers) {
+
+		Assert.notNull(discoverers, "Registry of LinkDiscoverer must not be null!");
+		this.discoverers = discoverers;
+	}
+
+	/**
+	 * Returns the {@link LinkDiscoverer} suitable for the given {@link MediaType}.
+	 *
+	 * @param mediaType
+	 * @return will never be {@literal null}.
+	 */
+	public Optional<LinkDiscoverer> getLinkDiscovererFor(MediaType mediaType) {
+		return discoverers.getPluginFor(mediaType);
+	}
+
+	/**
+	 * Returns the {@link LinkDiscoverer} suitable for the given media type.
+	 *
+	 * @param mediaType
+	 * @return
+	 */
+	public Optional<LinkDiscoverer> getLinkDiscovererFor(String mediaType) {
+		return getLinkDiscovererFor(MediaType.valueOf(mediaType));
+	}
+
+	/**
+	 * Returns the {@link LinkDiscoverer} suitable for the given {@link MediaType}.
+	 *
+	 * @param mediaType
+	 * @return will never be {@literal null}.
+	 */
+	public LinkDiscoverer getRequiredLinkDiscovererFor(MediaType mediaType) {
+		return discoverers.getRequiredPluginFor(mediaType);
+	}
+
+	/**
+	 * Returns the {@link LinkDiscoverer} suitable for the given media type.
+	 *
+	 * @param mediaType
+	 * @return
+	 */
+	public LinkDiscoverer getRequiredLinkDiscovererFor(String mediaType) {
+		return getRequiredLinkDiscovererFor(MediaType.valueOf(mediaType));
+	}
+}

src/main/java/org/springframework/hateoas/client/Rels.java

@@ -18,8 +18,6 @@ package org.springframework.hateoas.client;
 import java.util.Optional;
 
 import org.springframework.hateoas.Link;
-import org.springframework.hateoas.LinkDiscoverer;
-import org.springframework.hateoas.LinkDiscoverers;
 import org.springframework.http.MediaType;
 import org.springframework.util.Assert;
 

src/main/java/org/springframework/hateoas/client/Traverson.java

@@ -21,10 +21,8 @@ import lombok.RequiredArgsConstructor;
 import lombok.Value;
 
 import java.net.URI;
-import java.nio.charset.Charset;
 import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.Collection;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.List;
@@ -32,28 +30,21 @@ import java.util.Map;
 import java.util.stream.Collectors;
 
 import org.springframework.core.ParameterizedTypeReference;
+import org.springframework.core.io.support.SpringFactoriesLoader;
 import org.springframework.hateoas.Link;
-import org.springframework.hateoas.LinkDiscoverer;
-import org.springframework.hateoas.LinkDiscoverers;
-import org.springframework.hateoas.MediaTypes;
 import org.springframework.hateoas.UriTemplate;
 import org.springframework.hateoas.client.Rels.Rel;
-import org.springframework.hateoas.hal.HalLinkDiscoverer;
-import org.springframework.hateoas.hal.Jackson2HalModule;
+import org.springframework.hateoas.mediatype.hal.HalLinkDiscoverer;
 import org.springframework.http.HttpEntity;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.http.converter.HttpMessageConverter;
-import org.springframework.http.converter.StringHttpMessageConverter;
-import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
 import org.springframework.plugin.core.OrderAwarePluginRegistry;
 import org.springframework.util.Assert;
 import org.springframework.web.client.RestOperations;
 import org.springframework.web.client.RestTemplate;
 
-import com.fasterxml.jackson.databind.DeserializationFeature;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.jayway.jsonpath.JsonPath;
 
 /**
@@ -70,11 +61,21 @@ import com.jayway.jsonpath.JsonPath;
  */
 public class Traverson {
 
-	private static final LinkDiscoverers DEFAULT_LINK_DISCOVERERS;
+	private static final TraversonDefaults DEFAULTS;
 
 	static {
-		LinkDiscoverer discoverer = new HalLinkDiscoverer();
-		DEFAULT_LINK_DISCOVERERS = new LinkDiscoverers(OrderAwarePluginRegistry.of(discoverer));
+
+		List<TraversonDefaults> ALL_DEFAULTS = SpringFactoriesLoader.loadFactories(TraversonDefaults.class,
+				Traverson.class.getClassLoader());
+
+		Assert.isTrue(ALL_DEFAULTS.size() == 1,
+				() -> String.format("Expected to find only one TraversonDefaults instance, but found: ", //
+						ALL_DEFAULTS.stream() //
+								.map(Object::getClass) //
+								.map(Class::getName) //
+								.collect(Collectors.joining(", "))));
+
+		DEFAULTS = ALL_DEFAULTS.get(0);
 	}
 
 	private final URI baseUri;
@@ -108,8 +109,8 @@ public class Traverson {
 
 		this.mediaTypes = mediaTypes;
 		this.baseUri = baseUri;
-		this.discoverers = DEFAULT_LINK_DISCOVERERS;
 
+		setLinkDiscoverers(DEFAULTS.getLinkDiscoverers(mediaTypes));
 		setRestOperations(createDefaultTemplate(this.mediaTypes));
 	}
 
@@ -120,71 +121,17 @@ public class Traverson {
 	 * @return
 	 */
 	public static List<HttpMessageConverter<?>> getDefaultMessageConverters(MediaType... mediaTypes) {
-		return getDefaultMessageConverters(Arrays.asList(mediaTypes));
-	}
-
-	/**
-	 * Returns all {@link HttpMessageConverter}s that will be registered for the given {@link MediaType}s by default.
-	 *
-	 * @param mediaTypes must not be {@literal null}.
-	 * @return
-	 */
-	public static List<HttpMessageConverter<?>> getDefaultMessageConverters(List<MediaType> mediaTypes) {
-
-		Assert.notNull(mediaTypes, "Media types must not be null!");
-
-		List<HttpMessageConverter<?>> converters = new ArrayList<>();
-		converters.add(new StringHttpMessageConverter(Charset.forName("UTF-8")));
-
-		List<MediaType> halFlavors = getHalJsonFlavors(mediaTypes);
-
-		if (!halFlavors.isEmpty()) {
-			converters.add(getHalConverter(halFlavors));
-		}
-
-		return converters;
-	}
-
-	/**
-	 * Returns all HAL JSON compatible media types from the given list.
-	 *
-	 * @param mediaTypes must not be {@literal null}.
-	 * @return
-	 */
-	private static List<MediaType> getHalJsonFlavors(Collection<MediaType> mediaTypes) {
-
-		return mediaTypes.stream() //
-				.filter(MediaTypes.HAL_JSON::isCompatibleWith) //
-				.collect(Collectors.toList());
+		return DEFAULTS.getHttpMessageConverters(Arrays.asList(mediaTypes));
 	}
 
 	private static final RestOperations createDefaultTemplate(List<MediaType> mediaTypes) {
 
 		RestTemplate template = new RestTemplate();
-		template.setMessageConverters(getDefaultMessageConverters(mediaTypes));
+		template.setMessageConverters(DEFAULTS.getHttpMessageConverters(mediaTypes));
 
 		return template;
 	}
 
-	/**
-	 * Creates a new {@link HttpMessageConverter} to support HAL.
-	 *
-	 * @return
-	 */
-	private static final HttpMessageConverter<?> getHalConverter(List<MediaType> halFlavours) {
-
-		ObjectMapper mapper = new ObjectMapper();
-		mapper.registerModule(new Jackson2HalModule());
-		mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
-
-		MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
-
-		converter.setObjectMapper(mapper);
-		converter.setSupportedMediaTypes(halFlavours);
-
-		return converter;
-	}
-
 	/**
 	 * Configures the {@link RestOperations} to use. If {@literal null} is provided a default {@link RestTemplate} will be
 	 * used.
@@ -194,7 +141,10 @@ public class Traverson {
 	 */
 	public Traverson setRestOperations(RestOperations operations) {
 
-		this.operations = operations == null ? createDefaultTemplate(this.mediaTypes) : operations;
+		this.operations = operations == null //
+				? createDefaultTemplate(this.mediaTypes) //
+				: operations;
+
 		return this;
 	}
 
@@ -207,8 +157,11 @@ public class Traverson {
 	 */
 	public Traverson setLinkDiscoverers(List<? extends LinkDiscoverer> discoverer) {
 
-		this.discoverers = this.discoverers == null ? DEFAULT_LINK_DISCOVERERS
-				: new LinkDiscoverers(OrderAwarePluginRegistry.of(discoverer));
+		List<? extends LinkDiscoverer> defaultedDiscoverers = discoverer == null //
+				? DEFAULTS.getLinkDiscoverers(mediaTypes) //
+				: discoverer;
+
+		this.discoverers = new LinkDiscoverers(OrderAwarePluginRegistry.of(defaultedDiscoverers));
 
 		return this;
 	}

src/main/java/org/springframework/hateoas/client/TraversonDefaults.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2019 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.hateoas.client;
+
+import java.util.Collection;
+import java.util.List;
+
+import org.springframework.http.MediaType;
+import org.springframework.http.converter.HttpMessageConverter;
+
+/**
+ * SPI that exposes {@link HttpMessageConverter}s and {@link LinkDiscoverer}s to be used by default by
+ * {@link Traverson}. Not intended for public implementation.
+ *
+ * @author Oliver Drotbohm
+ */
+public interface TraversonDefaults {
+
+	/**
+	 * Returns the {@link HttpMessageConverter} instances to be registered for the given {@link MediaType}s.
+	 *
+	 * @param mediaTypes will never be {@literal null}.
+	 * @return
+	 */
+	List<HttpMessageConverter<?>> getHttpMessageConverters(Collection<MediaType> mediaTypes);
+
+	/**
+	 * Returns the {@link LinkDiscoverer}s to be registered by default for the given {@link MediaType}s.
+	 *
+	 * @param mediaTypes will never be {@literal null}.
+	 * @return
+	 */
+	List<LinkDiscoverer> getLinkDiscoverers(Collection<MediaType> mediaTypes);
+}