From 7a82915a98cbde10afaaa6de235934cee7fe4b66 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 16 Mar 2016 09:08:42 -0500 Subject: [PATCH] Polish Mongo Documentation * Externalize documentation code for testing * Polish wording * Start each new sentence with new line Issue gh-430 --- docs/build.gradle | 1 + docs/src/docs/asciidoc/index.adoc | 43 ++++++----------- .../MongoJacksonSessionConfiguration.java | 48 +++++++++++++++++++ .../http/MongoJdkSessionConfiguration.java | 40 ++++++++++++++++ .../test/java/docs/http/MyJacksonModule.java | 22 +++++++++ 5 files changed, 126 insertions(+), 28 deletions(-) create mode 100644 docs/src/test/java/docs/http/MongoJacksonSessionConfiguration.java create mode 100644 docs/src/test/java/docs/http/MongoJdkSessionConfiguration.java create mode 100644 docs/src/test/java/docs/http/MyJacksonModule.java diff --git a/docs/build.gradle b/docs/build.gradle index 11ff537..7aea8d2 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -28,6 +28,7 @@ tasks.findByPath("artifactoryPublish")?.enabled = false dependencies { testCompile project(':spring-session'), + project(':spring-session-data-mongo'), "org.springframework.data:spring-data-gemfire:$springDataGemFireVersion", "org.springframework.data:spring-data-redis:$springDataRedisVersion", "org.springframework.data:spring-data-gemfire:$springDataGemFireVersion", diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 62229cb..7943ae9 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -307,53 +307,40 @@ include::guides/mongo.adoc[tags=config,leveloffset=+3] ==== Session serialization mechanisms -To be able to persist session objects in MongoDB we need to provide the serialization/deserialization mechanism. Depending on your classpath Spring Session will choose one of two build-in converters: +To be able to persist session objects in MongoDB we need to provide the serialization/deserialization mechanism. +Depending on your classpath Spring Session will choose one of two build-in converters: * `JacksonMongoSessionConverter` when `ObjectMapper` class is available, or * `JdkMongoSessionConverter` otherwise. ===== JacksonMongoSessionConverter -This mechanism uses Jackson to serialize session objects to/from JSON. Converter is registered automatically by Spring Session always when the `ObjectMapper` class is available (usually provided by the `com.fasterxml.jackson.core:jackson-databind` dependency) and user hasn't registered own converter. +This mechanism uses Jackson to serialize session objects to/from JSON. +`JacksonMongoSessionConverter` will be the default when Jackson is detected on the classpath and the user has not explicitly registered a `AbstractMongoSessionConverter` Bean. -If you have to include custom Jackson's modules you can do it by registering converter by hand: +If you would like to provide custom Jackson modules you can do it by explicitly registering `JacksonMongoSessionConverter`: -[source, java] +[source,java,indent=0] ---- -@Configuration -@EnableMongoHttpSession -public class MySessionConfiguration { - - @Bean - public AbstractMongoSessionConverter mongoSessionConverter() { - return new JacksonMongoSessionConverter(getJacksonModules()); - } - - public Iterable getJacksonModules() { - return Collections.singletonList(new MyJacksonModule()); - } - -} +include::{docs-test-dir}docs/http/MongoJacksonSessionConfiguration.java[tags=config] ---- ==== JdkMongoSessionConverter -This converter uses standard Java serialization to persist session attributes map to MongoDB in a binary form. However standard session elements like id, access time, etc are still written as a plain Mongo objects and can be read and queried without additional effort. -You can enforce use of this converter by registering it manually: +`JdkMongoSessionConverter` uses standard Java serialization to persist session attributes map to MongoDB in a binary form. +However, standard session elements like id, access time, etc are still written as a plain Mongo objects and can be read and queried without additional effort. +`JdkMongoSessionConverter` is used if Jackson is not on the classpath and no explicit `AbstractMongoSessionConverter` Bean has been defined. +You can explicitly register `JdkMongoSessionConverter` by defining it as a Bean. -[source, java] +[source,java,indent=0] ---- -@Bean -public AbstractMongoSessionConverter mongoSessionConverter() { - return new JdkMongoSessionConverter(); -} +include::{docs-test-dir}docs/http/MongoJdkSessionConfiguration.java[tags=config] ---- ==== Using custom converters -You can create your own session converter by extending `AbstractMongoSessionConverter` class. At least you have to implement `getQueryForIndex` and two `convert` methods. -First is used to return query operating on a particular session attribute value, which usually depends on internal session collection schema provided by your mechanism. -Two other methods are used to convert `MongoExpiringSession` from/to Mongo's `DBObject`. +You can create your own session converter by extending `AbstractMongoSessionConverter` class. +The implementation will be used for serializing, deserializing your objects and for providing queries to access the session. [[httpsession-how]] === How HttpSession Integration Works diff --git a/docs/src/test/java/docs/http/MongoJacksonSessionConfiguration.java b/docs/src/test/java/docs/http/MongoJacksonSessionConfiguration.java new file mode 100644 index 0000000..8995af5 --- /dev/null +++ b/docs/src/test/java/docs/http/MongoJacksonSessionConfiguration.java @@ -0,0 +1,48 @@ +/* + * Copyright 2014-2016 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 docs.http; + +import java.util.Collections; + +import com.fasterxml.jackson.databind.Module; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.session.data.mongo.AbstractMongoSessionConverter; +import org.springframework.session.data.mongo.JacksonMongoSessionConverter; +import org.springframework.session.data.mongo.config.annotation.web.http.EnableMongoHttpSession; + +/** + * + * @author Jakub Kubrynski + * @author Rob Winch + */ +// tag::config[] +@Configuration +@EnableMongoHttpSession +public class MongoJacksonSessionConfiguration { + + @Bean + public AbstractMongoSessionConverter mongoSessionConverter() { + return new JacksonMongoSessionConverter(getJacksonModules()); + } + + public Iterable getJacksonModules() { + return Collections.singletonList(new MyJacksonModule()); + } +} +// end::config[] diff --git a/docs/src/test/java/docs/http/MongoJdkSessionConfiguration.java b/docs/src/test/java/docs/http/MongoJdkSessionConfiguration.java new file mode 100644 index 0000000..42a6efd --- /dev/null +++ b/docs/src/test/java/docs/http/MongoJdkSessionConfiguration.java @@ -0,0 +1,40 @@ +/* + * Copyright 2014-2016 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 docs.http; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.session.data.mongo.AbstractMongoSessionConverter; +import org.springframework.session.data.mongo.JdkMongoSessionConverter; +import org.springframework.session.data.mongo.config.annotation.web.http.EnableMongoHttpSession; + +/** + * + * @author Jakub Kubrynski + * @author Rob Winch + */ +// tag::config[] +@Configuration +@EnableMongoHttpSession +public class MongoJdkSessionConfiguration { + + @Bean + public AbstractMongoSessionConverter mongoSessionConverter() { + return new JdkMongoSessionConverter(); + } +} +// end::config[] diff --git a/docs/src/test/java/docs/http/MyJacksonModule.java b/docs/src/test/java/docs/http/MyJacksonModule.java new file mode 100644 index 0000000..bc2ce89 --- /dev/null +++ b/docs/src/test/java/docs/http/MyJacksonModule.java @@ -0,0 +1,22 @@ +/* + * Copyright 2014-2016 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 docs.http; + +import com.fasterxml.jackson.databind.module.SimpleModule; + +class MyJacksonModule extends SimpleModule { +}