Configuration & Deployment
The Web Application Configuration
The web application requires a couple of configuration changes to the web.xml
file in order to enabled XAP Session sharing:
<web-app>
....
<listener>
<listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
</listener>
<listener>
<listener-class>com.gigaspaces.httpsession.sessions.GigaSpacesCacheManager</listener-class>
</listener>
<filter>
<filter-name>GigaSpacesHttpSessionFilter</filter-name>
<filter-class>com.gigaspaces.httpsession.web.GigaSpacesHttpSessionFilter</filter-class>
<web:init-param>
<web:param-name>rewriteUrl</web:param-name>
<web:param-value>false</web:param-value> <!-- default true -->
</web:init-param>
</filter>
<filter-mapping>
<filter-name>GigaSpacesHttpSessionFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
The GigaSpacesHttpSessionFilter must be the first filter defined.
Shiro configuration
shiro.ini settings
Section | Property | Description | Required | Optional Values | Default Values |
---|---|---|---|---|---|
main | connector | wrap SpaceProxy and perform operation aginst space | Yes | com.gigaspaces.httpsession.SpaceConnector |
|
main | connector.url | Space url | Yes | jini://*/*/<space_name> |
|
main | connector.username | Space username | No | <space username> |
|
main | connector.password | Space password | No | <space password> |
|
main | connector.sessionLease | Lease timeout in milliseconds | No | Any positive integer. Millisecond time unit | 1800000 |
main | connector.readTimeout | Read timeout in milliseconds | No | Any positive interger. Millisecond time unit | 300000 |
main | sessionManager | XAP Session Manager Implementation | Yes | com.gigaspaces.httpsession.GigaSpacesWebSessionManager | |
main | sessionManager.sessionDAO | Yes | $sessionDAO | ||
main | sessionDAO | Provides a transparent caching layer between the components that use it and the underlying EIS (Enterprise Information System) session backing store | Yes | org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO | |
main | cacheManager | XAP extension of org.apache.shiro.cache.CacheManager Provides and maintains the lifecycles of com.gigaspaces.httpsession.sessions.GigaSpacesCache instances |
Yes | com.gigaspaces.httpsession.sessions.GigaSpacesCacheManager | |
main | cacheManager.compressor | Set the compressor instance to be used | No | $compressor | com.gigaspaces.httpsession.serialize.NonCompressCompressor |
main | cacheManager.serializer | instance of the serializer implementation | Yes | $serializer | |
main | cacheManager.policy | instance of session policy implementation | Yes | $policy | |
main | cacheManager.connector | instance of space connector implementation | Yes | $connector | |
main | compressor | Provides compress functionality | No | Provides your own com.gigaspaces.httpsession.serialize.Compressor implementation or use one of the out of the box option:1. com.gigaspaces.httpsession.serialize.CompressorImpl 2. com.gigaspaces.httpsession.serialize.NonCompressCompressor |
|
main | storeMode | Provide functionality of how to save changes to the space. there is tow sessions store mode full and delta. | Yes | use on of two options: 1. com.gigaspaces.httpsession.sessions.FullStoreMode 2.com.gigaspaces.httpsession.sessions.DeltaStoreMode |
|
main | storeMode.connector | Space connector to be used | Yes | $connector | |
main | storeMode.listener | Provides changes notification functionality. it must extends com.gigaspaces.httpsession.policies.GigaspacesNotifyListener |
No | listener |
|
main | storeMode.changeStrategy | define strategy of comparison and conflict detection response. | Yes | DeltaStoreMode: 1.com.gigaspaces.httpsession.policies.LWWChangeStrategy 2.com.gigaspaces.httpsession.policies.FailFastChangeStrategy 3.com.gigaspaces.httpsession.policies.PartialChangeStrategy |
FullStoreMode: com.gigaspaces.httpsession.policies.FullModeStrategy DeltaStoreMode: com.gigaspaces.httpsession.policies.LWWChangeStrategy |
main | listener | Fully qualified class name implementing com.gigaspaces.httpsession.policies.GigaspacesNotifyListener |
No | com.gigaspaces.httpsession.policies.TraceListener |
|
main | serializer | Provides serialization functionality | Yes | use one of the following options: 1.com.gigaspaces.httpsession.serialize.KryoSerializerImpl (recomended) 2.com.gigaspaces.httpsession.serialize.XStreamSerializerImpl 3. Custom - an implementation of the com.gigaspaces.httpsession.serialize.Serializer interface |
|
main | serializer.logLevel | internal kryo logging level | No | 1. NONE = 6 disables all logging.2. ERROR = 5 is for critical errors. The application may no longer work correctly.3. WARN = 4 is for important warnings. The application will continue to work correctly.4. INFO = 3 is for informative messages. Typically used for deployment.5. DEBUG = 2 is for debug messages. This level is useful during development.6. TRACE = 1 is for trace messages. A lot of information is logged, so this level is usually only needed when debugging a problem. |
LEVEL_INFO = 3 |
main | serializer.classes | comma separate list full qualified class names to be loaded at the initialization of the Kryo Serializer | No | ||
main | policy | Provides functionality of session policy to apply e.g. with and without authentication | Yes | Options: 1. com.gigaspaces.httpsession.policies.SessionPolicyWithLogin for sharing session cross multiple aplplications2. com.gigaspaces.httpsession.policies.SessionPolicyWithoutLogin for single application session store |
|
main | policy.connector = $connector | instance of space connector implementation | Yes | ||
main | policy.storeMode = $storeMode | instance of space storeMode implementation | Yes |
The shiro.ini
file should to be placed within the WEB-INF
folder. See below examples for the shiro.ini
file:
[main]
# space proxy wraper
connector = com.gigaspaces.httpsession.SpaceConnector
connector.url = jini://*/*/sessionSpace
# When using secured GigaSpace cluster, pass the credentials here
# connector.username = <username>
# connector.password = <password>
# Default lease is 30 minutes - 30 * 60 * 1000 = 1800000
connector.sessionLease = 1800000
# Default read timeout is 5 minutes = 5 * 60 * 1000 = 300000
connector.readTimeout = 300000
sessionManager = com.gigaspaces.httpsession.GigaSpacesWebSessionManager
#set the sessionManager to use an enterprise cache for backing storage:
sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
sessionManager.sessionDAO = $sessionDAO
# ensure the securityManager uses our native SessionManager:
securityManager.sessionManager = $sessionManager
# whatever your CacheManager implementation is, for example:
cacheManager = com.gigaspaces.httpsession.sessions.GigaSpacesCacheManager
# Model Manager service
storeMode = com.gigaspaces.httpsession.sessions.DeltaStoreMode
storeMode.connector = $connector
#storeMode.changeStrategy = com.gigaspaces.httpsession.policies.FailFastChangeStrategy
listener1 = com.gigaspaces.httpsession.policies.TraceListener
storeMode.listener = $listener1
cacheManager.storeMode = $storeMode
# Serialization Service
serializer = com.gigaspaces.httpsession.serialize.KryoSerializerImpl
serializer.logLevel = 1
#### classes registation: class1, class2, ...,classN
#serializer.classes = com.pak1.myClass1 , com.pak2.myClass2
cacheManager.serializer = $serializer
# Session Policy Service
policy = com.gigaspaces.httpsession.policies.SessionPolicyWithoutLogin
policy.connector = $connector
policy.storeMode = $storeMode
cacheManager.policy = $policy
# space proxy setter
cacheManager.connector= $connector
# This will use GigaSpaces for _all_ of Shiro's caching needs (realms, etc), not just for Session storage.
securityManager.cacheManager = $cacheManager
Note that this example uses the basic authentication configuration but, Shiro has various authenticator types see realm modules
[main]
authc.loginUrl = /login.jsp
# space proxy wraper
connector = com.gigaspaces.httpsession.SpaceConnector
connector.url = jini://*/*/sessionSpace
# When using secured GigaSpace cluster, pass the credentials here
# connector.username = <username>
# connector.password = <password>
# Default lease is 30 minutes - 30 * 60 * 1000 = 1800000
connector.sessionLease = 1800000
#sessionManager = org.apache.shiro.web.session.mgt.StandardWebSessionManager
#sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
sessionManager = com.gigaspaces.httpsession.GigaSpacesWebSessionManager
#set the sessionManager to use an enterprise cache for backing storage:
sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
sessionManager.sessionDAO = $sessionDAO
# ensure the securityManager uses our native SessionManager:
securityManager.sessionManager = $sessionManager
# whatever your CacheManager implementation is, for example:
cacheManager = com.gigaspaces.httpsession.sessions.GigaSpacesCacheManager
# Compression service
#compressor = com.gigaspaces.httpsession.serialize.CompressorImpl
#cacheManager.compressor = $compressor
# Model Manager service
#changeStrategy = com.gigaspaces.httpsession.policies.LastWriteWinsPolicy
storeMode = com.gigaspaces.httpsession.models.DeltaStoreMode
storeMode.connector = $connector
#storeMode.changeStrategy = $changeStrategy
cacheManager.storeMode = $storeMode
# Serialization Service
serializer = com.gigaspaces.httpsession.serialize.KryoSerializerImpl
#serializer.classes = com.gigaspaces.httpsession.sessions.NestSerial , com.gigaspaces.httpsession.sessions.NestNonSerial
cacheManager.serializer = $serializer
# Session Policy Service
policy = com.gigaspaces.httpsession.policies.SessionPolicyWithLogin
policy.connector = $connector
policy.storeMode = $storeMode
cacheManager.policy = $policy
# space proxy setter
cacheManager.connector= $connector
# This will use GigaSpaces for _all_ of Shiro's caching needs (realms, etc), not just for Session storage.
securityManager.cacheManager = $cacheManager
[users]
## format: username = password, role1, role2, ..., roleN
root = secret,admin
guest = guest,guest
presidentskroob = 12345,president
darkhelmet = ludicrousspeed,darklord,schwartz
lonestarr = vespa,goodguy,schwartz
[roles]
## format: roleName = permission1, permission2, ..., permissionN
admin = *
schwartz = lightsaber:*
goodguy = winnebago:drive:eagle5
[urls]
## The /login.jsp is not restricted to authenticated users (otherwise no one could log in!), but
## the 'authc' filter must still be specified for it so it can process that url's
## login submissions. It is 'smart' enough to allow those requests through as specified by the
## shiro.loginUrl above.
/login.jsp = authc
/** = authc
##/logout = logout
##/account/** = authc
/remoting/** = authc, roles[b2bClient], perms["remote:invoke:lan,wan"
Web Application Libraries
The web application should include the following libraries within its \WEB-INF\lib
folder:
- gs-session-manager-xxx.jar - located within the
XAP ROOT\lib\optional\httpsession
folder. - gs-runtime.jar - located within the
XAP ROOT\lib\required
folder.
The gs-runtime.jar
should be replaced with the relevant XAP gs-runtime.jar
matching your XAP data grid release.
Deployment
The XAP IMDG should be deployed using one of the topologies. You may also use the WAN Gateway with multi data grid deployment.
# To deploy the IMDG called `sessionSpace` start the XAP agent using:
<XAP-HOME>/bin/gs-agent
# and run the following command to deploy the session Space:
<XAP-HOME>/bin/gs deploy-space sessionSpace
See the deploy-space command for details.
Classpath
The gs-session-manager-xxx.jar
located within the \gigaspaces-xap-root\lib\optional\httpsession
folder should be copied into the \gigaspaces-xap-root\lib\platform\ext
folder.
Deploying the WAN Gateway
The WAN Gateway should be deployed using your preferred replication topography, such as multi-master or master-slave. See the WAN Replication Gateway best practice for an example of how a multi-master Gateway architecture can be deployed.
Securing the XAP IMDG
When using a Secure XAP cluster you can pass security credentials using following parameters in the shiro.ini
file:
connector.username = user
connector.password = pass
Example
The example can be deployed into any web server (Tomcat, JBoss, Websphere, Weblogic, Jetty, GlassFish). It demostrates Single Application Session Sharing configuration.
- Download the demo web application .
- Deploy a space named sessionSpace. You may have a single instance Space or deploy a clustered Space using the command line , GS-UI or the Web-UI.
- Deploy the
demo-app.war
into Tomcat (or any other app server). - Start your browser and access the web application via the following URL:
http://localhost:8080/demo-app
The URL above assumes the Web Server is configured to use port 8080.
Restart your web application and refresh the page. The session will be reloaded from the data grid.
Considerations
Web Application Context
Global HTTP session sharing works only when your application is deployed as a non-root context. It is relying on browser cookies for identifying user session, specifically JSESSIONID
cookie. Cookies are generated at a context name per host level. This way all the links on the page are referring to the same cookie/user session.
WebSphere Application Server HttpSessionIdReuse Custom Property
When using XAP Global HTTP session sharing with applications deployed into WebSphere Application Server, please enable the HttpSessionIdReuse custom property. In a multi-JVM environment that is not configured for session persistence setting this property to true enables the session manager to use the same session information for all of a user’s requests even if the Web applications that are handling these requests are governed by different JVMs.
Transient Attribute
An attribute specified as transient would not be shared and its content will not be stored within the IMDG. Your code should be modified to have this as a regular attribute that can be serialized.