As I mentioned in Chapter 4, Implementing Domain Objects, the sample application that accompanies the book is a banking application containing three components.
The central component is an online banking Java application built on top of Coherence. This is where pretty much all of the business logic for the whole solution resides, encapsulated within a set of rich domain objects. It uses Spring MVC (http://www.springsource.org/) to expose REST endpoints to an ExtJS (http://www.extjs.com/) frontend, and uses H2 database (http://www.h2database.com/) as a persistent data store behind Coherence.
These third-party components were chosen by me and the team of my colleagues who helped with the implementation of the sample application, either because we were already familiar with them and found them to be the most appropriate tools for the job, as was the case with Spring and ExtJS, or because they helped simplify the testing and deployment of the application, as was the case with H2. We have also embedded Jetty web server (http://jetty.codehaus.org/jetty/) into the application for the same reason.
The second component of the solution is a .NET application that uses WPF for the presentation layer and relies on data binding to CQC (Continuous Query Cache) to display account balance changes and a list of account transactions in real time.
The third and last component is a C++ command line application that emulates an ATM. It demonstrates implementation of a parallel domain model in C++, and how you can use entry processors from a C++ client to execute business logic within the cluster.
The remainder of this chapter is a step-by-step guide to get the whole solution up and running and start playing with it. Obviously, the fact that we have to deal with three different platforms introduces some complexity, but we have spent a significant amount of time creating and tuning build scripts that will do most of the heavy lifting for you.
I hope you find the sample applications as interesting to read as they were for us to write.
Note
Huge thanks to the Coherent Bank development team
I'd like to use the opportunity to thank once more to my friends who helped with the development of the sample application. I think they have done a great job on a very tight schedule and I'm very proud of the end result:
Marko Dumić, my colleague from S4HC, implemented the ExtJS frontend for the web application.
Ivan Cikić, Nenad Dobrilović, and Aleksandar Jević, also from S4HC, all worked on the .NET client at some point. Ivan implemented the C++ client as well.
My guest authors, Patrick Peralta and Marko Falco, contributed as well—Patrick implemented the persistence layer for the Java application, and Mark helped with the C++ client implementation.
Once again—thank you guys for all the hard work and enthusiasm you have put into this despite my crazy requests to add yet another feature at 3 am ☺. You are the best!
Before you can build, deploy, and run the various components of the Coherent Bank application, you will need to have several prerequisites in place.
First of all, we strongly suggest that you run all the components of the application on a single Windows XP machine, at least the very first time. There are several reasons for this, but the most important one is that Windows is the only OS where you will be able to run all three applications —while we have tested Java and C++ applications both on Windows and OS X, you will only be able to run .NET application on Windows.
Once you become more familiar with the application architecture and configuration, you can experiment by moving things around and running the Coherence cluster across multiple machines, the web application on OS X, the .NET application on Windows, and the C++ application on Linux, but in the beginning you should keep things simple.
The following sections document other software you will need and any specific configuration settings you need to make.
If you don't already have it (and my guess is you do), you should download and install the latest release of Sun's JDK 1.6. Make sure that you have the full JDK installed, not just the JRE.
You will also need to set the JAVA_HOME environment variable to point to your JDK. For example, if you installed JDK into the default location, your JAVA_HOME should look similar to the following:
JAVA_HOME=C:Program FilesJavajdk1.6.0_18
You will need Visual Studio 2008 to build the .NET and C++ sample applications. If you don't already have it, you can download express editions of Microsoft Visual C# and Microsoft Visual C++ from http://www.microsoft.com/express/Windows/, but please keep in mind that we have only tested the build process with the full version of Visual Studio 2008.
The .NET application requires .NET Framework 3.5, but if you have Visual Studio 2008 this should already be installed.
The application should work with other Coherence versions as well, but it has been tested with 3.5.3 only, so it is strongly recommended that you use that release.
You will need to download and install several packages:
Download the Coherence Java release and install it according to the instructions in Chapter 2, Getting Started. Set the
COHERENCE_HOMEenvironment variable to point to your installation directory containing thebin, lib, and other Coherence folders.Download and install Coherence for C++ 32-bit Windows release. You should install it by extracting the
coherence-cppdirectory from the downloaded archive into theCOHERENCE_HOMEdirectory. For example, if yourCOHERENCE_HOMEisC:coherence, your Coherence for C++ installation should be inC:coherencecoherence-cpp.Download and install Coherence for .NET. Simply run the installer from the download archive and accept the installation defaults when prompted. Make sure that you use the default installation path, as that's the location used to find
Coherence.dllwhen building the .NET sample application.
You will need to have Ant installed and in your system path in order to build and deploy the application. If you don't already have it, you can download it from http://ant.apache.org/.
Make sure that you set the ANT_HOME environment variable to the Ant installation directory and that you add ANT_HOMEin to your PATH.
You will need NAnt to build the .NET sample application. NAnt can be downloaded from http://nant.sourceforge.net/.
Make sure that you add NAnt's bin directory to system PATH as well.
In order to install the sample application, simply download CoherentBank.zip from the book's website and unzip it somewhere on your disk.
You should have a CoherentBank directory with three subdirectories: cpp, java, and net.
In order to deploy the Java application, you need to perform several steps:
Open a command prompt and navigate to the
CoherentBankjavadirectory.Edit
build.propertiesfile to reflect your environment.Start the H2 database:
> ant start-db-server
Start the web application:
> ant web-app
This should run the SQL script to create necessary tables, build the application, start the embedded Jetty web server, and open up the web browser showing the login screen.
If the web server fails to start make sure that you don't have anything else running on port 8080 and retry (or alternatively, change the
jetty.portproperty within thebuild.xmlfile).If the browser does not open automatically, make sure that you have specified the correct browser location in the build.properties file, or open the browser manually and navigate to http://localhost:8080/bank/login.
Log in using one of the test users from the following table, or create an account for yourself by clicking on the register here link below the login form.
The test accounts that are set up by default are:
Username
Password
sele
pass
aca
pass
marko
pass
ivan
pass
mark
pass
patrick
pass
Play with the application—post some transactions by paying bills, look at the transaction list, edit a user profile, and so on.
Start the Coherence Extend proxy server:
> ant start-extend-proxy
This will allow C++ and .NET clients to connect to the cluster.
Note
Optional: Run independent cache servers
By default, the web application runs as a storage-enabled Coherence node to simplify deployment, even though that is not how you would run it in production.
If you want to simulate a more realistic environment, uncomment the -Dtangosol.coherence.distributed.localstorage=false JVM argument within start-web-server target in build.xml.
However, if you do this you will need to run one or more cache servers before Step 4. You can do that by changing the startup sequence to:
> ant start-db-server > ant start-cache-server (one or more times) > ant web-app > ant start-extend-proxy
In order to build the C++ ATM application, you will need to do the following:
Open Visual Studio 2008 Command Prompt and navigate to the
CoherentBankcppdirectory. This will ensure that all environment variables necessary to run Microsoft C++ compiler are properly configured.> build
This should compile and link the application and copy the executable and necessary configuration files into the
distsubdirectory.
Navigate to the
distsubdirectory.Run the application with no arguments:
> atm
This should print out usage instructions:
Usage: atm <deposit|withdraw> <account number> <amount> <currency code>
Run the application one or more times against one of the accounts you have access to (you can see them in the web application when logged in). For example, if you want to withdraw $200 from the account with the ID 10 run the following:
> atm withdraw 10 200 USD
You should see a response similar to the following:
Transaction Details ---------------------------------- Type: WITHDRAWAL Description: ATM withdrawal ($ 200.00 @ 0.6630) Amount: 132.6 EUR Balance: 20745.4 EUR
Do several withdrawals and deposits against the same account and then view the account transactions in the web application.
In order to build and run the .NET application, you need to do the following:
Open a command prompt and navigate to the
CoherentBank etdirectory.Build and run the BranchTerminal sample application:
> nant run-terminal
This should build and start the .NET client and display a list of all the accounts, grouped by customer. You can click on an account to see a list of transactions on the right.
Post some transactions by paying bills from the web application and by making ATM withdrawals and deposits using the C++ application and watch how the account balance and transaction list are updated in real time.
Shutting down the .NET application is easy (simply close the application window), and the C++ application is even easier—it terminates automatically after each execution, so there is nothing you need to do.
However, shutting down all server-side components is a bit trickier, especially if you started multiple cache servers. At the very least you will need to shut down the web server, Extend proxy server, and database server.
What makes this even more complicated is that all these processes were started in the background using the Ant script, making them almost invisible. However, if you open Task Manager, you will see a number of java.exe processes running:
So, in order to shut down everything on the server, you can kill java.exe processes one by one in Task Manager.
However, there is an easier way, at least for all processes that are part of the Coherence cluster, which includes the web server, proxy server, and all cache servers you have started.
The Ant build file contains a stop-cluster target, which will send an invocable agent (see Chapter 6, Parallel and In-Place Processing, if you don't remember what that is) that executes System.exit() to all cluster members, effectively shutting them down gracefully.
> ant stop-cluster
However, before you run this task, make sure that your sample application cluster is fully isolated from any other clusters you might have on your network. Otherwise, there is a possibility that the stop-cluster task might decide to send the shutdown agent to your production cluster as well! If you are not sure, be safe and kill the processes from the Task Manager instead.
The last thing you need to do is to shut down the database server as well. You can try to do so by running this Ant task:
> ant stop-db-server
However, my experience so far has been that this task rarely succeeds, so you might need to kill the last remaining java.exe process using Task Manager (or if you have multiple java.exe processes running even after you have shut down the cluster, look for one that uses approximately 30 MB of memory).
The main reason for the sample application's existence is not the functionality it provides (which is fairly limited), but the implementation code behind it that demonstrates some Coherence best practices. By reviewing the sample code while reading the book, you will gain a lot more than by simply reading the book alone.
You should also download the latest Coherence Tools release from http://code.google.com/p/coherence-tools/, as that's where most of the base and utility classes used in the sample application are.
Reviewing Coherence Tools code along with the sample application code that depends on it is highly recommended. It will give you the most "bang for the buck", as you'll be better able to leverage Coherence Tools classes and components on your next project.
Enjoy!