mindol1004/spring-data-mongodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add javadocs.

Browse Source
This commit is contained in:
Mark Pollack
2010-12-23 14:46:13 -05:00
parent a7127bb312
commit e4d44e4a17
5 changed files with 444 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/CollectionOptions.java
View File

@@ -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 <code>CollectionOptions</code> 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;

422
spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java
View File

@@ -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 <T> 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 <T> 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 <tt>null</tt>
*/
<T> T execute(DBCallback<T> action);
/**
* Executes the given {@link CollectionCallback} on the default collection.
*
* @param <T>
* @param callback
* @return
* Allows for returning a result object, that is a domain object or a collection of domain objects.
*
* @param <T> return type
* @param action callback object that specifies the MongoDB action
* @return a result object returned by the action or <tt>null</tt>
*/
<T> T execute(CollectionCallback<T> callback);
<T> T execute(CollectionCallback<T> action);
/**
* Executes the given {@link CollectionCallback} on the collection of the given name.
*
* @param <T>
* @param callback
* @param collectionName
* @return
* Allows for returning a result object, that is a domain object or a collection of domain objects.
*
* @param <T> 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 <tt>null</tt>
*/
<T> T execute(CollectionCallback<T> callback, String collectionName);
<T> T execute(CollectionCallback<T> 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 <a href=http://www.mongodb.org/display/DOCS/Java+Driver+Concurrency>Java Driver Concurrency</a>}
*
* Allows for returning a result object, that is a domain object or a collection of domain objects.
*
* @param <T> 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 <tt>null</tt>
*/
<T> T executeInSession(DBCallback<T> 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<String> 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 <a href="http://static.springsource.org/spring/docs/3.0.x/reference/validation.html#core-convert">Spring 3 Type Conversion"</a>
* 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 <T> 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
*/
<T> void insert(String collectionName, T objectToSave, MongoWriter<T> 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<Object> 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<Object> listToSave);
<T> void insertList(String collectionName, List<T> listToSave,
MongoWriter<T> writer);
/**
* Insert a list of objects into the specified collection using the provided MongoWriter instance
*
* @param <T> 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
*/
<T> void insertList(String collectionName, List<T> listToSave, MongoWriter<T> 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 <a href="http://static.springsource.org/spring/docs/3.0.x/reference/validation.html#core-convert">Spring 3 Type Conversion"</a>
* 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 <a href="http://static.springsource.org/spring/docs/3.0.x/reference/validation.html#core-convert">Spring 3 Type Conversion"</a>
* 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 <T> 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
*/
<T> void save(String collectionName, T objectToSave, MongoWriter<T> 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
*/
<T> List<T> getCollection(Class<T> 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
*/
<T> List<T> getCollection(String collectionName, Class<T> 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
*/
<T> List<T> getCollection(String collectionName, Class<T> targetClass,
MongoReader<T> reader);
@@ -113,21 +399,111 @@ public interface MongoOperations {
<T> List<T> queryUsingJavaScript(String collectionName, String query,
Class<T> targetClass, MongoReader<T> 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
* <a href="https://github.com/grails/inconsequential">inconsequential</a> 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
*/
<T> List<T> query(DBObject query, Class<T> 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.
*/
<T> List<T> query(DBObject query, Class<T> 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.
*/
<T> List<T> query(DBObject query, Class<T> targetClass,
MongoReader<T> reader);
<T> List<T> query(String collectionName, DBObject query,
Class<T> 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
* <a href="https://github.com/grails/inconsequential">inconsequential</a> 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
*/
<T> List<T> query(String collectionName, DBObject query, Class<T> targetClass);
<T> List<T> query(String collectionName, DBObject query,
Class<T> 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.
*/
<T> List<T> query(String collectionName, DBObject query, Class<T> targetClass, CursorPreparer preparer);
<T> List<T> query(String collectionName, DBObject query,
Class<T> targetClass, MongoReader<T> 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.
*/
<T> List<T> query(String collectionName, DBObject query, Class<T> targetClass, MongoReader<T> reader);
}

14
spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoReader.java
View File

@@ -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 <T> the type of the object to convert from a DBObject
*/
public interface MongoReader<T> {
/**
* 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<? extends T> clazz, DBObject dbo);
}

6
spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoTemplate.java
View File

@@ -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> T execute(CollectionCallback<T> callback) {
return execute(callback, defaultCollectionName);
public <T> T execute(CollectionCallback<T> 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");

14
spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoWriter.java
View File

@@ -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 <T> the type of the object to convert to a DBObject
*/
public interface MongoWriter<T> {
/**
* 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);
}