Child pages
  • Sessions Tutorial

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

pagetitle
Sessions Tutorial
Section
Column
width260px
{div:style=} {include:
Wiki Markup
Div
stylemargin-top:20px
Include Page
documentation-index
documentation-index
} {div}
Column
{div9:id=documentationcolumn} {include:HeaderBasic} h1. Clustering a Spring Web Application {toc:minLevel=2|maxLevel=2} h2. Purpose {excerpt} This tutorial shows how to configure a web application for session clustering using Terracotta Sessions. By the end of the tutorial, you should be ready to use Terracotta Sessions on your own Web applications. {excerpt} h2. What You'll Need # Terracotta Software # [The Spring Framework| http://prdownloads.sourceforge.net/springframework/spring-framework-1.2.8-with-dependencies.zip?download] \- We'll be using the _Spring JPetStore_ example application. # [Apache Ant|http://ant.apache.org/] h2. What You'll See At the end of the tutorial, you will have multiple application servers running a web application with clustered sessions. h2. Overview The basic steps of this tutorial are: # [Download and install _Terracotta_.|#getting_started] # [Download Spring and build the Spring JPetStore sample.|#build_it] # [Start the JPetStore database.|#start_db] # [Start the Terracotta Sessions Configurator|#start_configurator] # [Import the JPetStore WAR into the Terracotta Sessions Configurator.|#import_war] # [Start the application servers without Terracotta enabled.|#start_app_without_tc] Verify that the application works without _Terracotta_ and that its sessions are not clustered. # [Restart the application with Terracotta enabled. Verify that session clustering works.|#start_app_with_tc] # [Inspect the clustered sessions object graph.|#inspect_session_graph] _Terracotta_ enables runtime visibility into live clustered objects. {anchor:getting_started} h2. Getting Started # Download and install {html}
Wiki Markup
Div
iddocumentationcolumn
Include Page
HeaderBasic
HeaderBasic

Clustering a Spring Web Application

Table of Contents
minLevel2
maxLevel2

Purpose

Excerpt

This tutorial shows how to configure a web application for session clustering using Terracotta Sessions. By the end of the tutorial, you should be ready to use Terracotta Sessions on your own Web applications.

What You'll Need

  1. Terracotta Software
  2. The Spring Framework - We'll be using the Spring JPetStore example application.
  3. Apache Ant

What You'll See

At the end of the tutorial, you will have multiple application servers running a web application with clustered sessions.

Overview

The basic steps of this tutorial are:

  1. Download and install Terracotta.
  2. Download Spring and build the Spring JPetStore sample.
  3. Start the JPetStore database.
  4. Start the Terracotta Sessions Configurator
  5. Import the JPetStore WAR into the Terracotta Sessions Configurator.
  6. Start the application servers without Terracotta enabled. Verify that the application works without Terracotta and that its sessions are not clustered.
  7. Restart the application with Terracotta enabled. Verify that session clustering works.
  8. Inspect the clustered sessions object graph. Terracotta enables runtime visibility into live clustered objects.

Anchor
getting_started
getting_started

Getting Started

  1. Download and install
    HTML
    <a href="/dl/">Terracotta</a>
{html}. # Download and unzip [The Spring Framework| http://prdownloads.sourceforge.net/springframework/spring-framework-1.2.8-with-dependencies.zip?download]. We'll be using the _JPetStore_ sample application that comes with the _Spring Framework_ kit. # Download and install [_Apache Ant_|http://ant.apache.org/] if you don't have it installed already. Detailed instructions for installing _Ant_ are in the [Apache Ant Manual|http://ant.apache.org/manual/index.html] {anchor:build_it} h2. Build the Spring JPetStore Sample *Note*: For more detailed instructions on building the _JPetStore_ sample, see the _readme.txt_ file in the jpetstore samples directory. # Change directories to _
  1. .
  2. Download and unzip The Spring Framework. We'll be using the JPetStore sample application that comes with the Spring Framework kit.
  3. Download and install Apache Ant if you don't have it installed already. Detailed instructions for installing Ant are in the Apache Ant Manual

Anchor
build_it
build_it

Build the Spring JPetStore Sample

Note: For more detailed instructions on building the JPetStore sample, see the readme.txt file in the jpetstore samples directory.

  1. Change directories to <spring_dir>/samples/jpetstore
_ # Run _ant warfile_ {code}
  1. Run ant warfile
Code Block

%> cd <spring_dir>/samples/jpetstore
%> ant warfile
{code}

This

will

leave

the

_

JPetStore

_

WAR

file

in

_

<spring_dir>/samples/jpetstore/dist/jpetstore.war

_&nbsp; {anchor:

 

Anchor
start_db
start_db

} h2. Start the JPetStore Database # Change directories to _

Start the JPetStore Database

  1. Change directories to <spring_dir>/samples/jpetstore/db/hsqldb/
_ #
  1. Run
  1. the
_
  1. server.sh
_
  1. script.
{
Code Block
}

%> cd <spring_dir>/samples/jpetstore/db/hsqldb/ %> sh server.sh
{code} {anchor:

Anchor
start_configurator
start_configurator

} h2. Start the Terracotta Sessions Configurator You can [obtain the Sessions Configurator from the Terracotta forge|http://svn.terracotta.org/svn/forge/projects/session-configurator]. See the [README.txt|http://svn.terracotta.org/svn/forge/projects/session-configurator/README.txt] for information on how to run the Sessions Configurator. See the [Sessions Configurator Guide] for an introduction to the Sessions Configurator. h2. Import the JPetStore WAR *Note:* If the welcome screen is not visible, you can use the _File -> Import..._ menu. Import the _JPetStore_ application by clicking the _Import..._ button. !import_webapp.png! Use the file chooser to select _

Start the Terracotta Sessions Configurator

You can obtain the Sessions Configurator from the Terracotta forge. See the README.txt for information on how to run the Sessions Configurator. See the Sessions Configurator Guide for an introduction to the Sessions Configurator.

Import the JPetStore WAR

Note: If the welcome screen is not visible, you can use the File -> Import... menu.

Import the JPetStore application by clicking the Import... button.

Image Added

Use the file chooser to select <spring_dir>/samples/jpetstore/dist/jpetstore.war

_ &nbsp; !import_webapp_chooser.png! {anchor:


 

Image Added

Anchor
start_app_without_tc
start_app_without_tc

} h2. Start the Application Servers Without Terracotta Ensure that the _Terracotta Sessions enabled_ checkbox is _NOT_ selected. Click the _Start all_ button to start the application servers. This will start two instances of the application server in two separate Java Virtual Machines. Each of these application servers has its own instance of the web applications deployed inside them. The first few applications are _Terracotta_ sample applications. You should see the _JPetStore_ application listed below. !start_servers.png! h2. View the Application Unclustered When the application servers have started, the hyper links to the different instances of the web applications will become active. Click on the _[

Start the Application Servers Without Terracotta

Ensure that the Terracotta Sessions enabled checkbox is NOT selected. Click the Start all button to start the application servers.

This will start two instances of the application server in two separate Java Virtual Machines. Each of these application servers has its own instance of the web applications deployed inside them. The first few applications are Terracotta sample applications. You should see the JPetStore application listed below.

Image Added

View the Application Unclustered

When the application servers have started, the hyper links to the different instances of the web applications will become active.

Click on the http://localhost:9081/jpetstore/

_]

_

link.

This

will

open

your

browser

to

the

application

server

instance

listening

on

port

_

9081

_. !servers_started_nodso.png! Click on the _Enter the Store_ link. !enter_store.png! You should see the _JPetStore_ homepage. !jpetstore_home.png! *Note:* If you get an error that says *"Could not open JDBC Connection for transaction"*, the _JPetStore_ database is not running. [Go back to that step|#start_db] and start the database. Browse to one of the product pages and add an item to your shopping cart. Your cart should look something like this: !full_cart.png! Now switch back to the _Terracotta Sessions Configurator_ and click on the [

.

Image Added

Click on the Enter the Store link.

Image Added

You should see the JPetStore homepage.

Image Added

Note: If you get an error that says "Could not open JDBC Connection for transaction", the JPetStore database is not running. Go back to that step and start the database.

Browse to one of the product pages and add an item to your shopping cart. Your cart should look something like this:

Image Added

Now switch back to the Terracotta Sessions Configurator and click on the http://localhost:9082/jpetstore/

]

link.

This

will

open

your

browser

to

the

application

server

instance

listening

on

port

_

9082

_. !servers_started_nodso.png! In the new browser window, click the shopping cart icon. You should see an empty shopping cart. !empty_cart.png! Because the two application servers, _9081_ and _9082_, are running in separate JVMs and they aren't clustered, the session data that contained your shopping cart items is lost when you move from one application server to the next. The result is frustrated customers and lost sales. !empty_cart_browser_pair.png! This is precisely what happens when multiple application servers are load balanced and user sessions move from one application server to another. This may happen, for example, in the event that one or more application servers have crashed or have been taken down for maintenance. Now let's watch what happens to your shopping cart when _Terracotta_ session clustering is turned on. {anchor:start_app_with_tc} h2. Start the Application Servers With Terracotta Switch back to the _Terracotta Sessions Configurator_ and stop the application servers by clicking on the _Stop all_ button. When the servers have stopped, click on the _Terracotta Sessions enabled_ checkbox. !start_servers_terracotta_enabled.png! Click on the _Start all_ button and, this time, the application servers will start with _Terracotta_ session clustering enabled. !servers_started_terracotta_enabled.png! When the servers have started, go through the same process of adding items to you cart in one server and checking the contents of the cart in the other server: # Click on the [

.

Image Added

In the new browser window, click the shopping cart icon. You should see an empty shopping cart.

Image Added

Because the two application servers, 9081 and 9082, are running in separate JVMs and they aren't clustered, the session data that contained your shopping cart items is lost when you move from one application server to the next. The result is frustrated customers and lost sales.

Image Added

This is precisely what happens when multiple application servers are load balanced and user sessions move from one application server to another. This may happen, for example, in the event that one or more application servers have crashed or have been taken down for maintenance.

Now let's watch what happens to your shopping cart when Terracotta session clustering is turned on.

Anchor
start_app_with_tc
start_app_with_tc

Start the Application Servers With Terracotta

Switch back to the Terracotta Sessions Configurator and stop the application servers by clicking on the Stop all button.

When the servers have stopped, click on the Terracotta Sessions enabled checkbox.

Image Added

Click on the Start all button and, this time, the application servers will start with Terracotta session clustering enabled.

Image Added

When the servers have started, go through the same process of adding items to you cart in one server and checking the contents of the cart in the other server:

  1. Click on the http://localhost:9081/jpetstore/
]
  1. link.
#
  1. Enter
  1. the
  1. store
  1. and
  1. add
  1. an
  1. item
  1. to
  1. your
  1. cart.
#
  1. Switch
  1. back
  1. to
  1. the
_
  1. Terracotta
  1. Sessions
  1. Configurator
_
  1. a
  1. click
  1. on
  1. the
[
  1. http://localhost:9082/jpetstore/
]
  1. link.
#
  1. In
  1. the
  1. new
  1. browser
  1. window,
  1. browse
  1. to
  1. the
  1. shopping
  1. cart.
  1. Your
  1. shopping
  1. cart
  1. from
  1. the
  1. server
  1. on
  1. port
_
  1. 9081
_
  1. should
  1. be
  1. intact
  1. on
  1. the
  1. server
  1. on
  1. port
_
  1. 9082
_. !full_cart_browser_pair.png! {anchor:
  1. .

Image Added

Anchor
inspect_session_graph
inspect_session_graph

} h2. Inspect the Clustered Session Object Graph Switch back to the _Terracotta Sessions Configurator_ and click on the _Monitor_ tab at the top of the window. !configurator_tabs.png! Expand the _Roots_ tree and select the _

Inspect the Clustered Session Object Graph

Switch back to the Terracotta Sessions Configurator and click on the Monitor tab at the top of the window.

Image Added

Expand the Roots tree and select the tc:tomcat_session_jpetstore

_

element.

This

is

a

real-time

view

of

the

clustered

session

object

graphs.

These

are

the

plain

Java

objects

that

are

currently

in

your

session.

!session_graph.png! *

Image Added

Note:

*

to

refresh

the

object

graph

view,

click

on

the

element

or

select

it

and

press

_

F5

_

on

your

keyboard.

You

can

also

right-click

on

an

element

to

see

a

context

menu.

Explore

the

object

tree

to

see

what's

in

the

session.

You

should

be

able

to

find

individual

shopping

cart

items

in

the

graph.

Try

changing

the

quantities

of

certain

items

in

your

cart

and

updating

the

object

graph

view

in

the

_

Terraotta

Sessions

Configurator

_

.

You

should

be

able

to

see

the

changes

to

those

objects

in

the

object

graph

view.

!session_graph_detail.png! h2. Conclusions This tutorial has taken you through the process of importing a web application into the _Terracotta Sessions Configurator_ and viewing the application with _Terracotta_ session clustering disabled and enabled. _Terracotta Sessions Configurator_ is an easy way to get started with _Terracotta_ and to watch the behavior of your clustered application at runtime. h2. Resources * [_The Spring JPetStore_|http://www.springframework.com/] sample application was written by Juergen Hoeller * _The Spring JPetStore_ sample application is based on Clinton Begin's _[_JPetStore_|http://www.ibatis.com/]__._ * [Manually Configuring Web Applications|docs:Configuration Guide and Reference#web applications] * [Terracotta Sessions Configurator Guide|docs:Sessions Configurator Guide] {div9}

Image Added

Conclusions

This tutorial has taken you through the process of importing a web application into the Terracotta Sessions Configurator and viewing the application with Terracotta session clustering disabled and enabled. Terracotta Sessions Configurator is an easy way to get started with Terracotta and to watch the behavior of your clustered application at runtime.

Resources