DATACMNS-330, DATACMNS-331 - Advanced web integration.

Added PagedResourcesAssembler to easily convert Page instances into a PagedResource instance and automatically build the required previous/next links based on the PageableHandlerMethodArgumentResolver present in the MVC configuration. The assembler can either be injected into a Spring MVC controller or a controller method. The latter will then assume the controller methods URI to be used as pagination link base.

Added @EnableSpringDataWebSupport to automatically register HandlerMethodArgumentResolvers for Pageable and Sort as well as a DomainClassConverter that will allow the usage of domain types being managed by Spring Data repositories in controller method signatures. In case Spring HATEOAS is present on the classpath, we'll also register a PagedResourcesAssembler for injection as well as the appropriate HandlerMethodArgumentResolver for injection into controller methods.

Adapted Sonargraph configuration accordingly. Upgraded to Spring HATEOAS 0.6.0.BUILD-SNAPSHOT.

Author: odrotbohm

Spring Data Commons.sonargraph

@@ -18,7 +18,7 @@
 
     <properties>
     	<jackson>1.9.7</jackson>
-    	<springhateoas>0.5.0.BUILD-SNAPSHOT</springhateoas>
+    	<springhateoas>0.6.0.BUILD-SNAPSHOT</springhateoas>
     	<dist.key>DATACMNS</dist.key>
     </properties>
 

pom.xml

@@ -218,7 +218,7 @@ private String getParameterNameToUse(String source, MethodParameter parameter) {
 
 		StringBuilder builder = new StringBuilder(prefix);
 
-		if (parameter.hasParameterAnnotation(Qualifier.class)) {
+		if (parameter != null && parameter.hasParameterAnnotation(Qualifier.class)) {
 			builder.append(parameter.getParameterAnnotation(Qualifier.class).value());
 			builder.append(qualifierSeparator);
 		}

src/main/java/org/springframework/data/web/PageableHandlerMethodArgumentResolver.java

@@ -0,0 +1,172 @@
+/*
+ * 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.data.web;
+
+import static org.springframework.web.util.UriComponentsBuilder.*;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.PagedResources;
+import org.springframework.hateoas.PagedResources.PageMetadata;
+import org.springframework.hateoas.Resource;
+import org.springframework.hateoas.ResourceAssembler;
+import org.springframework.hateoas.ResourceSupport;
+import org.springframework.util.Assert;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
+import org.springframework.web.util.UriComponents;
+import org.springframework.web.util.UriComponentsBuilder;
+
+/**
+ * {@link ResourceAssembler} to easily convert {@link Page} instances into {@link PagedResources}.
+ * 
+ * @since 1.6
+ * @author Oliver Gierke
+ */
+public class PagedResourcesAssembler<T> implements ResourceAssembler<Page<T>, PagedResources<Resource<T>>> {
+
+	private final PageableHandlerMethodArgumentResolver pageableResolver;
+	private final UriComponents baseUri;
+
+	/**
+	 * Creates a new {@link PagedResourcesAssembler} using the given {@link PageableHandlerMethodArgumentResolver} and
+	 * base URI. If the former is {@literal null}, a default one will be created. If the latter is {@literal null}, calls
+	 * to {@link #toResource(Page)} will use the current request's URI to build the relevant previous and next links.
+	 * 
+	 * @param resolver
+	 * @param baseUri
+	 */
+	public PagedResourcesAssembler(PageableHandlerMethodArgumentResolver resolver, UriComponents baseUri) {
+
+		this.pageableResolver = resolver == null ? new PageableHandlerMethodArgumentResolver() : resolver;
+		this.baseUri = baseUri;
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see org.springframework.hateoas.ResourceAssembler#toResource(java.lang.Object)
+	 */
+	@Override
+	public PagedResources<Resource<T>> toResource(Page<T> entity) {
+		return toResource(entity, new SimplePagedResourceAssembler<T>());
+	}
+
+	/**
+	 * Creates a new {@link PagedResources} by converting the given {@link Page} into a {@link PageMetadata} instance and
+	 * wrapping the contained elements into {@link Resource} instances. Will add pagination links based on the given the
+	 * self link.
+	 * 
+	 * @param page must not be {@literal null}.
+	 * @param selfLink must not be {@literal null}.
+	 * @return
+	 */
+	public PagedResources<Resource<T>> toResource(Page<T> page, Link selfLink) {
+		return toResource(page, new SimplePagedResourceAssembler<T>(), selfLink);
+	}
+
+	/**
+	 * Creates a new {@link PagedResources} by converting the given {@link Page} into a {@link PageMetadata} instance and
+	 * using the given {@link ResourceAssembler} to turn elements of the {@link Page} into resources.
+	 * 
+	 * @param page must not be {@literal null}.
+	 * @param assembler must not be {@literal null}.
+	 * @return
+	 */
+	public <R extends ResourceSupport> PagedResources<R> toResource(Page<T> page, ResourceAssembler<T, R> assembler) {
+		return createResource(page, assembler, null);
+	}
+
+	/**
+	 * Creates a new {@link PagedResources} by converting the given {@link Page} into a {@link PageMetadata} instance and
+	 * using the given {@link ResourceAssembler} to turn elements of the {@link Page} into resources. Will add pagination
+	 * links based on the given the self link.
+	 * 
+	 * @param page must not be {@literal null}.
+	 * @param assembler must not be {@literal null}.
+	 * @param link must not be {@literal null}.
+	 * @return
+	 */
+	public <R extends ResourceSupport> PagedResources<R> toResource(Page<T> page, ResourceAssembler<T, R> assembler,
+			Link link) {
+
+		Assert.notNull(link, "Link must not be null!");
+		return createResource(page, assembler, link);
+	}
+
+	private <S, R extends ResourceSupport> PagedResources<R> createResource(Page<S> page,
+			ResourceAssembler<S, R> assembler, Link link) {
+
+		Assert.notNull(page, "Page must not be null!");
+		Assert.notNull(assembler, "ResourceAssembler must not be null!");
+
+		List<R> resources = new ArrayList<R>(page.getNumberOfElements());
+
+		for (S element : page) {
+			resources.add(assembler.toResource(element));
+		}
+
+		PagedResources<R> pagedResources = new PagedResources<R>(resources, asPageMetadata(page));
+		return addPaginationLinks(pagedResources, page, link == null ? getDefaultUriString().toUriString() : link.getHref());
+	}
+
+	private UriComponents getDefaultUriString() {
+		return baseUri == null ? ServletUriComponentsBuilder.fromCurrentRequest().build() : baseUri;
+	}
+
+	private <R extends ResourceSupport> PagedResources<R> addPaginationLinks(PagedResources<R> resources, Page<?> page,
+			String uri) {
+
+		if (page.hasNextPage()) {
+			foo(resources, page.nextPageable(), uri, Link.REL_NEXT);
+		}
+
+		if (page.hasPreviousPage()) {
+			foo(resources, page.previousPageable(), uri, Link.REL_PREVIOUS);
+		}
+
+		return resources;
+	}
+
+	private void foo(PagedResources<?> resources, Pageable pageable, String uri, String rel) {
+
+		UriComponentsBuilder builder = fromUriString(uri);
+		pageableResolver.enhance(builder, null, pageable);
+		resources.add(new Link(builder.build().toUriString(), rel));
+	}
+
+	/**
+	 * Creates a new {@link PageMetadata} instance from the given {@link Page}.
+	 * 
+	 * @param page must not be {@literal null}.
+	 * @return
+	 */
+	private static <T> PageMetadata asPageMetadata(Page<T> page) {
+
+		Assert.notNull(page, "Page must not be null!");
+		return new PageMetadata(page.getSize(), page.getNumber(), page.getTotalElements(), page.getTotalPages());
+	}
+
+	private static class SimplePagedResourceAssembler<T> implements ResourceAssembler<T, Resource<T>> {
+
+		@Override
+		public Resource<T> toResource(T entity) {
+			return new Resource<T>(entity);
+		}
+	}
+}

src/main/java/org/springframework/data/web/PagedResourcesAssembler.java

@@ -0,0 +1,77 @@
+/*
+ * 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.data.web;
+
+import org.springframework.core.MethodParameter;
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.MethodLinkBuilderFactory;
+import org.springframework.hateoas.mvc.ControllerLinkBuilderFactory;
+import org.springframework.web.bind.support.WebDataBinderFactory;
+import org.springframework.web.context.request.NativeWebRequest;
+import org.springframework.web.method.support.HandlerMethodArgumentResolver;
+import org.springframework.web.method.support.ModelAndViewContainer;
+import org.springframework.web.util.UriComponents;
+import org.springframework.web.util.UriComponentsBuilder;
+
+/**
+ * {@link HandlerMethodArgumentResolver} to allow injection of {@link PagedResourcesAssembler} into Spring MVC
+ * controller methods.
+ * 
+ * @since 1.6
+ * @author Oliver Gierke
+ */
+public class PagedResourcesAssemblerArgumentResolver implements HandlerMethodArgumentResolver {
+
+	private final PageableHandlerMethodArgumentResolver resolver;
+	private final MethodLinkBuilderFactory<?> linkBuilderFactory;
+
+	/**
+	 * Creates a new {@link PagedResourcesAssemblerArgumentResolver} using the given
+	 * {@link PageableHandlerMethodArgumentResolver} and {@link MethodLinkBuilderFactory}.
+	 * 
+	 * @param resolver can be {@literal null}.
+	 * @param linkBuilderFactory can be {@literal null}, will be defaulted to a {@link ControllerLinkBuilderFactory}.
+	 */
+	public PagedResourcesAssemblerArgumentResolver(PageableHandlerMethodArgumentResolver resolver,
+			MethodLinkBuilderFactory<?> linkBuilderFactory) {
+
+		this.resolver = resolver;
+		this.linkBuilderFactory = linkBuilderFactory == null ? new ControllerLinkBuilderFactory() : linkBuilderFactory;
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see org.springframework.web.method.support.HandlerMethodArgumentResolver#supportsParameter(org.springframework.core.MethodParameter)
+	 */
+	@Override
+	public boolean supportsParameter(MethodParameter parameter) {
+		return PagedResourcesAssembler.class.equals(parameter.getParameterType());
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see org.springframework.web.method.support.HandlerMethodArgumentResolver#resolveArgument(org.springframework.core.MethodParameter, org.springframework.web.method.support.ModelAndViewContainer, org.springframework.web.context.request.NativeWebRequest, org.springframework.web.bind.support.WebDataBinderFactory)
+	 */
+	@Override
+	public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
+			NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
+
+		Link linkToMethod = linkBuilderFactory.linkTo(parameter.getMethod(), new Object[0]).withSelfRel();
+		UriComponents fromUriString = UriComponentsBuilder.fromUriString(linkToMethod.getHref()).build();
+
+		return new PagedResourcesAssembler<Object>(resolver, fromUriString);
+	}
+}

src/main/java/org/springframework/data/web/PagedResourcesAssemblerArgumentResolver.java

@@ -218,7 +218,7 @@ private String getSortParameter(MethodParameter parameter) {
 
 		StringBuilder builder = new StringBuilder();
 
-		if (parameter.hasParameterAnnotation(Qualifier.class)) {
+		if (parameter != null && parameter.hasParameterAnnotation(Qualifier.class)) {
 			builder.append(parameter.getParameterAnnotation(Qualifier.class).value()).append(qualifierDelimiter);
 		}
 

src/main/java/org/springframework/data/web/SortHandlerMethodArgumentResolver.java

@@ -0,0 +1,98 @@
+/*
+ * 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.data.web.config;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.ImportSelector;
+import org.springframework.core.type.AnnotationMetadata;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Sort;
+import org.springframework.data.repository.support.DomainClassConverter;
+import org.springframework.data.web.PageableHandlerMethodArgumentResolver;
+import org.springframework.data.web.PagedResourcesAssembler;
+import org.springframework.data.web.PagedResourcesAssemblerArgumentResolver;
+import org.springframework.data.web.SortHandlerMethodArgumentResolver;
+import org.springframework.util.ClassUtils;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
+
+/**
+ * Annotation to automatically register the following beans for usage with Spring MVC.
+ * <ul>
+ * <li>{@link DomainClassConverter} - to allow usage of domain types managed by Spring Data repositories as controller
+ * method arguments bound with {@link PathVariable} or {@link RequestParam}.</li>
+ * <li>{@link PageableHandlerMethodArgumentResolver} - to allow injection of {@link Pageable} instances into controller
+ * methods automatically created from request parameters.</li>
+ * <li>{@link SortHandlerMethodArgumentResolver} - to allow injection of {@link Sort} instances into controller methods
+ * automatically created from request parameters.</li>
+ * </ul>
+ * If Spring HATEOAS is present on the classpath we will additionall register the following beans:
+ * <ul>
+ * <li>{@link PagedResourcesAssembler} - for injection into web components</li>
+ * <li>{@link PagedResourcesAssemblerArgumentResolver} - for injection of {@link PagedResourcesAssembler} into
+ * controller methods</li>
+ * <ul>
+ * 
+ * @since 1.6
+ * @see SpringDataWebConfiguration
+ * @see HateoasAwareSpringDataWebConfiguration
+ * @author Oliver Gierke
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Inherited
+@Import(EnableSpringDataWebSupport.SpringDataWebConfigurationImportSelector.class)
+public @interface EnableSpringDataWebSupport {
+
+	/**
+	 * Import selector to import the appropriate configuration class depending on whether Spring HATEOAS is present on the
+	 * classpath. We need to register the HATEOAS specific class first as apparently only the first class implementing
+	 * {@link WebMvcConfigurationSupport} gets callbacks invoked (see https://jira.springsource.org/browse/SPR-10565).
+	 * 
+	 * @author Oliver Gierke
+	 */
+	class SpringDataWebConfigurationImportSelector implements ImportSelector {
+
+		// Don't make final to allow test cases faking this to false
+		private static boolean HATEOAS_PRESENT = ClassUtils.isPresent("org.springframework.hateoas.Link", null);
+
+		/* 
+		 * (non-Javadoc)
+		 * @see org.springframework.context.annotation.ImportSelector#selectImports(org.springframework.core.type.AnnotationMetadata)
+		 */
+		@Override
+		public String[] selectImports(AnnotationMetadata importingClassMetadata) {
+
+			List<String> configs = new ArrayList<String>();
+
+			if (HATEOAS_PRESENT) {
+				configs.add(HateoasAwareSpringDataWebConfiguration.class.getName());
+			}
+
+			configs.add(SpringDataWebConfiguration.class.getName());
+			return configs.toArray(new String[configs.size()]);
+		}
+	}
+}