Child pages
  • Sessions Tutorial

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
Column
width260px
Wiki Markup
{div:style=margin-top:20px}
{include:documentation-index}
{div}
Column
Wiki Markup
{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}<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 _<spring_dir>/samples/jpetstore_
# Run _ant warfile_

{code}
%> 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:start_db}

h2. Start the JPetStore Database

# Change directories to _<spring_dir>/samples/jpetstore/db/hsqldb/_
# Run the _server.sh_ script.

{code}
%> cd <spring_dir>/samples/jpetstore/db/hsqldb/ %> sh server.sh
{code}
{anchor: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 _<spring_dir>/samples/jpetstore/dist/jpetstore.war_
&nbsp;

!import_webapp_chooser.png!

{anchor: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 _[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 [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 [http://localhost:9081/jpetstore/] link.
# Enter the store and add an item to your cart.
# Switch back to the _Terracotta Sessions Configurator_ a click on the [http://localhost:9082/jpetstore/] link.
# In the new browser window, browse to the shopping cart.  Your shopping cart from the server on port _9081_ should be intact on the server on port _9082_.

!full_cart_browser_pair.png!

{anchor: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 _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!

*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}