Merge branch 'master' of https://github.com/spring-projects/spring-se…

…ssion

docs/build.gradle

@@ -32,6 +32,7 @@ dependencies {
 				'org.mockito:mockito-core:1.9.5',
 				"org.springframework:spring-test:$springVersion",
 				'org.easytesting:fest-assert:1.4',
+				"com.hazelcast:hazelcast:$hazelcastVersion",
 				"redis.clients:jedis:2.4.1",
 				"javax.servlet:javax.servlet-api:$servletApiVersion"
 }
@@ -47,6 +48,7 @@ asciidoctor {
 			'download-url' : "https://github.com/spring-projects/spring-session/archive/${ghTag}.zip",
 			'spring-session-version' : version,
 			'spring-version' : springVersion,
+			'hazelcast-version' : hazelcastVersion,
 			'docs-test-dir' : rootProject.projectDir.path + '/docs/src/test/java/',
 			'docs-test-resources-dir' : rootProject.projectDir.path + '/docs/src/test/resources/',
 			'samples-dir' : rootProject.projectDir.path + '/samples/',

docs/src/docs/asciidoc/guides/hazelcast-spring.adoc

@@ -0,0 +1,191 @@
+= Spring Session and Spring Security with Hazelcast
+Tommy Ludwig; Rob Winch
+:toc:
+
+This guide describes how to use Spring Session along with Spring Security using Hazelcast as your data store.
+It assumes you have already applied Spring Security to your application.
+
+NOTE: The completed guide can be found in the <<hazelcast-spring-security-sample, Hazelcast Spring Security sample application>>.
+
+== Updating Dependencies
+Before you use Spring Session, you must ensure to update your dependencies.
+If you are using Maven, ensure to add the following dependencies:
+
+.pom.xml
+[source,xml]
+[subs="verbatim,attributes"]
+----
+<dependencies>
+	<!-- ... -->
+
+	<dependency>
+		<groupId>com.hazelcast</groupId>
+		<artifactId>hazelcast</artifactId>
+		<version>{hazelcast-version}</version>
+	</dependency>
+	<dependency>
+		<groupId>org.springframework</groupId>
+		<artifactId>spring-web</artifactId>
+		<version>{spring-version}</version>
+	</dependency>
+</dependencies>
+----
+
+ifeval::["{version-snapshot}" == "true"]
+Since We are using a SNAPSHOT version, we need to ensure to add the Spring Snapshot Maven Repository.
+Ensure you have the following in your pom.xml:
+
+.pom.xml
+[source,xml]
+----
+<repositories>
+
+	<!-- ... -->
+
+	<repository>
+	<id>spring-snapshot</id>
+	<url>https://repo.spring.io/libs-snapshot</url>
+	</repository>
+</repositories>
+----
+endif::[]
+
+ifeval::["{version-milestone}" == "true"]
+Since We are using a Milestone version, we need to ensure to add the Spring Milestone Maven Repository.
+Ensure you have the following in your pom.xml:
+
+.pom.xml
+[source,xml]
+----
+<repository>
+<id>spring-milestone</id>
+<url>https://repo.spring.io/libs-milestone</url>
+</repository>
+----
+endif::[]
+
+[[security-spring-configuration]]
+== Spring Configuration
+
+After adding the required dependencies, we can create our Spring configuration.
+The Spring configuration is responsible for creating a Servlet Filter that replaces the `HttpSession` implementation with an implementation backed by Spring Session.
+Add the following Spring Configuration:
+
+[source,java]
+----
+include::{docs-test-dir}docs/http/HazelcastHttpSessionConfig.java[tags=config]
+----
+
+<1> The `@EnableHazelcastHttpSession` annotation creates a Spring Bean with the name of `springSessionRepositoryFilter` that implements Filter.
+The filter is what is in charge of replacing the `HttpSession` implementation to be backed by Spring Session.
+In this instance Spring Session is backed by Hazelcast.
+<2> We create a `HazelcastInstance` that connects Spring Session to Hazelcast.
+By default, an embedded instance of Hazelcast is started and connected to by the application.
+For more information on configuring Hazelcast, refer to the http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#hazelcast-configuration[reference documentation].
+
+== Servlet Container Initialization
+
+Our <<security-spring-configuration,Spring Configuration>> created a Spring Bean named `springSessionRepositoryFilter` that implements `Filter`.
+The `springSessionRepositoryFilter` bean is responsible for replacing the `HttpSession` with a custom implementation that is backed by Spring Session.
+
+In order for our `Filter` to do its magic, Spring needs to load our `Config` class.
+Since our application is already loading Spring configuration using our `SecurityInitializer` class, we can simply add our Config class to it.
+
+.src/main/java/sample/SecurityInitializer.java
+[source,java]
+----
+include::{samples-dir}hazelcast-spring/src/main/java/sample/SecurityInitializer.java[tags=class]
+----
+
+Last we need to ensure that our Servlet Container (i.e. Tomcat) uses our `springSessionRepositoryFilter` for every request.
+It is extremely important that Spring Session's `springSessionRepositoryFilter` is invoked before Spring Security's `springSecurityFilterChain`.
+This ensures that the `HttpSession` that Spring Security uses is backed by Spring Session.
+Fortunately, Spring Session provides a utility class named `AbstractHttpSessionApplicationInitializer` that makes this extremely easy.
+You can find an example below:
+
+.src/main/java/sample/Initializer.java
+[source,java]
+----
+include::{samples-dir}hazelcast-spring/src/main/java/sample/Initializer.java[tags=class]
+----
+
+NOTE: The name of our class (Initializer) does not matter. What is important is that we extend `AbstractHttpSessionApplicationInitializer`.
+
+By extending `AbstractHttpSessionApplicationInitializer` we ensure that the Spring Bean by the name `springSessionRepositoryFilter` is registered with our Servlet Container for every request before Spring Security's `springSecurityFilterChain`.
+
+
+
+[[hazelcast-spring-security-sample]]
+== Hazelcast Spring Security Sample Application
+
+=== Running the Sample Application
+
+You can run the sample by obtaining the {download-url}[source code] and invoking the following command:
+
+[NOTE]
+====
+Hazelcast will run in embedded mode with your application by default, but if you want to connect
+to a stand alone instance instead, you can configure it by following the instructions in the
+http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#hazelcast-configuration[reference documentation].
+====
+
+----
+$ ./gradlew :samples:hazelcast-spring:tomcatRun
+----
+
+You should now be able to access the application at http://localhost:8080/
+
+=== Exploring the security Sample Application
+
+Try using the application. Enter the following to log in:
+
+* **Username** _user_
+* **Password** _password_
+
+Now click the **Login** button.
+You should now see a message indicating your are logged in with the user entered previously.
+The user's information is stored in Hazelcast rather than Tomcat's `HttpSession` implementation.
+
+=== How does it work?
+
+Instead of using Tomcat's `HttpSession`, we are actually persisting the values in Hazelcast.
+Spring Session replaces the `HttpSession` with an implementation that is backed by a `Map` in Hazelcast.
+When Spring Security's `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession` it is then persisted into Hazelcast.
+
+When a new `HttpSession` is created, Spring Session creates a cookie named SESSION in your browser that contains the id of your session.
+Go ahead and view the cookies (click for help with https://developer.chrome.com/devtools/docs/resources#cookies[Chrome] or https://getfirebug.com/wiki/index.php/Cookies_Panel#Cookies_List[Firefox]).
+
+=== Interact with the data store
+
+If you like, you can remove the session using http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#hazelcast-java-client[a Java client],
+http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#other-client-implementations[one of the other clients], or the
+http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#management-center[management center].
+
+==== Using the console
+
+For example, using the management center console after connecting to your Hazelcast node:
+
+	default> ns spring:session:sessions
+	spring:session:sessions> m.clear
+
+TIP: The Hazelcast documentation has instructions for http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#console[the console].
+
+Alternatively, you can also delete the explicit key. Enter the following into the console ensuring to replace `7e8383a4-082c-4ffe-a4bc-c40fd3363c5e` with the value of your SESSION cookie:
+
+	spring:session:sessions> m.remove 7e8383a4-082c-4ffe-a4bc-c40fd3363c5e
+
+Now visit the application at http://localhost:8080/ and observe that we are no longer authenticated.
+
+==== Using the REST API
+
+As described in the other clients section of the documentation, there is a 
+http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#rest-client[REST API]
+provided by the Hazelcast node(s).
+
+For example, you could delete an individual key as follows (replacing `7e8383a4-082c-4ffe-a4bc-c40fd3363c5e` with the value of your SESSION cookie):
+
+	$ curl -v -X DELETE http://localhost:xxxxx/hazelcast/rest/maps/spring:session:sessions/7e8383a4-082c-4ffe-a4bc-c40fd3363c5e
+
+TIP: The port number of the Hazelcast node will be printed to the console on startup. Replace `xxxxx` above with the port number.
+
+Now observe that you are no longer authenticated with this session.

docs/src/docs/asciidoc/index.adoc

@@ -71,7 +71,7 @@ If you are looking to get started with Spring Session, the best place to start i
 [[samples-hazelcast-spring]]
 | {gh-samples-url}hazelcast-spring[Hazelcast Spring]
 | Demonstrates how to use Spring Session and Hazelcast with an existing Spring Security application.
-| TBD
+| link:guides/hazelcast-spring.html[Hazelcast Spring Guide]
 
 |===
 
@@ -342,6 +342,43 @@ It is important to note that no infrastructure for session expirations is config
 This is because things like session expiration are highly implementation dependent.
 This means if you require cleaning up expired sessions, you are responsible for cleaning up the expired sessions.
 
+[[api-enablehazelcasthttpsession]]
+=== EnableHazelcastHttpSession
+
+If you wish to use http://hazelcast.org/[Hazelcast] as your backing source for the `SessionRepository`, then the `@EnableHazelcastHttpSession` annotation 
+can be added to an `@Configuration` class. This extends the functionality provided by the `@EnableSpringHttpSession` annotation but makes the `SessionRepository` for you in Hazelcast.
+You must provide a single `HazelcastInstance` bean for the configuration to work.
+For example:
+
+[source,java,indent=0]
+----
+include::{docs-test-dir}docs/http/HazelcastHttpSessionConfig.java[tags=config]
+----
+
+This will configure Hazelcast in embedded mode with default configuration.
+See the http://docs.hazelcast.org/docs/latest/manual/html-single/hazelcast-documentation.html#hazelcast-configuration[Hazelcast documentation] for 
+detailed information on configuration options for Hazelcast.
+
+[[api-enablehazelcasthttpsession-storage]]
+==== Storage Details
+
+Sessions will be stored in a distributed `Map` in Hazelcast using a <<api-mapsessionrepository,MapSessionRepository>>.
+The `Map` interface methods will be used to `get()` and `put()` Sessions.
+The expiration of a session in the `Map` is handled by Hazelcast's native support for configuring a map's `max-idle-seconds` setting.
+Entries (sessions) that have been idle longer than the max idle setting will be automatically removed from the `Map`.
+
+[[api-enablehazelcasthttpsession-customize]]
+==== Basic Customization
+You can use the following attributes on `@EnableHazelcastHttpSession` to customize the configuration:
+
+* **maxInactiveIntervalInSeconds** - the amount of time before the session will expire in seconds. Default is 1800 seconds (30 minutes)
+* **sessionMapName** - the name of the distributed `Map` that will be used in Hazelcast to store the session data.
+
+[[api-enablehazelcasthttpsession-events]]
+==== Session Events
+Using a `MapListener` to respond to entries being added, evicted, and removed from the distributed `Map`, these events will trigger 
+publishing SessionCreatedEvent, SessionExpiredEvent, and SessionDeletedEvent events respectively using the `ApplicationEventPublisher`.
+
 [[api-redisoperationssessionrepository]]
 === RedisOperationsSessionRepository
 

docs/src/test/java/docs/http/HazelcastHttpSessionConfig.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2002-2015 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.hazelcast.config.annotation.web.http.EnableHazelcastHttpSession;
+
+import com.hazelcast.config.Config;
+import com.hazelcast.core.Hazelcast;
+import com.hazelcast.core.HazelcastInstance;
+
+//tag::config[]
+@EnableHazelcastHttpSession // <1>
+@Configuration
+public class HazelcastHttpSessionConfig {
+	@Bean
+	public HazelcastInstance embeddedHazelcast() {
+		Config hazelcastConfig = new Config();
+		return Hazelcast.newHazelcastInstance(hazelcastConfig); // <2>
+	}
+}
+// end::config[]

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-2.2.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.9-rc-1-bin.zip

samples/hazelcast-spring/src/main/java/sample/Config.java

@@ -15,74 +15,34 @@
  */
 package sample;
 
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import org.springframework.session.MapSessionRepository;
-import org.springframework.session.config.annotation.web.http.EnableSpringHttpSession;
-import org.springframework.session.ExpiringSession;
+import org.springframework.session.hazelcast.config.annotation.web.http.EnableHazelcastHttpSession;
 import org.springframework.util.SocketUtils;
 
-import com.hazelcast.config.MapConfig;
 import com.hazelcast.config.NetworkConfig;
 import com.hazelcast.config.SerializerConfig;
 import com.hazelcast.core.Hazelcast;
 import com.hazelcast.core.HazelcastInstance;
-import com.hazelcast.core.IMap;
 
 // tag::class[]
-@EnableSpringHttpSession
+@EnableHazelcastHttpSession(maxInactiveIntervalInSeconds = "300")
 @Configuration
 public class Config {
 
-	private String sessionMapName = "spring:session:sessions";
-
-	@Autowired
-	private ApplicationEventPublisher eventPublisher;
-
 	@Bean(destroyMethod = "shutdown")
 	public HazelcastInstance hazelcastInstance() {
 		com.hazelcast.config.Config cfg = new com.hazelcast.config.Config();
 		NetworkConfig netConfig = new NetworkConfig();
 		netConfig.setPort(SocketUtils.findAvailableTcpPort());
+		System.out.println("Hazelcast port #: " + netConfig.getPort());
 		cfg.setNetworkConfig(netConfig);
 		SerializerConfig serializer = new SerializerConfig().setTypeClass(
 				Object.class).setImplementation(new ObjectStreamSerializer());
 		cfg.getSerializationConfig().addSerializerConfig(serializer);
-		MapConfig mc = new MapConfig();
-		mc.setName(sessionMapName);
-
-		mc.setMaxIdleSeconds(60);
-		cfg.addMapConfig(mc);
 
 		return Hazelcast.newHazelcastInstance(cfg);
 	}
 
-	@Bean
-	public SessionRemovedListener removeListener() {
-		return new SessionRemovedListener(eventPublisher);
-	}
-
-	@Bean
-	public SessionEvictedListener evictListener() {
-		return new SessionEvictedListener(eventPublisher);
-	}
-
-	@Bean
-	public SessionCreatedListener addListener() {
-		return new SessionCreatedListener(eventPublisher);
-	}
-
-	@Bean
-	public MapSessionRepository sessionRepository(HazelcastInstance instance,
-			SessionRemovedListener removeListener, SessionEvictedListener evictListener,
-			SessionCreatedListener addListener) {
-		IMap<String, ExpiringSession> sessions = instance.getMap(sessionMapName);
-		sessions.addEntryListener(removeListener, true);
-		sessions.addEntryListener(evictListener, true);
-		sessions.addEntryListener(addListener, true);
-		return new MapSessionRepository(sessions);
-	}
 }
 // end::class[]