From e4d44e4a1700bfc9b3d66e9fc5e2adb7a904010a Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Thu, 23 Dec 2010 14:46:13 -0500 Subject: [PATCH] Add javadocs. --- .../document/mongodb/CollectionOptions.java | 15 +- .../document/mongodb/MongoOperations.java | 424 +++++++++++++++++- .../data/document/mongodb/MongoReader.java | 14 + .../data/document/mongodb/MongoTemplate.java | 6 +- .../data/document/mongodb/MongoWriter.java | 14 + 5 files changed, 444 insertions(+), 29 deletions(-) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/CollectionOptions.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/CollectionOptions.java index 3c884ae32..eb6fb7d15 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/CollectionOptions.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/CollectionOptions.java @@ -15,6 +15,12 @@ */ package org.springframework.data.document.mongodb; +/** + * Provides a simple wrapper to encapsulate the variety of settings you can use when creating a collection. + * + * @author Thomas Risberg + * + */ public class CollectionOptions { private Integer maxDocuments; @@ -23,8 +29,13 @@ public class CollectionOptions { private Boolean capped; - - + /** + * Constructs a new CollectionOptions instance. + * @param size the collection size in bytes, this data space is preallocated + * @param maxDocuments the maximum number of documents in the collection. + * @param capped true to created a "capped" collection (fixed size with auto-FIFO behavior + * based on insertion order), false otherwise. + */ public CollectionOptions(Integer size, Integer maxDocuments, Boolean capped) { super(); this.maxDocuments = maxDocuments; diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java index ac6f8208a..9d6167929 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java @@ -1,3 +1,18 @@ +/* + * Copyright 2010 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.document.mongodb; import java.util.List; @@ -5,100 +20,371 @@ import java.util.List; import com.mongodb.DBCollection; import com.mongodb.DBObject; +/** + * Interface that specifies a basic set of MongoDB operations. Implemented by {@link MongoTemplate}. + * Not often used but a useful option for extensibility and testability (as it can be easily mocked, stubbed, or be + * the target of a JDK proxy). + * + * @author Thomas Risberg + * @author Mark Pollack + * + */ public interface MongoOperations { + /** + * The default collection name used by this template. + * @return + */ String getDefaultCollectionName(); /** + * The default collection used by this template * @return The default collection used by this template */ DBCollection getDefaultCollection(); + + /** + * Execute the a MongoDB command expressed as a JSON string. This will call the method + * JSON.parse that is part of the MongoDB driver to convert the JSON string to a DBObject. + * Any errors that result from executing this command will be converted into Spring's DAO + * exception hierarchy. + * @param jsonCommand a MongoDB command expressed as a JSON string. + */ void executeCommand(String jsonCommand); + /** + * Execute a MongoDB command. Any errors that result from executing this command will be converted + * into Spring's DAO exception hierarchy. + * @param command a MongoDB command + */ void executeCommand(DBObject command); /** - * Executes a {@link DBCallback} translating any exceptions as necessary + * Executes a {@link DBCallback} translating any exceptions as necessary. * - * @param The return type - * @param action The action to execute + * Allows for returning a result object, that is a domain object or a collection of domain objects. * - * @return The return value of the {@link DBCallback} + * @param return type + * @param action callback object that specifies the MongoDB actions to perform on the passed in DB instance. + * + * @return a result object returned by the action or null */ T execute(DBCallback action); /** * Executes the given {@link CollectionCallback} on the default collection. * - * @param - * @param callback - * @return + * Allows for returning a result object, that is a domain object or a collection of domain objects. + * + * @param return type + * @param action callback object that specifies the MongoDB action + * @return a result object returned by the action or null */ - T execute(CollectionCallback callback); + T execute(CollectionCallback action); /** * Executes the given {@link CollectionCallback} on the collection of the given name. * - * @param - * @param callback - * @param collectionName - * @return + * Allows for returning a result object, that is a domain object or a collection of domain objects. + * + * @param return type + * @param action callback object that specifies the MongoDB action + * @param collectionName the name of the collection that specifies which DBCollection instance will be passed into + * the callback action. + * @return a result object returned by the action or null */ - T execute(CollectionCallback callback, String collectionName); + T execute(CollectionCallback action, String collectionName); + /** + * Executes the given {@link DBCallback} within the same connection to the database so as to ensure + * consistency in a write heavy environment where you may read the data that you wrote. See the + * comments on {@see Java Driver Concurrency} + * + * Allows for returning a result object, that is a domain object or a collection of domain objects. + * + * @param return type + * @param action callback that specified the MongoDB actions to perform on the DB instance + * @return a result object returned by the action or null + */ T executeInSession(DBCallback action); + /** + * Create an uncapped collection with the provided name. + * @param collectionName name of the collection + * @return the created collection + */ DBCollection createCollection(String collectionName); - void createCollection(String collectionName, - CollectionOptions collectionOptions); + /** + * Create a collect with the provided name and options + * @param collectionName name of the collection + * @param collectionOptions options to use when creating the collection. + */ + void createCollection(String collectionName, CollectionOptions collectionOptions); + /** + * A list of collection names + * @return list of collection names + */ List getCollectionNames(); + /** + * Get a collection by name, creating it if it doesn't exist. + * + * Translate any exceptions as necessary. + * + * @param collectionName name of the collection + * @return an existing collection or a newly created one. + */ DBCollection getCollection(String collectionName); + /** + * Check to see if a collection with a given name exists. + * + * Translate any exceptions as necessary. + * + * @param collectionName name of the collection + * @return true if a collection with the given name is found, false otherwise. + */ boolean collectionExists(String collectionName); + /** + * Drop the collection with the given name. + * + * Translate any exceptions as necessary. + * + * @param collectionName name of the collection to drop/delete. + */ void dropCollection(String collectionName); + /** + * Insert the object into the default collection. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property + * is a String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from + * ObjectId to your property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's + * new Type Conversion API. + * See Spring 3 Type Conversion" + * for more details. + * + * + * Insert is used to initially store the object into the database. + * To update an existing object use the save method. + * + * @param objectToSave the object to store in the collection. + */ void insert(Object objectToSave); + /** + * Insert the object into the specified collection. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * Insert is used to initially store the object into the + * database. To update an existing object use the save method. + * + * @param collectionName name of the collection to store the object in + * @param objectToSave the object to store in the collection + */ void insert(String collectionName, Object objectToSave); + /** + * Insert the object into the specified collection. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoWriter} + * + * Insert is used to initially store the object into the + * database. To update an existing object use the save method. + * + * @param the type of the object to insert + * @param collectionName name of the collection to store the object in + * @param objectToSave the object to store in the collection + * @param writer the writer to convert the object to save into a DBObject + */ void insert(String collectionName, T objectToSave, MongoWriter writer); + /** + * Insert a list of objects into the default collection in a single batch write to the database. + * + * @param listToSave the list of objects to save. + */ void insertList(List listToSave); + /** + * Insert a list of objects into the specified collection in a single batch write to the database. + * @param collectionName name of the collection to store the object in + * @param listToSave the list of objects to save. + */ void insertList(String collectionName, List listToSave); - void insertList(String collectionName, List listToSave, - MongoWriter writer); + /** + * Insert a list of objects into the specified collection using the provided MongoWriter instance + * + * @param the type of object being saved + * @param collectionName name of the collection to store the object in + * @param listToSave the list of objects to save. + * @param writer the writer to convert the object to save into a DBObject + */ + void insertList(String collectionName, List listToSave, MongoWriter writer); + /** + * Save the object to the default collection. This will perform an insert if the object is not already + * present, that is an 'upsert'. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property + * is a String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from + * ObjectId to your property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's + * new Type Conversion API. + * See Spring 3 Type Conversion" + * for more details. + * + * @param objectToSave the object to store in the collection + */ void save(Object objectToSave); + /** + * Save the object to the specified collection. This will perform an insert if the object is not already + * present, that is an 'upsert'. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * If you object has an "Id' property, it will be set with the generated Id from MongoDB. If your Id property + * is a String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from + * ObjectId to your property type will be handled by Spring's BeanWrapper class that leverages Spring 3.0's + * new Type Cobnversion API. + * See Spring 3 Type Conversion" + * for more details. + * + * @param collectionName name of the collection to store the object in + * @param objectToSave the object to store in the collection + */ void save(String collectionName, Object objectToSave); + /** + * Save the object into the specified collection. This will perform an insert if the object is not already + * present, that is an 'upsert'. + * + * The object is converted to the MongoDB native representation using an instance of + * {@see MongoWriter} + * + * @param the type of the object to insert + * @param collectionName name of the collection to store the object in + * @param objectToSave the object to store in the collection + * @param writer the writer to convert the object to save into a DBObject + */ void save(String collectionName, T objectToSave, MongoWriter writer); + /** + * Updates the first object that is found in the default collection that matches the query document + * with the provided updated document. + * + * @param queryDoc the query document that specifies the criteria used to select a record to be updated + * @param updateDoc the update document that contains the updated object or $ operators to manipulate the + * existing object. + */ void updateFirst(DBObject queryDoc, DBObject updateDoc); + /** + * Updates the first object that is found in the specified collection that matches the query document criteria + * with the provided updated document. + * + * @param collectionName name of the collection to update the object in + * @param queryDoc the query document that specifies the criteria used to select a record to be updated + * @param updateDoc the update document that contains the updated object or $ operators to manipulate the + * existing object. + */ void updateFirst(String collectionName, DBObject queryDoc, DBObject updateDoc); + /** + * Updates all objects that are found in the default collection that matches the query document criteria + * with the provided updated document. + * + * @param queryDoc the query document that specifies the criteria used to select a record to be updated + * @param updateDoc the update document that contains the updated object or $ operators to manipulate the + * existing object. + */ void updateMulti(DBObject queryDoc, DBObject updateDoc); + /** + * Updates all objects that are found in the specified collection that matches the query document criteria + * with the provided updated document. + * + * @param collectionName name of the collection to update the object in + * @param queryDoc the query document that specifies the criteria used to select a record to be updated + * @param updateDoc the update document that contains the updated object or $ operators to manipulate the + * existing object. + */ void updateMulti(String collectionName, DBObject queryDoc, DBObject updateDoc); + /** + * Remove all documents from the default collection that match the provide query document criteria. + * @param queryDoc the query document that specifies the criteria used to remove a record + */ void remove(DBObject queryDoc); + /** + * Remove all documents from the specified collection that match the provide query document criteria. + * @param collectionName name of the collection where the objects will removed + * @param queryDoc the query document that specifies the criteria used to remove a record + */ void remove(String collectionName, DBObject queryDoc); + /** + * Query for a list of objects of type T from the default collection. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient + * way to map objects since the test for class type is done in the client and not on the server. + * + * @param targetClass the parameterized type of the returned list + * @return the converted collection + */ List getCollection(Class targetClass); + /** + * Query for a list of objects of type T from the specified collection. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient + * way to map objects since the test for class type is done in the client and not on the server. + * @param collectionName name of the collection to retrieve the objects from + * @param targetClass the parameterized type of the returned list. + * @return the converted collection + */ List getCollection(String collectionName, Class targetClass); + /** + * Query for a list of objects of type T from the specified collection, mapping the DBObject using + * the provided MongoReader. + * + * + * @param collectionName name of the collection to retrieve the objects from + * @param targetClass the parameterized type of the returned list. + * @param reader the MongoReader to convert from DBObject to an object. + * @return the converted collection + */ List getCollection(String collectionName, Class targetClass, MongoReader reader); @@ -113,21 +399,111 @@ public interface MongoOperations { List queryUsingJavaScript(String collectionName, String query, Class targetClass, MongoReader reader); + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List of the specified type. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * NOTE: A generic criteria API will be introduced in a future release. You can see the + * inconsequential project for an example of how that + * may look. + * + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @return the List of converted objects + */ List query(DBObject query, Class targetClass); + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List of the specified type. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @param preparer allows for customization of the DBCursor used when iterating over the result set, + * (apply limits, skips and so on). + * @return the List of converted objects. + */ List query(DBObject query, Class targetClass, CursorPreparer preparer); - + + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List using the provided MongoReader + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @param reader the MongoReader to convert from DBObject to an object. + * @return the List of converted objects. + */ List query(DBObject query, Class targetClass, MongoReader reader); - List query(String collectionName, DBObject query, - Class targetClass); + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List of the specified type. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * NOTE: A generic criteria API will be introduced in a future release. You can see the + * inconsequential project for an example of how that + * may look. + * + * @param collectionName name of the collection to retrieve the objects from + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @return the List of converted objects + */ + List query(String collectionName, DBObject query, Class targetClass); - List query(String collectionName, DBObject query, - Class targetClass, CursorPreparer preparer); + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List of the specified type. + * + * The object is converted from the MongoDB native representation using an instance of + * {@see MongoConverter}. Unless configured otherwise, an + * instance of SimpleMongoConverter will be used. + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * @param collectionName name of the collection to retrieve the objects from + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @param preparer allows for customization of the DBCursor used when iterating over the result set, + * (apply limits, skips and so on). + * @return the List of converted objects. + */ + List query(String collectionName, DBObject query, Class targetClass, CursorPreparer preparer); - List query(String collectionName, DBObject query, - Class targetClass, MongoReader reader); + /** + * Map the results of an ad-hoc query on the default MongoDB collection to a List using the provided MongoReader + * + * The query document is specified as a standard DBObject. You can use the driver's QueryBuilder to + * more easily create a query document. + * + * @param collectionName name of the collection to retrieve the objects from + * @param query the query document that specifies the criteria used to find a record + * @param targetClass the parameterized type of the returned list. + * @param reader the MongoReader to convert from DBObject to an object. + * @return the List of converted objects. + */ + List query(String collectionName, DBObject query, Class targetClass, MongoReader reader); } \ No newline at end of file diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoReader.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoReader.java index 5c081147b..3916df1b9 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoReader.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoReader.java @@ -17,7 +17,21 @@ package org.springframework.data.document.mongodb; import com.mongodb.DBObject; +/** + * A MongoWriter is responsible for converting a native MongoDB DBObject to an object of type T. + * + * @author Mark Pollack + * @author Thomas Risberg + * + * @param the type of the object to convert from a DBObject + */ public interface MongoReader { + /** + * Ready from the native MongoDB DBObject representation to an instance of the class T. + * @param clazz the type of the return value + * @param dbo theDBObject + * @return the converted object + */ T read(Class clazz, DBObject dbo); } diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoTemplate.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoTemplate.java index c0a55744b..c794f4e83 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoTemplate.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoTemplate.java @@ -153,8 +153,8 @@ public class MongoTemplate implements InitializingBean, MongoOperations { /* (non-Javadoc) * @see org.springframework.data.document.mongodb.MongoOperations#execute(org.springframework.data.document.mongodb.CollectionCallback) */ - public T execute(CollectionCallback callback) { - return execute(callback, defaultCollectionName); + public T execute(CollectionCallback action) { + return execute(action, defaultCollectionName); } /* (non-Javadoc) @@ -609,7 +609,7 @@ public class MongoTemplate implements InitializingBean, MongoOperations { return dbo; } - private void populateIdIfNecessary(Object savedObject, Object id) { + protected void populateIdIfNecessary(Object savedObject, Object id) { //TODO Needs proper conversion support and should be integrated with reader implementation somehow BeanWrapper bw = PropertyAccessorFactory.forBeanPropertyAccess(savedObject); PropertyDescriptor idPd = BeanUtils.getPropertyDescriptor(savedObject.getClass(), "id"); diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoWriter.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoWriter.java index 8635fc9b3..8aa02b128 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoWriter.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoWriter.java @@ -17,7 +17,21 @@ package org.springframework.data.document.mongodb; import com.mongodb.DBObject; +/** + * A MongoWriter is responsible for converting an object of type T to the native MongoDB representation DBObject. + * + * @author Mark Pollack + * @author Thomas Risberg + * + * @param the type of the object to convert to a DBObject + */ public interface MongoWriter { + /** + * Write the given object of type T to the native MongoDB object representation DBObject. + * @param t The object to convert to a DBObject + * @param dbo The DBObject to use for writing. + */ void write(T t, DBObject dbo); + }