From b5e0b2bec2dc7f548a8d2987ea1d23331c95670f Mon Sep 17 00:00:00 2001 From: Oliver Gierke Date: Tue, 6 Dec 2011 19:04:06 +0100 Subject: [PATCH] DATAMONGO-340 - Polished reference documentation. Added section ids to generate stable URLs for HTML documentation. --- src/docbkx/reference/mongodb.xml | 255 +++++++++++++++---------------- 1 file changed, 124 insertions(+), 131 deletions(-) diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index e67027b32..0aca33c86 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -302,7 +302,7 @@ public class MongoApp { -
+
Migrating from M2 to M3 There were several API changes introduced in the M3 release. To @@ -356,7 +356,7 @@ public class MongoApp {
-
+
Examples Repository There is an . -
+
Registering a Mongo instance using Java based metadata An example of using Java based bean metadata to register an @@ -455,7 +455,7 @@ public class AppConfig {
-
+
Registering a Mongo instance using XML based metadata While you can use Spring's traditional @@ -527,7 +527,7 @@ public class AppConfig {
-
+
The MongoDbFactory interface While com.mongodb.Mongo is the entry point @@ -587,7 +587,7 @@ public class AppConfig { section.
-
+
Registering a MongoDbFactory instance using Java based metadata @@ -627,7 +627,7 @@ public class MongoConfiguration {
-
+
Registering a MongoDbFactory instance using XML based metadata @@ -908,22 +908,22 @@ public class AppConfig { INSERT_LIST, SAVE) and a few other pieces of contextual information. For example, - private class MyAppWriteConcernResolver implements WriteConcernResolver { - - public WriteConcern resolve(MongoAction action) { - if (action.getEntityClass().getSimpleName().contains("Audit")) { - return WriteConcern.NONE; - } else if (action.getEntityClass().getSimpleName().contains("Metadata")) { - return WriteConcern.JOURNAL_SAFE; - } - return action.getDefaultWriteConcern(); - } - } + private class MyAppWriteConcernResolver implements WriteConcernResolver { + + public WriteConcern resolve(MongoAction action) { + if (action.getEntityClass().getSimpleName().contains("Audit")) { + return WriteConcern.NONE; + } else if (action.getEntityClass().getSimpleName().contains("Metadata")) { + return WriteConcern.JOURNAL_SAFE; + } + return action.getDefaultWriteConcern(); + } +}
-
+
Saving, Updating, and Removing Documents MongoTemplate provides a simple way for you @@ -1048,7 +1048,7 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p The query stynax used in the example is explained in more detail in the section Querying Documents. -
+
How the '_id' field is handled in the mapping layer MongoDB requires that you have an '_id' field for all documents. @@ -1084,17 +1084,20 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p An id property or field declared as a String in the Java class - will be converted to and stored as an ObjectId if possible using a - Spring Converter<String, ObjectId>. Valid conversion rules are - delegated to the MongoDB Java driver. If it cannot be converted to - an ObjectId, then the value will be stored as a string in the - database. + will be converted to and stored as an + ObjectId if possible using a Spring + Converter<String, ObjectId>. + Valid conversion rules are delegated to the MongoDB Java driver. If it + cannot be converted to an ObjectId, then the value will be stored as + a string in the database. - An id property or field declared as BigInteger in the Java - class will be converted to and stored as an ObjectId using a Spring - Converter<BigInteger, ObjectId>. + An id property or field declared as + BigInteger in the Java class will be + converted to and stored as an ObjectId using + a Spring Converter<BigInteger, + ObjectId>. @@ -1110,15 +1113,16 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p domain classes.
-
+
Methods for saving and inserting documents There are several convenient methods on MongoTemplate for saving and inserting your objects. To have more fine grained control over the conversion process - you can register Spring converters with the MappingMongoConverter, for - example Converter<Person, DBObject> and Converter<DBObject, - Person>. + you can register Spring converters with the + MappingMongoConverter, for example + Converter<Person, DBObject> and + Converter<DBObject, Person>. The difference between insert and save operations is that a save @@ -1149,13 +1153,12 @@ DEBUG work.data.mongodb.core.MongoTemplate: 376 - Dropped collection [database.p import static org.springframework.data.mongodb.core.query.Criteria.where; import static org.springframework.data.mongodb.core.query.Criteria.query; - ... +… - Person p = new Person("Bob", 33); - mongoTemplate.insert(p); +Person p = new Person("Bob", 33); +mongoTemplate.insert(p); - Person qp = mongoTemplate.findOne(query(where("age").is(33)), Person.class); - +Person qp = mongoTemplate.findOne(query(where("age").is(33)), Person.class); The insert/save operations available to you are listed @@ -1191,7 +1194,7 @@ import static org.springframework.data.mongodb.core.query.Criteria.query; -
+
Which collection will my documents be saved into? There are two ways to manage the collection name that is used @@ -1204,7 +1207,7 @@ import static org.springframework.data.mongodb.core.query.Criteria.query; parameter for the selected MongoTemplate method calls.
-
+
Inserting or saving individual objects The MongoDB driver supports inserting a collection of documents @@ -1233,7 +1236,7 @@ import static org.springframework.data.mongodb.core.query.Criteria.query;
-
+
Inserting several objects in a batch The MongoDB driver supports inserting a collection of documents @@ -1286,7 +1289,7 @@ import static org.springframework.data.mongodb.core.query.Update; Update object to provide a fluent style for the API. -
+
Methods for executing updates for documents @@ -1302,11 +1305,9 @@ import static org.springframework.data.mongodb.core.query.Update; updated document. - -
-
+
Methods for the Update class The Update class can be used with a little 'syntax sugar' as its @@ -1386,7 +1387,7 @@ import static org.springframework.data.mongodb.core.query.Update;
-
+
Upserting documents in a collection Related to perfomring an updateFirst @@ -1446,7 +1447,7 @@ assertThat(p.getFirstName(), is("Mary")); assertThat(p.getAge(), is(1));
-
+
Methods for removing documents You can use several overloaded methods to remove an object from @@ -1528,7 +1529,7 @@ import static org.springframework.data.mongodb.core.query.Query.query; Criteria object to provide a fluent style for the API. -
+
Methods for the Criteria class @@ -1677,7 +1678,7 @@ import static org.springframework.data.mongodb.core.query.Query.query;
There are also methods on the Criteria class for geospatial - queries. Here is al isting but look at the section on GeoSpatial Queries to see them in action. @@ -1727,7 +1728,7 @@ import static org.springframework.data.mongodb.core.query.Query.query; The Query class has some additional methods used to provide options for the query. -
+
Methods for the Query class @@ -1768,7 +1769,7 @@ import static org.springframework.data.mongodb.core.query.Query.query;
-
+
Methods for querying for documents The query methods need to specify the target type T that will be @@ -2019,7 +2020,7 @@ public class ValueObject { private String id; private float value; - + public String getId() { return id; } @@ -2036,9 +2037,7 @@ public class ValueObject { public String toString() { return "ValueObject [id=" + id + ", value=" + value + "]"; } - -} - By default the output type of INLINE is used so you don't +} By default the output type of INLINE is used so you don't have to specify an output collection. To specify additional map-reduce options use an overloaded method that takes an additional MapReduceOptions argument. The class @@ -2046,24 +2045,21 @@ public class ValueObject { additional options can be done in a very compact syntax. Here an example that sets the output collection to "jmr1_out". Note that setting only the output collection assumes a default output type of REPLACE. - -MapReduceResults<ValueObject> results = mongoOperations.mapReduce("jmr1", "classpath:map.js", "classpath:reduce.js", - new MapReduceOptions().outputCollection("jmr1_out"), ValueObject.class); - There is also a static import import static + MapReduceResults<ValueObject> results = mongoOperations.mapReduce("jmr1", "classpath:map.js", "classpath:reduce.js", + new MapReduceOptions().outputCollection("jmr1_out"), ValueObject.class); + There is also a static import import static org.springframework.data.mongodb.core.mapreduce.MapReduceOptions.options; that can be used to make the syntax slightly more compact - -MapReduceResults<ValueObject> results = mongoOperations.mapReduce("jmr1", "classpath:map.js", "classpath:reduce.js", - options().outputCollection("jmr1_out"), ValueObject.class); - You can also specify a query to reduce the set of data that - will be used to feed into the map-reduce operation. This will remove the - document that contains [a,b] from consideration for map-reduce - operations. -Query query = new Query(where("x").ne(new String[] { "a", "b" })); + MapReduceResults<ValueObject> results = mongoOperations.mapReduce("jmr1", "classpath:map.js", "classpath:reduce.js", + options().outputCollection("jmr1_out"), ValueObject.class); + You can also specify a query to reduce the set of data that will be used + to feed into the map-reduce operation. This will remove the document + that contains [a,b] from consideration for map-reduce operations. + Query query = new Query(where("x").ne(new String[] { "a", "b" })); MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, "jmr1", "classpath:map.js", "classpath:reduce.js", - options().outputCollection("jmr1_out"), ValueObject.class); - Note that you can specify additional limit and sort values - as well on the query but not skip values. + options().outputCollection("jmr1_out"), ValueObject.class); + Note that you can specify additional limit and sort values as well on + the query but not skip values.
@@ -2092,7 +2088,7 @@ MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, " strings in your code. Note that you can still pass JavaScript code as Java strings if you prefer. -
+
Example Usage In order to understand how group operations work the following @@ -2143,38 +2139,33 @@ MapReduceResults<ValueObject> results = mongoOperations.mapReduce(query, " argument in the group method, in this case XObject which is shown below. - public class XObject { - - private float x; - - private float count; + public class XObject { + private float x; - public float getX() { - return x; - } + private float count; - public void setX(float x) { - this.x = x; - } - - - public float getCount() { - return count; - } + public float getX() { + return x; + } + public void setX(float x) { + this.x = x; + } - public void setCount(float count) { - this.count = count; - } + public float getCount() { + return count; + } + public void setCount(float count) { + this.count = count; + } - @Override - public String toString() { - return "XObject [x=" + x + " count = " + count + "]"; - } - + @Override + public String toString() { + return "XObject [x=" + x + " count = " + count + "]"; + } } You can also obtain tha raw result as a @@ -2199,7 +2190,7 @@ GroupByResults<XObject> results = mongoTemplate.group(where("x").gt(0),
-
+
Overriding default mapping with custom converters In order to have more fine grained control over the mapping process @@ -2222,7 +2213,7 @@ GroupByResults<XObject> results = mongoTemplate.group(where("x").gt(0), url="http://static.springsource.org/spring/docs/3.0.x/reference/validation.html#core-convert">here. -
+
Saving using a registered Spring Converter An example implementation of the @@ -2244,11 +2235,10 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { dbo.put("age", source.getAge()); return dbo; } - }
-
+
Reading using a Spring Converter An example implemention of a Converter that converts from a @@ -2261,11 +2251,10 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { p.setAge((Integer) source.get("age")); return p; } - }
-
+
Registering Spring Converters with the MongoConverter The mongo XSD namespace provides a convenience way to register @@ -2293,7 +2282,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> {
-
+
Index and Collection managment MongoTemplate provides a few methods for @@ -2322,7 +2311,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { } -
+
Methods for creating an Index We can create an index on a collection to improve query @@ -2351,7 +2340,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { mongoTemplate.indexOps(Venue.class).ensureIndex(new GeospatialIndex("location"));
-
+
Accessing index information The IndexOperations interface has the method getIndexInfo that @@ -2369,7 +2358,7 @@ List<IndexInfo> indexInfoList = template.indexOps(Person.class).getIndexIn
-
+
Methods for working with a Collection It's time to look at some code examples showing how to use the @@ -2416,15 +2405,16 @@ mongoTemplate.dropCollection("MyNewCollection");
-
+
Executing Commands You can also get at the MongoDB driver's DB.command( - ) method using the executeCommand methods on MongoTemplate. - These will also perform exception translation into Spring's Data Access - Exception hierarchy. + ) method using the executeCommand(…) + methods on MongoTemplate. These will also perform + exception translation into Spring's + DataAccessException hierarchy. -
+
Methods for executing commands @@ -2528,7 +2518,7 @@ mongoTemplate.dropCollection("MyNewCollection");
-
+
Exception Translation The Spring framework provides exception translation for a wide @@ -2551,15 +2541,16 @@ mongoTemplate.dropCollection("MyNewCollection"); MongoDB driver inherit from the MongoException class. The inner exception and message are preserved so no information is lost. - Some of the mappings performed by the MongoExceptionTranslator are: - com.mongodb.Network to DataAccessResourceFailureException and - MongoException error codes 1003, 12001, 12010, 12011, 12012 to - InvalidDataAccessApiUsageException. Look into the implementation for more - details on the mapping. + Some of the mappings performed by the + MongoExceptionTranslator are: com.mongodb.Network + to DataAccessResourceFailureException and + MongoException error codes 1003, 12001, 12010, + 12011, 12012 to InvalidDataAccessApiUsageException. + Look into the implementation for more details on the mapping.
- Execution Callback + Execution callbacks One common design feature of all Spring template classes is that all functionality is routed into one of the templates execute callback @@ -2568,7 +2559,8 @@ mongoTemplate.dropCollection("MyNewCollection"); greater need in the case of JDBC and JMS than with MongoDB, it still offers a single spot for exception translation and logging to occur. As such, using thexe execute callback is the preferred way to access the - MongoDB driver's DB and Collection objects to perform uncommon operations + MongoDB driver's DB and + DBCollection objects to perform uncommon operations that were not exposed as methods on MongoTemplate. @@ -2614,19 +2606,20 @@ mongoTemplate.dropCollection("MyNewCollection"); - Here is an example that uses the CollectionCallback to return - information about an index. - - boolean hasIndex = template.execute("geolocation", new CollectionCallback<Boolean>() { - public Boolean doInCollection(Venue.class, DBCollection collection) throws MongoException, DataAccessException { - List<DBObject> indexes = collection.getIndexInfo(); - for (DBObject dbo : indexes) { - if ("location_2d".equals(dbo.get("name"))) { - return true; - } - } - return false; + Here is an example that uses the + CollectionCallback to return information + about an index + + boolean hasIndex = template.execute("geolocation", new CollectionCallbackBoolean>() { + public Boolean doInCollection(Venue.class, DBCollection collection) throws MongoException, DataAccessException { + List<DBObject> indexes = collection.getIndexInfo(); + for (DBObject dbo : indexes) { + if ("location_2d".equals(dbo.get("name"))) { + return true; } - }); + } + return false; + } +});
- + \ No newline at end of file