DATAMONGO-1245 - Add support for Query By Example.

An explorative approach to QBE trying find possibilities and limitations. We now support querying documents by providing a sample of the given object holding compare values. For the sake of partial matching we flatten out nested structures so we can create different queries for matching like:

{ _id : 1, nested : { value : "conflux" } }
{ _id : 1, nested.value : { "conflux" } }

This is useful when you want so search using a only partially filled nested document. String matching can be configured to wrap strings with $regex which creates { firstname : { $regex : "^foo", $options: "i" } } when using StringMatchMode.STARTING along with the ignoreCaseOption. DBRefs and geo structures such as Point or GeoJsonPoint is converted to their according structure.

Related tickets: DATACMNS-810.
Original pull request: #341.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoTemplate.java

@@ -51,6 +51,7 @@
 import org.springframework.data.annotation.Id;
 import org.springframework.data.authentication.UserCredentials;
 import org.springframework.data.convert.EntityReader;
+import org.springframework.data.domain.Example;
 import org.springframework.data.geo.Distance;
 import org.springframework.data.geo.GeoResult;
 import org.springframework.data.geo.GeoResults;
@@ -340,8 +341,8 @@ public CloseableIterator<T> doInCollection(DBCollection collection) throws Mongo
 				DBCursor cursor = collection.find(mappedQuery, mappedFields);
 				QueryCursorPreparer cursorPreparer = new QueryCursorPreparer(query, entityType);
 
-				ReadDbObjectCallback<T> readCallback = new ReadDbObjectCallback<T>(mongoConverter, entityType,
-						collection.getName());
+				ReadDbObjectCallback<T> readCallback = new ReadDbObjectCallback<T>(mongoConverter, entityType, collection
+						.getName());
 
 				return new CloseableIterableCursorAdapter<T>(cursorPreparer.prepare(cursor), exceptionTranslator, readCallback);
 			}
@@ -374,8 +375,8 @@ public CommandResult doInDB(DB db) throws MongoException, DataAccessException {
 	 */
 	@Deprecated
 	public CommandResult executeCommand(final DBObject command, final int options) {
-		return executeCommand(command,
-				(options & Bytes.QUERYOPTION_SLAVEOK) != 0 ? ReadPreference.secondaryPreferred() : ReadPreference.primary());
+		return executeCommand(command, (options & Bytes.QUERYOPTION_SLAVEOK) != 0 ? ReadPreference.secondaryPreferred()
+				: ReadPreference.primary());
 	}
 
 	/*
@@ -421,8 +422,7 @@ public void executeQuery(Query query, String collectionName, DocumentCallbackHan
 	 * @param preparer allows for customization of the {@link DBCursor} used when iterating over the result set, (apply
 	 *          limits, skips and so on).
 	 */
-	protected void executeQuery(Query query, String collectionName, DocumentCallbackHandler dch,
-			CursorPreparer preparer) {
+	protected void executeQuery(Query query, String collectionName, DocumentCallbackHandler dch, CursorPreparer preparer) {
 
 		Assert.notNull(query);
 
@@ -637,6 +637,17 @@ public <T> T findById(Object id, Class<T> entityClass, String collectionName) {
 		return doFindOne(collectionName, new BasicDBObject(idKey, id), null, entityClass);
 	}
 
+	public <S extends T, T> List<T> findByExample(S sample) {
+		return findByExample(new Example<S>(sample));
+	}
+
+	@SuppressWarnings("unchecked")
+	public <S extends T, T> List<T> findByExample(Example<S> sample) {
+
+		Assert.notNull(sample, "Sample object must not be null!");
+		return (List<T>) find(new Query(new Criteria().alike(sample)), sample.getSampleType());
+	}
+
 	public <T> GeoResults<T> geoNear(NearQuery near, Class<T> entityClass) {
 		return geoNear(near, entityClass, determineCollectionName(entityClass));
 	}
@@ -672,8 +683,8 @@ public <T> GeoResults<T> geoNear(NearQuery near, Class<T> entityClass, String co
 		List<Object> results = (List<Object>) commandResult.get("results");
 		results = results == null ? Collections.emptyList() : results;
 
-		DbObjectCallback<GeoResult<T>> callback = new GeoNearResultDbObjectCallback<T>(
-				new ReadDbObjectCallback<T>(mongoConverter, entityClass, collectionName), near.getMetric());
+		DbObjectCallback<GeoResult<T>> callback = new GeoNearResultDbObjectCallback<T>(new ReadDbObjectCallback<T>(
+				mongoConverter, entityClass, collectionName), near.getMetric());
 		List<GeoResult<T>> result = new ArrayList<GeoResult<T>>(results.size());
 
 		int index = 0;
@@ -749,9 +760,8 @@ public long count(final Query query, String collectionName) {
 	public long count(Query query, Class<?> entityClass, String collectionName) {
 
 		Assert.hasText(collectionName);
-		final DBObject dbObject = query == null ? null
-				: queryMapper.getMappedObject(query.getQueryObject(),
-						entityClass == null ? null : mappingContext.getPersistentEntity(entityClass));
+		final DBObject dbObject = query == null ? null : queryMapper.getMappedObject(query.getQueryObject(),
+				entityClass == null ? null : mappingContext.getPersistentEntity(entityClass));
 
 		return execute(collectionName, new CollectionCallback<Long>() {
 			public Long doInCollection(DBCollection collection) throws MongoException, DataAccessException {
@@ -1030,8 +1040,8 @@ public Object doInCollection(DBCollection collection) throws MongoException, Dat
 				MongoAction mongoAction = new MongoAction(writeConcern, MongoActionOperation.INSERT, collectionName,
 						entityClass, dbDoc, null);
 				WriteConcern writeConcernToUse = prepareWriteConcern(mongoAction);
-				WriteResult writeResult = writeConcernToUse == null ? collection.insert(dbDoc)
-						: collection.insert(dbDoc, writeConcernToUse);
+				WriteResult writeResult = writeConcernToUse == null ? collection.insert(dbDoc) : collection.insert(dbDoc,
+						writeConcernToUse);
 				handleAnyWriteResultErrors(writeResult, dbDoc, MongoActionOperation.INSERT);
 				return dbDoc.get(ID_FIELD);
 			}
@@ -1052,8 +1062,8 @@ public Void doInCollection(DBCollection collection) throws MongoException, DataA
 				MongoAction mongoAction = new MongoAction(writeConcern, MongoActionOperation.INSERT_LIST, collectionName, null,
 						null, null);
 				WriteConcern writeConcernToUse = prepareWriteConcern(mongoAction);
-				WriteResult writeResult = writeConcernToUse == null ? collection.insert(dbDocList)
-						: collection.insert(dbDocList.toArray((DBObject[]) new BasicDBObject[dbDocList.size()]), writeConcernToUse);
+				WriteResult writeResult = writeConcernToUse == null ? collection.insert(dbDocList) : collection.insert(
+						dbDocList.toArray((DBObject[]) new BasicDBObject[dbDocList.size()]), writeConcernToUse);
 				handleAnyWriteResultErrors(writeResult, null, MongoActionOperation.INSERT_LIST);
 				return null;
 			}
@@ -1083,8 +1093,8 @@ public Object doInCollection(DBCollection collection) throws MongoException, Dat
 				MongoAction mongoAction = new MongoAction(writeConcern, MongoActionOperation.SAVE, collectionName, entityClass,
 						dbDoc, null);
 				WriteConcern writeConcernToUse = prepareWriteConcern(mongoAction);
-				WriteResult writeResult = writeConcernToUse == null ? collection.save(dbDoc)
-						: collection.save(dbDoc, writeConcernToUse);
+				WriteResult writeResult = writeConcernToUse == null ? collection.save(dbDoc) : collection.save(dbDoc,
+						writeConcernToUse);
 				handleAnyWriteResultErrors(writeResult, dbDoc, MongoActionOperation.SAVE);
 				return dbDoc.get(ID_FIELD);
 			}
@@ -1137,10 +1147,10 @@ public WriteResult doInCollection(DBCollection collection) throws MongoException
 
 				increaseVersionForUpdateIfNecessary(entity, update);
 
-				DBObject queryObj = query == null ? new BasicDBObject()
-						: queryMapper.getMappedObject(query.getQueryObject(), entity);
-				DBObject updateObj = update == null ? new BasicDBObject()
-						: updateMapper.getMappedObject(update.getUpdateObject(), entity);
+				DBObject queryObj = query == null ? new BasicDBObject() : queryMapper.getMappedObject(query.getQueryObject(),
+						entity);
+				DBObject updateObj = update == null ? new BasicDBObject() : updateMapper.getMappedObject(
+						update.getUpdateObject(), entity);
 
 				if (LOGGER.isDebugEnabled()) {
 					LOGGER.debug("Calling update using query: {} and update: {} in collection: {}",
@@ -1281,9 +1291,9 @@ private void assertUpdateableIdIfNotSet(Object entity) {
 		Object idValue = persistentEntity.getPropertyAccessor(entity).getProperty(idProperty);
 
 		if (idValue == null && !MongoSimpleTypes.AUTOGENERATED_ID_TYPES.contains(idProperty.getType())) {
-			throw new InvalidDataAccessApiUsageException(
-					String.format("Cannot autogenerate id of type %s for entity of type %s!", idProperty.getType().getName(),
-							entity.getClass().getName()));
+			throw new InvalidDataAccessApiUsageException(String.format(
+					"Cannot autogenerate id of type %s for entity of type %s!", idProperty.getType().getName(), entity.getClass()
+							.getName()));
 		}
 	}
 
@@ -1322,12 +1332,12 @@ public WriteResult doInCollection(DBCollection collection) throws MongoException
 				WriteConcern writeConcernToUse = prepareWriteConcern(mongoAction);
 
 				if (LOGGER.isDebugEnabled()) {
-					LOGGER.debug("Remove using query: {} in collection: {}.",
-							new Object[] { serializeToJsonSafely(dboq), collection.getName() });
+					LOGGER.debug("Remove using query: {} in collection: {}.", new Object[] { serializeToJsonSafely(dboq),
+							collection.getName() });
 				}
 
-				WriteResult wr = writeConcernToUse == null ? collection.remove(dboq)
-						: collection.remove(dboq, writeConcernToUse);
+				WriteResult wr = writeConcernToUse == null ? collection.remove(dboq) : collection.remove(dboq,
+						writeConcernToUse);
 
 				handleAnyWriteResultErrors(wr, dboq, MongoActionOperation.REMOVE);
 
@@ -1343,8 +1353,8 @@ public <T> List<T> findAll(Class<T> entityClass) {
 	}
 
 	public <T> List<T> findAll(Class<T> entityClass, String collectionName) {
-		return executeFindMultiInternal(new FindCallback(null), null,
-				new ReadDbObjectCallback<T>(mongoConverter, entityClass, collectionName), collectionName);
+		return executeFindMultiInternal(new FindCallback(null), null, new ReadDbObjectCallback<T>(mongoConverter,
+				entityClass, collectionName), collectionName);
 	}
 
 	public <T> MapReduceResults<T> mapReduce(String inputCollectionName, String mapFunction, String reduceFunction,
@@ -1360,8 +1370,8 @@ public <T> MapReduceResults<T> mapReduce(String inputCollectionName, String mapF
 
 	public <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, String mapFunction,
 			String reduceFunction, Class<T> entityClass) {
-		return mapReduce(query, inputCollectionName, mapFunction, reduceFunction, new MapReduceOptions().outputTypeInline(),
-				entityClass);
+		return mapReduce(query, inputCollectionName, mapFunction, reduceFunction,
+				new MapReduceOptions().outputTypeInline(), entityClass);
 	}
 
 	public <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, String mapFunction,
@@ -1372,9 +1382,8 @@ public <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName
 		DBCollection inputCollection = getCollection(inputCollectionName);
 
 		MapReduceCommand command = new MapReduceCommand(inputCollection, mapFunc, reduceFunc,
-				mapReduceOptions.getOutputCollection(), mapReduceOptions.getOutputType(),
-				query == null || query.getQueryObject() == null ? null
-						: queryMapper.getMappedObject(query.getQueryObject(), null));
+				mapReduceOptions.getOutputCollection(), mapReduceOptions.getOutputType(), query == null
+						|| query.getQueryObject() == null ? null : queryMapper.getMappedObject(query.getQueryObject(), null));
 
 		copyMapReduceOptionsToCommand(query, mapReduceOptions, command);
 
@@ -1710,8 +1719,8 @@ protected <T> T doFindOne(String collectionName, DBObject query, DBObject fields
 					mappedFields, entityClass, collectionName);
 		}
 
-		return executeFindOneInternal(new FindOneCallback(mappedQuery, mappedFields),
-				new ReadDbObjectCallback<T>(this.mongoConverter, entityClass, collectionName), collectionName);
+		return executeFindOneInternal(new FindOneCallback(mappedQuery, mappedFields), new ReadDbObjectCallback<T>(
+				this.mongoConverter, entityClass, collectionName), collectionName);
 	}
 
 	/**
@@ -1725,8 +1734,8 @@ protected <T> T doFindOne(String collectionName, DBObject query, DBObject fields
 	 * @return the List of converted objects.
 	 */
 	protected <T> List<T> doFind(String collectionName, DBObject query, DBObject fields, Class<T> entityClass) {
-		return doFind(collectionName, query, fields, entityClass, null,
-				new ReadDbObjectCallback<T>(this.mongoConverter, entityClass, collectionName));
+		return doFind(collectionName, query, fields, entityClass, null, new ReadDbObjectCallback<T>(this.mongoConverter,
+				entityClass, collectionName));
 	}
 
 	/**
@@ -1744,8 +1753,8 @@ protected <T> List<T> doFind(String collectionName, DBObject query, DBObject fie
 	 */
 	protected <T> List<T> doFind(String collectionName, DBObject query, DBObject fields, Class<T> entityClass,
 			CursorPreparer preparer) {
-		return doFind(collectionName, query, fields, entityClass, preparer,
-				new ReadDbObjectCallback<T>(mongoConverter, entityClass, collectionName));
+		return doFind(collectionName, query, fields, entityClass, preparer, new ReadDbObjectCallback<T>(mongoConverter,
+				entityClass, collectionName));
 	}
 
 	protected <S, T> List<T> doFind(String collectionName, DBObject query, DBObject fields, Class<S> entityClass,
@@ -1898,8 +1907,8 @@ private <T> T executeFindOneInternal(CollectionCallback<DBObject> collectionCall
 			DbObjectCallback<T> objectCallback, String collectionName) {
 
 		try {
-			T result = objectCallback
-					.doWith(collectionCallback.doInCollection(getAndPrepareCollection(getDb(), collectionName)));
+			T result = objectCallback.doWith(collectionCallback.doInCollection(getAndPrepareCollection(getDb(),
+					collectionName)));
 			return result;
 		} catch (RuntimeException e) {
 			throw potentiallyConvertRuntimeException(e, exceptionTranslator);
@@ -1924,8 +1933,8 @@ private <T> T executeFindOneInternal(CollectionCallback<DBObject> collectionCall
 	 * @param collectionName the collection to be queried
 	 * @return
 	 */
-	private <T> List<T> executeFindMultiInternal(CollectionCallback<DBCursor> collectionCallback, CursorPreparer preparer,
-			DbObjectCallback<T> objectCallback, String collectionName) {
+	private <T> List<T> executeFindMultiInternal(CollectionCallback<DBCursor> collectionCallback,
+			CursorPreparer preparer, DbObjectCallback<T> objectCallback, String collectionName) {
 
 		try {
 
@@ -2015,8 +2024,8 @@ String determineCollectionName(Class<?> entityClass) {
 
 		MongoPersistentEntity<?> entity = mappingContext.getPersistentEntity(entityClass);
 		if (entity == null) {
-			throw new InvalidDataAccessApiUsageException(
-					"No Persistent Entity information found for the class " + entityClass.getName());
+			throw new InvalidDataAccessApiUsageException("No Persistent Entity information found for the class "
+					+ entityClass.getName());
 		}
 		return entity.getCollection();
 	}
@@ -2080,8 +2089,8 @@ private void handleCommandError(CommandResult result, DBObject source) {
 			String error = result.getErrorMessage();
 			error = error == null ? "NO MESSAGE" : error;
 
-			throw new InvalidDataAccessApiUsageException(
-					"Command execution failed:  Error [" + error + "], Command = " + source, ex);
+			throw new InvalidDataAccessApiUsageException("Command execution failed:  Error [" + error + "], Command = "
+					+ source, ex);
 		}
 	}
 
@@ -2277,8 +2286,7 @@ public T doWith(DBObject object) {
 
 	class UnwrapAndReadDbObjectCallback<T> extends ReadDbObjectCallback<T> {
 
-		public UnwrapAndReadDbObjectCallback(EntityReader<? super T, DBObject> reader, Class<T> type,
-				String collectionName) {
+		public UnwrapAndReadDbObjectCallback(EntityReader<? super T, DBObject> reader, Class<T> type, String collectionName) {
 			super(reader, type, collectionName);
 		}
 

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/convert/GeoConverters.java

@@ -117,6 +117,10 @@ public Point convert(DBObject source) {
 
 			Assert.isTrue(source.keySet().size() == 2, "Source must contain 2 elements");
 
+			if (source.containsField("type")) {
+				return DbObjectToGeoJsonPointConverter.INSTANCE.convert(source);
+			}
+
 			return new Point((Double) source.get("x"), (Double) source.get("y"));
 		}
 	}