diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml index ec24086fa..90979cc3e 100644 --- a/src/docbkx/introduction/introduction.xml +++ b/src/docbkx/introduction/introduction.xml @@ -12,21 +12,29 @@ Knowing Spring Spring Data uses Spring framework's core - functionality, such as the IoC - container and Data Access abstractions such as the portable - exception hierarchy. While it is not important to know the Spring APIs, - understanding the concepts behind them is. At a minimum, the idea behind - IoC should be familiar for whatever IoC container you choose to use. - + url="http://static.springframework.org/spring/docs/3.0.x/reference/spring-core.html">core + functionality, such as the IoC + container, type + conversion system, expression + language, JMX + integration, and portable DAO + exception hierarchy. While it is not important to know the + Spring APIs, understanding the concepts behind them is. At a minimum, + the idea behind IoC should be familiar for whatever IoC container you + choose to use. The core functionality of the MongoDB and CouchDB support can be - used directly, with no references to the Spring Container, much like - JdbcTemplate can be used 'standalone' without any other services of the - Spring container. To leverage all the features of Spring Data document, - such as it's repository support, then you will need to configure the - container using Spring. + used directly, with no need to invoke the IoC services of the Spring + Container. This is much like JdbcTemplate which + can be used 'standalone' without any other services of the Spring + container. To leverage all the features of Spring Data document, such as + the repository support, you will need to configure some parts of the + library using Spring. To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 40f1eacfc..b8010e53e 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -140,7 +140,7 @@ log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %40.40c:%4L - %m Create a simple Person class to persist - package org.spring.example; + package org.spring.mongodb.example; public class Person { @@ -172,7 +172,7 @@ public class Person { And a main application to run - package org.spring.example; + package org.spring.mongodb.example; import static org.springframework.data.document.mongodb.query.Criteria.where; @@ -205,61 +205,96 @@ public class MongoApp { 10:01:32,062 DEBUG apping.MongoPersistentEntityIndexCreator: 80 - Analyzing class class org.spring.example.Person for index information. 10:01:32,265 DEBUG work.data.document.mongodb.MongoTemplate: 631 - insert DBObject containing fields: [_class, age, name] in collection: Person 10:01:32,765 DEBUG work.data.document.mongodb.MongoTemplate:1243 - findOne using query: { "name" : "Joe"} in db.collection: database.Person -10:01:32,953 INFO org.spring.example.MongoApp: 25 - Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34] +10:01:32,953 INFO org.spring.mongodb.example.MongoApp: 25 - Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34] 10:01:32,984 DEBUG work.data.document.mongodb.MongoTemplate: 375 - Dropped collection [database.person] - The quick brown fox. + Even in this simple example, there are few things to take notice + of + + + + You can instantiate the central helper class of Spring Mongo, + MongoTemplate, using the + standard com.mongodb.Mongo object and the name + of the database to use. + + + + The mapper works against standard POJO objects without the need + for any additional metadata (though you can optionally provide that + information. See here.). + + + + Conventions are used for handling the id field, converting it to + be a ObjectId when stored in the database. + + + + Mapping conventions can use field access. Notice the Person + class has only getters. + + + + If the constructor argument names match the field names of the + stored document, they will be used to instantiate the object + + + +
+ -
Required Jars - - - spring-data-document-core-1.0.0.M3.jar - + The following jars are required to use Sping Mongo - - spring-data-mongodb-1.0.0.M3.jar - - In addition to the above listed Spring Data jars - you need to provide the following dependencies: - - com.springsource.org.aopalliance-1.0.0.jar - + + + spring-data-mongodb-1.0.0.M3.jar + + - - commons-logging-1.1.1.jar - + In addition to the above listed Spring Data jars you need to provide the following dependencies: - - mongo-java-driver-2.5.3.jar - + + + com.springsource.org.aopalliance-1.0.0.jar + - - spring-aop-3.0.5.RELEASE.jar - + + commons-logging-1.1.1.jar + - - spring-asm-3.0.5.RELEASE.jar - + + mongo-java-driver-2.5.3.jar + - - spring-beans-3.0.5.RELEASE.jar - + + spring-aop-3.0.5.RELEASE.jar + - - spring-context-3I.0.5.RELEASE.jar - + + spring-asm-3.0.5.RELEASE.jar + - - spring-core-3.0.5.RELEASE.jar - + + spring-beans-3.0.5.RELEASE.jar + - - spring-expression-3.0.5.RELEASE.jar - - - + + spring-context-3I.0.5.RELEASE.jar + + + + spring-core-3.0.5.RELEASE.jar + + + + spring-expression-3.0.5.RELEASE.jar + + + +
@@ -273,7 +308,7 @@ public class MongoApp {
- Connecting to MongoDB + Connecting to MongoDB with Spring One of the first tasks when using MongoDB and Spring is to create a com.mongodb.Mongo object using the IoC container. @@ -290,7 +325,7 @@ public class MongoApp {
- Using Java based metadata + Registering a Mongo instance using Java based metadata An example of using Java based bean metadata to register an instance of a com.mongodb.Mongo is shown below @@ -304,7 +339,7 @@ public class AppConfig { /* * Use the standard Mongo driver API to create a com.mongodb.Mongo instance. */ - public @Bean Mongo mongo() throws Exception { + public @Bean Mongo mongo() throws UnknownHostException { return new Mongo("localhost"); } } @@ -313,19 +348,24 @@ public class AppConfig { This approach allows you to use the standard com.mongodb.Mongo API that you may already be used to using but also pollutes the code with the UnknownHostException - checked exception. + checked exception. The use of the checked exception is not desirable as + Java based bean metadata uses methods as a means to set object + dependencies, making the calling code cluttered. - You may also register an instance of + An alternative is to register an instance of com.mongodb.Mongo instance with the container using Spring's MongoFactoryBean. As compared to instantiating a com.mongodb.Mongo - instance directly, the FactoryBean approach has the added advantage of - also providing the container with an ExceptionTranslator that can - translate Mongo exceptions to exceptions in Spring's portable - DataAccessException hierarchy. This hierarchy is - described in DataAccessException hierarchy for data access + classes annoated with the @Repository annotation. + This hierarchy and use of @Repository is described in + Spring's - DAO support features. An example is shown below + DAO support features. An example of a Java based bean metadata that supports exception translation on @Repository annotated classes is @@ -350,25 +390,23 @@ public class AppConfig { } - To access the com.mongodb.Mongo object created by the - MongoFactoryBean in other @Configuration or - your own classes, use a "private @Autowired Mongo - mongo;" field. + To access the com.mongodb.Mongo object + created by the MongoFactoryBean in other + @Configuration or your own classes, use a + "private @Autowired Mongo mongo;" field.
- Using XML based metadata + Registering a Mongo instance using XML based metadata - While you can use Spring's traditional <beans/> XML - namespace to register an instance of - com.mongodb.Mongo with the container, the XML can - be quite verbose, does not easily support the configuration of public - instance variables used with the driver's MongoOptions class, and - constructor arguments/names are not the most effective means to - distinguish between configuration of replica sets and replica pairs. o - address these issues a XML namespace is available to simplify the - configuration of a com.mongodb.Mongo instance in XML. + While you can use Spring's traditional + <beans/> XML namespace to register an instance + of com.mongodb.Mongo with the container, the XML + can be quite verbose as it is general purpose. XML namespaces are a + better alternative to configuring commonly used objects such as the + Mongo instance. The mongo namespace alows you to create a Mongo instance + server location, replica-sets, and options. To use the Mongo namespace elements you will need to reference the Mongo schema: @@ -384,75 +422,63 @@ public class AppConfig { xsi:schemaLocation= "http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd - http://www.springframework.org/schema/data/mongo - http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd + http://www.springframework.org/schema/data/mongo + http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"> <!-- Default bean name is 'mongo' --> - <mongo:mongo host="localhost" port="27017"/> - - <!-- To translate any MongoExceptions thrown in @Repository annotated classes --> - <context:annotation-config/> + <mongo:mongo host="localhost" port="27017"/> </beans> - A more advanced configuration with MongoOptions is shown - below + A more advanced configuration with MongoOptions is shown below + (note these are not recommended values) - XML schema to configure MongoOptinos in MongoDB + XML schema to configure a com.mongodb.Mongo object with + MongoOptions <beans> <mongo:mongo host="localhost" port="27017"> - <mongo:options connectionsPerHost="10" - threadsAllowedToBlockForConnectionMultiplier="5" - maxWaitTime="12000" - connectTimeout="0" - socketTimeout="0" - autoConnectRetry="0"/> + <mongo:options connections-per-host="8" + threads-allowed-to-block-for-connection-multiplier="4" + connect-timeout="1000" + max-wait-time="1500}" + auto-connect-retry="true" + socket-keep-alive="true" + socket-timeout="1500" + slave-ok="true" + write-number="1" + write-timeout="0" + write-fsync="true"/> </mongo:mongo/> </beans> - A configuration using replica sets within the XML schema is not - yet available. If you would like to configure ReplicaSets use Spring's - Java based bean metadata shown below: - Configuring a com.mongodb.Mongo object with Replica Sets - using Java based bean metadata + A configuration using replica sets is shown below. + XML schema to configure com.mongodb.Mongo object with Replica + Sets - @Configuration -public class AppConfig { - - /* - * Use the standard Mongo driver API to create a com.mongodb.Mongo instance that supports replica sets - */ - @Bean - public Mongo mongo() throws Exception { - - List<ServerAddress> serverAddresses = new ArrayList<ServerAddress>(); - serverAddresses.add( new ServerAddress( "127.0.0.1", 27017 ) ); - serverAddresses.add( new ServerAddress( "127.0.0.1", 27018 ) ); - - MongoOptions options = new MongoOptions(); - options.autoConnectRetry = true; - - Mongo mongo = new Mongo( serverAddresses, options ); - mongo.slaveOk(); - - return mongo; - } -} + <mongo:mongo id="replicaSetMongo" replica-set="127.0.0.1:27017,localhost:27018"/>
+ +
+ Registering a MongoDbFactory instance using Java based + metadata + + As an alternative to configuring a com.mongodb.Mongo instance and + later providing the database name, the MongoDbFactory +
-
+
Introduction to MongoTemplate The class MongoTemplate, located in the