DATACMNS-966 - Add annotation that specify allowed sort properties.

.travis.yml

@@ -1,19 +1,31 @@
 language: java
+
 jdk:
   - oraclejdk8
+
 env:
   matrix:
     - PROFILE=ci
     - PROFILE=spring43-next
     - PROFILE=spring5
     - PROFILE=spring5-next
     - PROFILE=querydsl-next
+
+addons:
+  apt:
+    packages:
+    - oracle-java8-installer
+
 cache:
   directories:
     - $HOME/.m2
+
 sudo: false
+
 install: true
+
 script: "mvn clean dependency:list test -P${PROFILE} -Dsort"
+
 notifications:
   slack:
     secure: PWyr3+7uTnHzZSrJY2DrowwdYODlIeFZB6tzuq+i/vYqMlX2GGXGQN9YmqbKPeaVZBdSI7YrI1UDa5cPAAXoTjn/JewkL0RbdTeIS6PGCpcpAb5rFMYtOhEDBrFB/SRiMH4tw86bRNKq/SrUWmpkzDtTzLrw7JceumgyqnrT6GY=

pom.xml

@@ -17,6 +17,7 @@
 
 	<properties>
 		<dist.key>DATACMNS</dist.key>
+		<javaslang>2.0.4</javaslang>
 		<scala>2.11.7</scala>
 		<xmlbeam>1.4.8</xmlbeam>
 	</properties>
@@ -143,6 +144,13 @@
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>io.javaslang</groupId>
+			<artifactId>javaslang</artifactId>
+			<version>${javaslang}</version>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>javax.el</groupId>
 			<artifactId>el-api</artifactId>

src/main/asciidoc/repositories.adoc

@@ -218,7 +218,7 @@ NOTE: Note, that the intermediate repository interface is annotated with `@NoRep
 Using a unique Spring Data module in your application makes things simple hence, all repository interfaces in the defined scope are bound to the Spring Data module. Sometimes applications require using more than one Spring Data module. In such case, it's required for a repository definition to distinguish between persistence technologies. Spring Data enters strict repository configuration mode because it detects multiple repository factories on the class path. Strict configuration requires details on the repository or the domain class to decide about Spring Data module binding for a repository definition:
 
 1. If the repository definition <<repositories.multiple-modules.types,extends the module-specific repository>>, then it's a valid candidate for the particular Spring Data module.
-2. If the domain class is <<repositories.multiple-modules.annotations,annotated with the module-specific type annotation>>, then it's a valid candidate for the particular Spring Data module. Spring Data modules accept either 3rd party annotations (such as JPA's `@Entity`) or provide own annotations such as `@Document` for Spring Data MongoDB/Spring Data Elasticsearch. 
+2. If the domain class is <<repositories.multiple-modules.annotations,annotated with the module-specific type annotation>>, then it's a valid candidate for the particular Spring Data module. Spring Data modules accept either 3rd party annotations (such as JPA's `@Entity`) or provide own annotations such as `@Document` for Spring Data MongoDB/Spring Data Elasticsearch.
 
 [[repositories.multiple-modules.types]]
 .Repository definitions using Module-specific Interfaces
@@ -306,7 +306,7 @@ public class Person {
 This example shows a domain class using both JPA and Spring Data MongoDB annotations. It defines two repositories, `JpaPersonRepository` and `MongoDBPersonRepository`. One is intended for JPA and the other for MongoDB usage. Spring Data is no longer able to tell the repositories apart which leads to undefined behavior.
 ====
 
-<<repositories.multiple-modules.types,Repository type details>> and <<repositories.multiple-modules.annotations,identifying domain class annotations>> are used for strict repository configuration identify repository candidates for a particular Spring Data module. Using multiple persistence technology-specific annotations on the same domain type is possible to reuse domain types across multiple persistence technologies, but then Spring Data is no longer able to determine a unique module to bind the repository. 
+<<repositories.multiple-modules.types,Repository type details>> and <<repositories.multiple-modules.annotations,identifying domain class annotations>> are used for strict repository configuration identify repository candidates for a particular Spring Data module. Using multiple persistence technology-specific annotations on the same domain type is possible to reuse domain types across multiple persistence technologies, but then Spring Data is no longer able to determine a unique module to bind the repository.
 
 The last way to distinguish repositories is scoping repository base packages. Base packages define the starting points for scanning for repository interface definitions which  implies to have repository definitions located in the appropriate packages. By default, annotation-driven configuration uses the package of the configuration class. The <<repositories.create-instances.spring,base package in XML-based configuration>> is mandatory.
 
@@ -414,7 +414,7 @@ List<User> findByLastname(String lastname, Pageable pageable);
 ----
 ====
 
-The first method allows you to pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query. A `Page` knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number. As this might be expensive depending on the store used, `Slice` can be used as return instead. A `Slice` only knows about whether there's a next `Slice` available which might be just sufficient when walking thought a larger result set.
+The first method allows you to pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query. A `Page` knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number. As this might be expensive depending on the store used, `Slice` can be used as return instead. A `Slice` only knows about whether there's a next `Slice` available which might be just sufficient when walking through a larger result set.
 
 Sorting options are handled through the `Pageable` instance too. If you only need sorting, simply add an `org.springframework.data.domain.Sort` parameter to your method. As you also can see, simply returning a `List` is possible as well. In this case the additional metadata required to build the actual `Page` instance will not be created (which in turn means that the additional count query that would have been necessary not being issued) but rather simply restricts the query to look up only the given range of entities.
 
@@ -736,6 +736,36 @@ A corresponding attribute is available in the XML namespace.
 ----
 ====
 
+[[core.domain-events]]
+== Publishing events from aggregate roots
+
+Entities managed by repositories are aggregate roots.
+In a Domain-Driven Design application, these aggregate roots usually publish domain events.
+Spring Data provides an annotation `@DomainEvents` you can use on a method of your aggregate root to make that publication as easy as possible.
+
+.Exposing domain events from an aggregate root
+====
+[source, java]
+----
+class AnAggreagteRoot {
+
+    @DomainEvents <1>
+    Collection<Object> domainEvents() {
+        // … return events you want to get published here
+    }
+
+    @AfterDomainEventsPublication <2>
+    void callbackMethod() {
+       // … potentially clean up domain events list
+    }
+}
+----
+<1> The method using `@DomainEvents` can either return a single event instance or a collection of events. It must not take any arguments.
+<2> After all events have been published, a method annotated with `@AfterDomainEventsPublication`. It e.g. can be used to potentially clean the list of events to be published.
+====
+
+The methods will be called every time one of a Spring Data repository's `save(…)` methods is called.
+
 [[core.extensions]]
 == Spring Data extensions
 

src/main/asciidoc/repository-query-return-types-reference.adoc

@@ -19,6 +19,7 @@ NOTE: Geospatial types like (`GeoResult`, `GeoResults`, `GeoPage`) are only avai
 |`Collection<T>`|A `Collection`.
 |`List<T>`|A `List`.
 |`Optional<T>`|A Java 8 or Guava `Optional`. Expects the query method to return one result at most. In case no result is found `Optional.empty()`/`Optional.absent()` is returned. More than one result will trigger an `IncorrectResultSizeDataAccessException`.
+|`Option<T>`|An either Scala or JavaSlang `Option` type. Semantically same behavior as Java 8's `Optional` described above.
 |`Stream<T>`|A Java 8 `Stream`.
 |`Future<T>`|A `Future`. Expects method to be annotated with `@Async` and requires Spring's asynchronous method execution capability enabled.
 |`CompletableFuture<T>`|A Java 8 `CompletableFuture`. Expects method to be annotated with `@Async` and requires Spring's asynchronous method execution capability enabled.

src/main/java/org/springframework/data/convert/Jsr310Converters.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2015 the original author or authors.
+ * Copyright 2013-2016 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.
@@ -19,10 +19,12 @@
 import static java.time.LocalDateTime.*;
 import static java.time.ZoneId.*;
 
+import java.time.Duration;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
+import java.time.Period;
 import java.time.ZoneId;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -38,6 +40,7 @@
  * Helper class to register JSR-310 specific {@link Converter} implementations in case the we're running on Java 8.
  * 
  * @author Oliver Gierke
+ * @author Barak Schoster
  */
 public abstract class Jsr310Converters {
 
@@ -66,6 +69,10 @@ public abstract class Jsr310Converters {
 		converters.add(InstantToDateConverter.INSTANCE);
 		converters.add(ZoneIdToStringConverter.INSTANCE);
 		converters.add(StringToZoneIdConverter.INSTANCE);
+		converters.add(DurationToStringConverter.INSTANCE);
+		converters.add(StringToDurationConverter.INSTANCE);
+		converters.add(PeriodToStringConverter.INSTANCE);
+		converters.add(StringToPeriodConverter.INSTANCE);
 
 		return converters;
 	}
@@ -181,4 +188,48 @@ public ZoneId convert(String source) {
 			return ZoneId.of(source);
 		}
 	}
+
+	@WritingConverter
+	public static enum DurationToStringConverter implements Converter<Duration, String> {
+
+		INSTANCE;
+
+		@Override
+		public String convert(Duration duration) {
+			return duration.toString();
+		}
+	}
+
+	@ReadingConverter
+	public static enum StringToDurationConverter implements Converter<String, Duration> {
+
+		INSTANCE;
+
+		@Override
+		public Duration convert(String s) {
+			return Duration.parse(s);
+		}
+	}
+
+	@WritingConverter
+	public static enum PeriodToStringConverter implements Converter<Period, String> {
+
+		INSTANCE;
+
+		@Override
+		public String convert(Period period) {
+			return period.toString();
+		}
+	}
+
+	@ReadingConverter
+	public static enum StringToPeriodConverter implements Converter<String, Period> {
+
+		INSTANCE;
+
+		@Override
+		public Period convert(String s) {
+			return Period.parse(s);
+		}
+	}
 }

src/main/java/org/springframework/data/domain/AbstractAggregateRoot.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2016 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.domain;
+
+import lombok.Getter;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.springframework.util.Assert;
+
+/**
+ * Convenience base class for aggregate roots that exposes a {@link #registerEvent(Object)} to capture domain events and
+ * expose them via {@link #getDomainEvents()}. The implementation is using the general event publication mechanism
+ * implied by {@link DomainEvents} and {@link AfterDomainEventPublication}. If in doubt or need to customize anything
+ * here, rather build your own base class and use the annotations directly.
+ * 
+ * @author Oliver Gierke
+ * @since 1.13
+ */
+public class AbstractAggregateRoot {
+
+	/**
+	 * All domain events currently captured by the aggregate.
+	 */
+	@Getter(onMethod = @__(@DomainEvents)) //
+	private transient final List<Object> domainEvents = new ArrayList<Object>();
+
+	/**
+	 * Registers the given event object for publication on a call to a Spring Data repository's save method.
+	 * 
+	 * @param event must not be {@literal null}.
+	 * @return
+	 */
+	protected <T> T registerEvent(T event) {
+
+		Assert.notNull(event, "Domain event must not be null!");
+
+		this.domainEvents.add(event);
+		return event;
+	}
+
+	/**
+	 * Clears all domain events currently held. Usually invoked by the infrastructure in place in Spring Data
+	 * repositories.
+	 */
+	@AfterDomainEventPublication
+	public void clearDomainEvents() {
+		this.domainEvents.clear();
+	}
+}

src/main/java/org/springframework/data/domain/AfterDomainEventPublication.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2016 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.domain;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to be used on a method of a Spring Data managed aggregate to get invoked after the events of an aggregate
+ * have been published.
+ * 
+ * @author Oliver Gierke
+ * @see DomainEvents
+ * @since 1.13
+ * @soundtrack Benny Greb - September (Moving Parts Live)
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface AfterDomainEventPublication {
+
+}

src/main/java/org/springframework/data/domain/DomainEvents.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2016 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.domain;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.context.ApplicationEventPublisher;
+
+/**
+ * {@link DomainEvents} can be used on methods of aggregate roots managed by Spring Data repositories to publish the
+ * events returned by that method as Spring application events.
+ * 
+ * @author Oliver Gierke
+ * @see ApplicationEventPublisher
+ * @see AfterDomainEventPublication
+ * @since 1.13
+ * @soundtrack Benny Greb - Soulfood (Moving Parts Live)
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface DomainEvents {
+}

src/main/java/org/springframework/data/domain/ExampleMatcher.java

@@ -608,7 +608,7 @@ public static GenericPropertyMatcher startsWith() {
 		 * @return
 		 */
 		public static GenericPropertyMatcher exact() {
-			return new GenericPropertyMatcher().startsWith();
+			return new GenericPropertyMatcher().exact();
 		}
 
 		/**