From ba773efe255026edd6a1f3daf3c07d259d66be27 Mon Sep 17 00:00:00 2001 From: John Blum Date: Wed, 7 Jun 2017 08:43:01 -0700 Subject: [PATCH] Polish Asciidoc documentation. --- .../docs/asciidoc/guides/boot-gemfire.adoc | 2 +- .../guides/java-gemfire-clientserver.adoc | 2 +- .../asciidoc/guides/java-gemfire-p2p.adoc | 2 +- .../guides/xml-gemfire-clientserver.adoc | 2 +- .../docs/asciidoc/guides/xml-gemfire-p2p.adoc | 4 +- docs/src/docs/asciidoc/index.adoc | 89 ++----------------- ...GemFireCustomIndexingIntegrationTests.java | 0 ...essionGemFireIndexingIntegrationTests.java | 0 .../spring-session-sample-boot-gemfire.gradle | 2 +- 9 files changed, 13 insertions(+), 90 deletions(-) rename docs/src/{test => integration-test}/java/docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java (100%) rename docs/src/{test => integration-test}/java/docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java (100%) diff --git a/docs/src/docs/asciidoc/guides/boot-gemfire.adoc b/docs/src/docs/asciidoc/guides/boot-gemfire.adoc index e3b4e5d..d07442e 100644 --- a/docs/src/docs/asciidoc/guides/boot-gemfire.adoc +++ b/docs/src/docs/asciidoc/guides/boot-gemfire.adoc @@ -72,7 +72,7 @@ If you are using Maven, include the following `repository` declaration in your _ endif::[] // tag::config[] -[[httpsession-spring-java-configuration]] +[[httpsession-spring-java-configuration-gemfire-boot]] == Spring Boot Configuration After adding the required dependencies and repository declarations, we can create our Spring configuration diff --git a/docs/src/docs/asciidoc/guides/java-gemfire-clientserver.adoc b/docs/src/docs/asciidoc/guides/java-gemfire-clientserver.adoc index 7523b47..eec0d3c 100644 --- a/docs/src/docs/asciidoc/guides/java-gemfire-clientserver.adoc +++ b/docs/src/docs/asciidoc/guides/java-gemfire-clientserver.adoc @@ -69,7 +69,7 @@ If you are using Maven, include the following `repository` declaration in your _ endif::[] // tag::config[] -[[httpsession-spring-java-configuration]] +[[httpsession-spring-java-configuration-gemfire-clientserver]] == Spring Java Configuration After adding the required dependencies and repository declarations, we can create our Spring configuration. diff --git a/docs/src/docs/asciidoc/guides/java-gemfire-p2p.adoc b/docs/src/docs/asciidoc/guides/java-gemfire-p2p.adoc index 3ecee9f..27f2612 100644 --- a/docs/src/docs/asciidoc/guides/java-gemfire-p2p.adoc +++ b/docs/src/docs/asciidoc/guides/java-gemfire-p2p.adoc @@ -69,7 +69,7 @@ If you are using Maven, include the following `repository` declaration in your _ endif::[] // tag::config[] -[[httpsession-spring-java-configuration]] +[[httpsession-spring-java-configuration-gemfire-p2p]] == Spring Java Configuration After adding the required dependencies and repository declarations, we can create our Spring configuration. diff --git a/docs/src/docs/asciidoc/guides/xml-gemfire-clientserver.adoc b/docs/src/docs/asciidoc/guides/xml-gemfire-clientserver.adoc index cf0b10c..93a9760 100644 --- a/docs/src/docs/asciidoc/guides/xml-gemfire-clientserver.adoc +++ b/docs/src/docs/asciidoc/guides/xml-gemfire-clientserver.adoc @@ -69,7 +69,7 @@ If you are using Maven, include the following `repository` declaration in your _ endif::[] // tag::config[] -[[httpsession-spring-xml-configuration]] +[[httpsession-spring-xml-configuration-gemfire-clientserver]] == Spring XML Configuration After adding the required dependencies and repository declarations, we can create our Spring configuration. diff --git a/docs/src/docs/asciidoc/guides/xml-gemfire-p2p.adoc b/docs/src/docs/asciidoc/guides/xml-gemfire-p2p.adoc index e4b0959..6ebb417 100644 --- a/docs/src/docs/asciidoc/guides/xml-gemfire-p2p.adoc +++ b/docs/src/docs/asciidoc/guides/xml-gemfire-p2p.adoc @@ -1,5 +1,5 @@ = Spring Session - HttpSession with GemFire P2P using XML (Quick Start) -John Blum, Rob Winch +John Blum :toc: This guide describes how to configure Pivotal GemFire as a provider in Spring Session to transparently back @@ -69,7 +69,7 @@ If you are using Maven, include the following `repository` declaration in your _ endif::[] // tag::config[] -[[httpsession-spring-xml-configuration]] +[[httpsession-spring-xml-configuration-gemfire-p2p]] == Spring XML Configuration After adding the required dependencies and repository declarations, we can create our Spring configuration. diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 053dc89..ac5af5a 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -1,8 +1,6 @@ = Spring Session John Blum :doctype: book -:indexdoc-tests: {docs-test-dir}docs/IndexDocTests.java -:websocketdoc-test-dir: {docs-test-dir}docs/websocket/ :toc: left [[abstract]] @@ -278,32 +276,12 @@ To use this support, you need to: If you are using the configuration support documented in <>, then all you need to do is register every `HttpSessionListener` as a bean. For example, assume you want to support Spring Security's concurrency control and need to use `HttpSessionEventPublisher` you can simply add `HttpSessionEventPublisher` as a bean. -In Java configuration, this might look like: - -[source,java,indent=0] ----- -include::{docs-test-dir}docs/http/RedisHttpSessionConfig.java[tags=config] ----- - -In XML configuration, this might look like: - -[source,xml,indent=0] ----- -include::{docs-test-resources-dir}docs/http/HttpSessionListenerXmlTests-context.xml[tags=config] ----- [[api-session]] === Session A `Session` is a simplified `Map` of key value pairs. -Typical usage might look like the following: - -[source,java,indent=0] ----- -include::{indexdoc-tests}[tags=repository-demo] ----- - <1> We create a `SessionRepository` instance with a generic type, `S`, that extends `Session`. The generic type is defined in our class. <2> We create a new `Session` using our `SessionRepository` and assign it to a variable of type `S`. <3> We interact with the `Session`. In our example, we demonstrate saving a `User` to the `Session`. @@ -317,13 +295,6 @@ include::{indexdoc-tests}[tags=repository-demo] An `ExpiringSession` extends a `Session` by providing attributes related to the `Session` instance's expiration. If there is no need to interact with the expiration information, prefer using the more simple `Session` API. -Typical usage might look like the following: - -[source,java,indent=0] ----- -include::{indexdoc-tests}[tags=expire-repository-demo] ----- - <1> We create a `SessionRepository` instance with a generic type, `S`, that extends `ExpiringSession`. The generic type is defined in our class. <2> We create a new `ExpiringSession` using our `SessionRepository` and assign it to a variable of type `S`. <3> We interact with the `ExpiringSession`. @@ -356,12 +327,6 @@ For example, Spring's Redis support implements `FindByIndexNameSessionRepository The `FindByIndexNameSessionRepository` adds a single method to look up all the sessions for a particular user. This is done by ensuring that the session attribute with the name `FindByIndexNameSessionRepository.PRINCIPAL_NAME_INDEX_NAME` is populated with the username. It is the responsibility of the developer to ensure the attribute is populated since Spring Session is not aware of the authentication mechanism being used. -An example of how this might be used can be seen below: - -[source,java,indent=0] ----- -include::{docs-test-dir}docs/FindByIndexNameSessionRepositoryTests.java[tags=set-username] ----- [NOTE] ==== @@ -369,24 +334,11 @@ Some implementations of `FindByIndexNameSessionRepository` will provide hooks to For example, many implementations will automatically ensure the current Spring Security user name is indexed with the index name `FindByIndexNameSessionRepository.PRINCIPAL_NAME_INDEX_NAME`. ==== -Once the session is indexed, it can be found using the following: - -[source,java,indent=0] ----- -include::{docs-test-dir}docs/FindByIndexNameSessionRepositoryTests.java[tags=findby-username] ----- - [[api-enablespringhttpsession]] === EnableSpringHttpSession The `@EnableSpringHttpSession` annotation can be added to an `@Configuration` class to expose the `SessionRepositoryFilter` as a bean named "springSessionRepositoryFilter". In order to leverage the annotation, a single `SessionRepository` bean must be provided. -For example: - -[source,java,indent=0] ----- -include::{docs-test-dir}docs/SpringHttpSessionConfig.java[tags=class] ----- It is important to note that no infrastructure for session expirations is configured for you out of the box. This is because things like session expiration are highly implementation dependent. @@ -412,8 +364,8 @@ strategies for finding the principal name. The first strategy is that the value [source,java,indent=0] ---- -include::{docs-itest-dir}docs/http/HttpSessionGemFireIndexingITests.java[tags=findbyindexname-set] -include::{docs-itest-dir}docs/http/HttpSessionGemFireIndexingITests.java[tags=findbyindexname-get] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java[tags=findbyindexname-set] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java[tags=findbyindexname-get] ---- [[api-gemfireoperationssessionrepository-indexing-security]] @@ -425,8 +377,8 @@ find the current user's sessions using: [source,java,indent=0] ---- -include::{docs-itest-dir}docs/http/HttpSessionGemFireIndexingITests.java[tags=findbyspringsecurityindexname-context] -include::{docs-itest-dir}docs/http/HttpSessionGemFireIndexingITests.java[tags=findbyspringsecurityindexname-get] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java[tags=findbyspringsecurityindexname-context] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java[tags=findbyspringsecurityindexname-get] ---- [[api-gemfireoperationssessionrepository-indexing-custom]] @@ -443,21 +395,10 @@ Sessions attributes to index can be specified with the `indexableSessionAttribut annotation. A developer adds this annotation to their Spring application `@Configuration` class when s/he wishes to enable Spring Session support for HttpSession backed by GemFire. -For example, the following configuration: - [source,java,indent=0] ---- -include::{docs-itest-dir}docs/http/gemfire/indexablesessionattributes/GemFireHttpSessionConfig.java[tags=class-start] - // ... -} ----- - -will allow searching for sessions using the following: - -[source,java,indent=0] ----- -include::{docs-itest-dir}docs/http/gemfire/indexablesessionattributes/HttpSessionGemFireIndexingCustomITests.java[tags=findbyindexname-set] -include::{docs-itest-dir}docs/http/gemfire/indexablesessionattributes/HttpSessionGemFireIndexingCustomITests.java[tags=findbyindexname-get] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java[tags=findbyindexname-set] +include::{docs-itest-dir}docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java[tags=findbyindexname-get] ---- NOTE: Only Session attribute names identified in the `@EnableGemFireHttpSession` annotation's `indexableSessionAttributes` @@ -474,24 +415,6 @@ To learn more about GemFire's Range-based Indexes, see http://gemfire.docs.pivot To learn more about GemFire Indexing in general, see http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_index/query_index.html[Working with Indexes]. - -[[api-mapsessionrepository]] -=== MapSessionRepository - -The `MapSessionRepository` allows for persisting `ExpiringSession` in a `Map` with the key being the `ExpiringSession` id and the value being the `ExpiringSession`. -The implementation can be used with a `ConcurrentHashMap` as a testing or convenience mechanism. -Alternatively, it can be used with distributed `Map` implementations. For example, it can be used with Hazelcast. - -[[api-mapsessionrepository-new]] -==== Instantiating MapSessionRepository - -Creating a new instance is as simple as: - -[source,java,indent=0] ----- -include::{indexdoc-tests}[tags=new-mapsessionrepository] ----- - [[community]] == Spring Session Community diff --git a/docs/src/test/java/docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java b/docs/src/integration-test/java/docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java similarity index 100% rename from docs/src/test/java/docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java rename to docs/src/integration-test/java/docs/gemfire/indexing/HttpSessionGemFireCustomIndexingIntegrationTests.java diff --git a/docs/src/test/java/docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java b/docs/src/integration-test/java/docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java similarity index 100% rename from docs/src/test/java/docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java rename to docs/src/integration-test/java/docs/gemfire/indexing/HttpSessionGemFireIndexingIntegrationTests.java diff --git a/samples/boot/gemfire/spring-session-sample-boot-gemfire.gradle b/samples/boot/gemfire/spring-session-sample-boot-gemfire.gradle index f89e37e..abc7185 100644 --- a/samples/boot/gemfire/spring-session-sample-boot-gemfire.gradle +++ b/samples/boot/gemfire/spring-session-sample-boot-gemfire.gradle @@ -38,7 +38,7 @@ run { } bootJar { - mainClass = 'sample.client.Application' + mainClassName = 'sample.client.Application' } task runGemFireServer() {