spring-projects#297 - Add sample for fluent MongoDB API.

Author: christophstrobl

mongodb/fluent-api/README.md

@@ -0,0 +1,63 @@
+# Spring Data MongoDB 2.0 - FluentMongoOperations Example
+
+This project contains usage samples of `FluentMongoOperations`.
+
+## Fluent API
+
+`FluentMongoOperations` provides a stripped down, more focused API alternative for classic `MongoOperations`.
+The main entry points are typical tasks for finding and manipulating ``Document``s on a domain type base, while operations like creating indexes are left out.
+
+For convenience classic `MongoOperations` extend `FluentMongoOperations`, however for most cases it might be sufficient to just work with the reduced interface.
+To get started just inject `FluentMongoOperations`.
+
+The entry point methods of `FluentMongoOperations` provide you with an immutable fluent API allowing only valid next steps while constructing the operation to execute. This allows to set up operations once and keep those in memory for multiple executions.
+
+### Query
+
+Looking at the following `query(SWCharacter.class)`.
+
+`SWCharacter` is used for mapping the query properties to the actual document field names. As the `SWCharacter` defines `@Field("firstname") name;` the `where` clause of the query is mapped to the MongoDB representation as `{ firstname : "luke" }`.
+
+Using `as(Jedi.class)` switches return type mapping from `SWCharacter` to `Jedi` which allows to map resulting documents to a different type than the one used for query mapping.
+
+So far no actual query execution has been invoked. Calling on of the terminating methods like `one()`, `first()`, `all()`,... triggers the query.
+
+```java
+mongoOps.query(SWCharacter.class)
+  .inCollection("star-wars")
+  .as(Jedi.class)
+  .matching(query(where("name").is("luke")))
+  .one();
+
+```
+
+Different stages in the command essembly process allow to seamlessly switch to different API paths. Using `near` instead of `matching` switches to the path for geo queries requireing the presence of a `NearQuery` while altering the command result type from `List` to `GeoResults` and limiting terminating operations to just `all()`.
+
+```java
+
+NearQuery alderaanWithin3Parsecs = NearQuery.near(-73.9667, 40.78)
+  .maxDistance(new Distance(3, MILES))
+  .spherical(true);
+
+GeoResults<Jedi> results = mongoOps.query(SWCharacter.class)
+  .as(Jedi.class)
+  .near(alderaanWithin3Parsecs)
+  .all();
+```
+
+
+### Update
+
+Looking at the following `update(Jedi.class)`.
+
+`Jedi` already defines the `collection` via the `@Document` annotation, so there is no need to explicitly specify a collection name via `inCollection(String)`. The `Jedi` domain type is also used for query and update mapping.
+
+So far no actual query execution has been invoked. Calling on of the terminating methods like `all()`, `upsert()`, `findAndModify()`, etc. triggers the update.
+```java
+
+
+mongoOps.update(Jedi.class)
+  .matching(query(where("lastname").is("windu")))
+  .apply(update("name", "mence"))
+  .upsert();
+```

mongodb/fluent-api/pom.xml

@@ -0,0 +1,15 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<artifactId>spring-data-mongodb-fluent-api</artifactId>
+
+	<name>Spring Data MongoDB - Fluent API Example</name>
+
+	<parent>
+		<groupId>org.springframework.data.examples</groupId>
+		<artifactId>spring-data-mongodb-examples</artifactId>
+		<version>1.0.0.BUILD-SNAPSHOT</version>
+	</parent>
+
+</project>

mongodb/fluent-api/src/main/java/example/springdata/mongodb/fluent/Human.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import lombok.Data;
+
+/**
+ * @author Christoph Strobl
+ */
+@Data
+class Human {
+
+	final String firstname;
+	final String lastname;
+}

mongodb/fluent-api/src/main/java/example/springdata/mongodb/fluent/Jedi.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+
+/**
+ * @author Christoph Strobl
+ */
+@Getter
+@EqualsAndHashCode(callSuper = true)
+@ToString
+class Jedi extends SWCharacter {
+
+	private final String lastname;
+
+	Jedi(String name, String lastname) {
+
+		super(name);
+		this.lastname = lastname;
+	}
+
+}

mongodb/fluent-api/src/main/java/example/springdata/mongodb/fluent/Planet.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import lombok.Data;
+
+import org.springframework.data.annotation.Id;
+import org.springframework.data.geo.Point;
+import org.springframework.data.mongodb.core.index.GeoSpatialIndexed;
+
+/**
+ * @author Christoph Strobl
+ */
+@Data
+public class Planet {
+
+	final @Id String name;
+	final @GeoSpatialIndexed Point coordinates;
+}

mongodb/fluent-api/src/main/java/example/springdata/mongodb/fluent/SWCharacter.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+
+import lombok.Setter;
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+import org.springframework.data.mongodb.core.mapping.Field;
+
+/**
+ * @author Christoph Strobl
+ */
+@Document(collection = "star-wars")
+@Getter
+@Setter
+@EqualsAndHashCode(of = "name")
+class SWCharacter {
+
+	private @Id String id;
+	private @Field("firstname") String name;
+	private Planet homePlanet;
+
+	SWCharacter(String name) {
+		this.name = name;
+	}
+}

mongodb/fluent-api/src/main/java/example/springdata/mongodb/fluent/Sith.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import org.springframework.beans.factory.annotation.Value;
+
+/**
+ * @author Christoph Strobl
+ */
+public interface Sith {
+
+	@Value("#{target.name + ' ' + target.lastname}")
+	String getName();
+}

mongodb/fluent-api/src/test/java/example/springdata/mongodb/fluent/ApplicationConfiguration.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 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 example.springdata.mongodb.fluent;
+
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+import org.springframework.data.geo.Point;
+import org.springframework.data.mongodb.core.MongoTemplate;
+import org.springframework.data.mongodb.core.index.GeoSpatialIndexType;
+import org.springframework.data.mongodb.core.index.GeospatialIndex;
+
+/**
+ * @author Christoph Strobl
+ */
+@SpringBootApplication
+public class ApplicationConfiguration {
+
+	static final String COLLECTION = "star-wars";
+
+	@Bean
+	CommandLineRunner init(MongoTemplate template) {
+
+		return (args) -> {
+
+			if (template.collectionExists(COLLECTION)) {
+				template.dropCollection(COLLECTION);
+			}
+
+			GeospatialIndex index = new GeospatialIndex("homePlanet.coordinates") //
+					.typed(GeoSpatialIndexType.GEO_2DSPHERE) //
+					.named("planet-coordinate-idx");
+
+			template.createCollection(COLLECTION);
+			template.indexOps(SWCharacter.class).ensureIndex(index);
+
+			Planet alderaan = new Planet("alderaan", new Point(-73.9667, 40.78));
+			Planet stewjon = new Planet("stewjon", new Point(-73.9836, 40.7538));
+			Planet tatooine = new Planet("tatooine", new Point(-73.9928, 40.7193));
+
+			Jedi anakin = new Jedi("anakin", "skywalker");
+			anakin.setHomePlanet(tatooine);
+
+			Jedi luke = new Jedi("luke", "skywalker");
+			luke.setHomePlanet(tatooine);
+
+			Jedi leia = new Jedi("leia", "organa");
+			leia.setHomePlanet(alderaan);
+
+			Jedi obiWan = new Jedi("obi-wan", "kenobi");
+			obiWan.setHomePlanet(stewjon);
+
+			Human han = new Human("han", "solo");
+
+			template.save(anakin, COLLECTION);
+			template.save(luke, COLLECTION);
+			template.save(leia, COLLECTION);
+			template.save(obiWan, COLLECTION);
+			template.save(han, COLLECTION);
+		};
+	}
+}