Skip to content

DATAMONGO-1019: Correct examples in reference documentation #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DATAMONGO-1019: Correct examples in reference documentation #214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/main/asciidoc/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,11 @@
Mark Pollack, Thomas Risberg, Oliver Gierke, Costin Leau, Jon Brisbin, Thomas Darimont, Christoph Strobl
:toc:
:spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/issue/DATACMNS-551/src/main/asciidoc

{version}

© 2008-2014 The original authors.

NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._

include::preface.adoc[]
Expand Down
35 changes: 21 additions & 14 deletions src/main/asciidoc/reference/cross-store.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ Assuming that you have a working JPA application and would like to add some cros

First of all you need to add a dependency on the module. Using Maven this is done by adding a dependency to your pom:

=== Example Maven pom.xml with spring-data-mongodb-cross-store dependency

.Example Maven pom.xml with spring-data-mongodb-cross-store dependency
====
[source,xml]
----
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand All @@ -31,11 +31,12 @@ First of all you need to add a dependency on the module. Using Maven this is do

</project>
----
====

Once this is done we need to enable AspectJ for the project. The cross-store support is implemented using AspectJ aspects so by enabling compile time AspectJ support the cross-store features will become available to your project. In Maven you would add an additional plugin to the <build> section of the pom:

=== Example Maven pom.xml with AspectJ plugin enabled

.Example Maven pom.xml with AspectJ plugin enabled
====
[source,xml]
----
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand Down Expand Up @@ -100,11 +101,12 @@ Once this is done we need to enable AspectJ for the project. The cross-store sup

</project>
----
====

Finally, you need to configure your project to use MongoDB and also configure the aspects that are used. The following XML snippet should be added to your application context:

=== Example application context with MongoDB and cross-store aspect support

.Example application context with MongoDB and cross-store aspect support
====
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
Expand Down Expand Up @@ -150,14 +152,15 @@ Finally, you need to configure your project to use MongoDB and also configure th

</beans>
----
====

[[mongodb_cross-store-application]]
== Writing the Cross Store Application

We are assuming that you have a working JPA application so we will only cover the additional steps needed to persist part of your Entity in your Mongo database. First you need to identify the field you want persisted. It should be a domain class and follow the general rules for the Mongo mapping support covered in previous chapters. The field you want persisted in MongoDB should be annotated using the `@RelatedDocument` annotation. That is really all you need to do!. The cross-store aspects take care of the rest. This includes marking the field with `@Transient` so it won't be persisted using JPA, keeping track of any changes made to the field value and writing them to the database on successful transaction completion, loading the document from MongoDB the first time the value is used in your application. Here is an example of a simple Entity that has a field annotated with `@RelatedEntity`.

=== Example of Entity with @RelatedDocument

.Example of Entity with @RelatedDocument
====
[source,java]
----
@Entity
Expand All @@ -177,9 +180,10 @@ public class Customer {
// getters and setters omitted
}
----
====

=== Example of domain class to be stored as document

.Example of domain class to be stored as document
====
[source,java]
----
public class SurveyInfo {
Expand Down Expand Up @@ -208,11 +212,12 @@ public class SurveyInfo {
}
}
----
====

Once the SurveyInfo has been set on the Customer object above the MongoTemplate that was configured above is used to save the SurveyInfo along with some metadata about the JPA Entity is stored in a MongoDB collection named after the fully qualified name of the JPA Entity class. The following code:

=== Example of code using the JPA Entity configured for cross-store persistence

.Example of code using the JPA Entity configured for cross-store persistence
====
[source,java]
----
Customer customer = new Customer();
Expand All @@ -225,11 +230,12 @@ SurveyInfo surveyInfo = new SurveyInfo()
customer.setSurveyInfo(surveyInfo);
customerRepository.save(customer);
----
====

Executing the code above results in the following JSON document stored in MongoDB.

=== Example of JSON document stored in MongoDB

.Example of JSON document stored in MongoDB
====
[source,javascript]
----
{ "_id" : ObjectId( "4d9e8b6e3c55287f87d4b79e" ),
Expand All @@ -241,3 +247,4 @@ Executing the code above results in the following JSON document stored in MongoD
"citizenship" : "Norwegian" },
"_entity_field_class" : "org.springframework.data.mongodb.examples.custsvc.domain.SurveyInfo" }
----
====
5 changes: 3 additions & 2 deletions src/main/asciidoc/reference/jmx.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ The JMX support for MongoDB exposes the results of executing the 'serverStatus'

Spring's Mongo namespace enables you to easily enable JMX functionality

=== XML schema to configure MongoDB

.XML schema to configure MongoDB
====
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
Expand Down Expand Up @@ -45,6 +45,7 @@ Spring's Mongo namespace enables you to easily enable JMX functionality

</beans>
----
====

This will expose several MBeans

Expand Down
35 changes: 21 additions & 14 deletions src/main/asciidoc/reference/mapping.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ Unless explicitly configured, an instance of `MongoMappingConverter` is created

You can configure the `MongoMappingConverter` as well as `com.mongodb.Mongo` and MongoTemplate either using Java or XML based metadata. Here is an example using Spring's Java based configuration

=== @Configuration class to configure MongoDB mapping support

.@Configuration class to configure MongoDB mapping support
====
[source,java]
----
@Configuration
Expand Down Expand Up @@ -83,6 +83,7 @@ public class GeoSpatialAppConfig extends AbstractMongoConfiguration {
}
}
----
====

`AbstractMongoConfiguration` requires you to implement methods that define a `com.mongodb.Mongo` as well as provide a database name. `AbstractMongoConfiguration` also has a method you can override named '`getMappingBasePackage`' which tells the converter where to scan for classes annotated with the `@org.springframework.data.mongodb.core.mapping.Document` annotation.

Expand All @@ -94,8 +95,8 @@ You can also override the method `UserCredentials getUserCredentials()` to provi

Spring's MongoDB namespace enables you to easily enable mapping functionality in XML

=== XML schema to configure MongoDB mapping support

.XML schema to configure MongoDB mapping support
====
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
Expand Down Expand Up @@ -134,6 +135,7 @@ Spring's MongoDB namespace enables you to easily enable mapping functionality in

</beans>
----
====

The `base-package` property tells it where to scan for classes annotated with the `@org.springframework.data.mongodb.core.mapping.Document` annotation.

Expand All @@ -142,8 +144,8 @@ The `base-package` property tells it where to scan for classes annotated with th

To take full advantage of the object mapping functionality inside the Spring Data/MongoDB support, you should annotate your mapped objects with the `@org.springframework.data.mongodb.core.mapping.Document` annotation. Although it is not necessary for the mapping framework to have this annotation (your POJOs will be mapped correctly, even without any annotations), it allows the classpath scanner to find and pre-process your domain objects to extract the necessary metadata. If you don't use this annotation, your application will take a slight performance hit the first time you store a domain object because the mapping framework needs to build up its internal metadata model so it knows about the properties of your domain object and how to persist them.

=== Example domain object

.Example domain object
====
[source,java]
----
package com.mycompany.domain;
Expand All @@ -163,17 +165,18 @@ public class Person {
private String lastName;
}
----
====

The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property and the `@Indexed` annotation tells the mapping framework to call `ensureIndex` on that property of your document, making searches faster.
IMPORTANT: The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property and the `@Indexed` annotation tells the mapping framework to call `ensureIndex` on that property of your document, making searches faster.

Automatic index creation is only done for types annotated with `@Document`.
IMPORTANT: Automatic index creation is only done for types annotated with `@Document`.

[[mapping-usage-annotations]]
=== Mapping annotation overview

The MappingMongoConverter can use metadata to drive the mapping of objects to documents. An overview of the annotations is provided below

* `@Id `- applied at the field level to mark the field used for identiy purpose.
* `@Id` - applied at the field level to mark the field used for identiy purpose.
* `@Document` - applied at the class level to indicate this class is a candidate for mapping to the database. You can specify the name of the collection where the database will be stored.
* `@DBRef` - applied at the field to indicate it is to be stored using a com.mongodb.DBRef.
* `@Indexed` - applied at the field level to describe how to index the field.
Expand Down Expand Up @@ -292,8 +295,8 @@ NOTE: Compound indexes are very important to improve the performance of queries

Here's an example that creates a compound index of `lastName` in ascending order and `age` in descending order:

==== Example Compound Index Usage

.Example Compound Index Usage
====
[source,java]
----
package com.mycompany.domain;
Expand All @@ -312,6 +315,7 @@ public class Person {

}
----
====

[[mapping-usage-indexes.text-index]]
=== Text Indexes
Expand All @@ -320,8 +324,8 @@ NOTE: The text index feature is disabled by default for mongodb v.2.4.

Creating a text index allows to accumulate several fields into a searchable full text index. It is only possible to have one text index per collection so all fields marked with `@TextIndexed` are combined into this index. Properties can be weighted to influence document score for ranking results. The default language for the text index is english, to change the default language set `@Document(language="spanish")` to any language you want. Using a property called `language` or `@Language` allows to define a language override on a per document base.

==== Example Text Index Usage

.Example Text Index Usage
====
[source,java]
----
@Document(language = "spanish")
Expand All @@ -340,6 +344,7 @@ class Nested {
String roo;
}
----
====

[[mapping-usage-references]]
=== Using DBRefs
Expand All @@ -348,6 +353,7 @@ The mapping framework doesn't have to store child objects embedded within the do

Here's an example of using a DBRef to refer to a specific document that exists independently of the object in which it is referenced (both classes are shown in-line for brevity's sake):

====
[source,java]
----
@Document
Expand All @@ -369,10 +375,11 @@ public class Person {
private List<Account> accounts;
}
----
====

There's no need to use something like `@OneToMany` because the mapping framework sees that you're wanting a one-to-many relationship because there is a List of objects. When the object is stored in MongoDB, there will be a list of DBRefs rather than the `Account` objects themselves.

The mapping framework does not handle cascading saves. If you change an `Account` object that is referenced by a `Person` object, you must save the Account object separately. Calling `save` on the `Person` object will not automatically save the `Account` objects in the property `accounts`.
IMPORTANT: The mapping framework does not handle cascading saves. If you change an `Account` object that is referenced by a `Person` object, you must save the Account object separately. Calling `save` on the `Person` object will not automatically save the `Account` objects in the property `accounts`.

[[mapping-usage-events]]
=== Mapping Framework Events
Expand Down
Loading