DigiPri Widgets sales dashboard – Part 2: Setting up the server application

This article is Part 2 of a series of articles and tutorials centered on a sales dashboard application built using Flex and the Adobe Flash Platform. The individual articles in the series are designed to stand on their own, so you can read all of them or just the ones that interest you, in whatever order you like.

This part steps you through the process of setting up the server application for the DigiPri Widget sample application. For an overview of the application, see Part 1: Overview. For a closer look at the application and its architecture, see Part 3: Understanding the dashboard application. For a more in-depth look at the code, see Part 4: Exploring the code in Flash Builder.

The DigiPri Widgets sales dashboard uses BlazeDS, the server-based Java remoting and web messaging technology, to connect the Adobe Flex front end to the back-end server application. In developing the dashboard, the focus was on developing an application that illustrated Flex and BlazeDS independent of the server-side technology used. With this in mind, the main goals in building the server application were to keep it simple, straightforward, and easy to understand so that it could be adapted to another language, application server, or database. As a result, the server-side implementation does not include any additional frameworks—such as Spring and Hibernate—that one might employ when building a production-ready or mission-critical application.

In the spirit of simplicity, the server software is based on easy-to-set-up and free software packages so you can set up and deploy the application on your own development workstation. These software packages include MySQL 5.1 RDBMS, J2SE 5.0 (Java Platform Standard Edition 5.0), and the latest production release of BlazeDS (the turnkey download contains a ready-to-use version of Tomcat, currently version 6.0.14).

To get started, you'll need to download the following software packages:

• MySQL 5.1: The MySQL Community Server is freely downloadable.
• J2SE 5.0 (Java 2 Platform, Standard Edition 5.0): If you already have JRE 1.5.0 or greater installed, you can skip this.
• MySQL Connector/J: This is the Java application archive (JAR) file used by the Java application to connect to the MySQL database server.
• BlazeDS: Select the turnkey download with the ready-to-use version of Tomcat (version 6.0.14).

This article explains how to install and configure each software package in order to deploy and test the server application. You'll need to install the software packages in the order presented here to avoid configuration problems.

Database setup and configuration

After downloading the MySQL 5.1 binary distribution for your particular operating system, follow the instructions included with the download to install the software.

Next, download and install the MySQL Administrator and MySQL Query Browser tools, which you'll need to follow the steps below. If you are familiar with the MySQL command line and prefer to work with it, you should be able to make the necessary configurations based on the following instructions.

Start the restore operation and create your schema

First, you'll need to create the database schema for the CRM server application. Instead of creating a new database and each table manually, you can use the restore feature in the MySQL Administrator tool to create the schema and populate the database from the backup file, adobeCRM_backup.sql, which is included with this article's sample files.

Follow these steps to create the database:

1. Run the MySQL Administrator tool and click Restore (see Figure 1).

2. To begin the restore operation click Open Backup File (Windows) or Choose File (Mac OS X) and then browse to the adobeCRM_backup.sql sample file.
3. Click Open.

   On Mac OS X you'll see the adobeCRM database schema ready to be restored. On Windows, you have to perform an extra step to ensure the backup file is ready for the restore operation.

4. If you're running the Windows MySQL Administrator tool, click the Restore Content tab (see Figure 2) and then click Analyze Backup File Content. You should now see the database schema ready to be restored.

5. Click Start Restore (Windows) or Restore Backup (Mac OS X) to begin the restore process (see Figure 3).

Create a new user account

After restoring the database schema you need to create a user account for accessing the database used by the application.

1. Run the MySQL Administrator tool and click User Administration (Windows) or Accounts (Mac OS X).
2. To create a new MySQL user on Windows, click Add New User near the bottom of the screen; on Mac OS X click the Add New User icon in the lower left-hand corner of the screen as (see Figure 4).

3. In the Login Information group on the right of the screen, type adobeCRM as the user name and type adobeCRM as the password (see Figure 5). Both the user name and password are case sensitive.

   Note: You can configure the user name and password used to access the data source later by editing the META-INF/context.xml file when the application is deployed. The default configuration uses adobeCRM for both by default.

After you have created the user, you need to grant schema privileges to the adobeCRM user account.

On Mac OS X, however, you first have to associate a host (that is, location) from which the adobeCRM user account can connect to the database. To do this, click the Add Host button located in the lower left-hand corner of the MySQL Administrator tool (see Figure 6) and select localhost in the dialog box that appears.

4. With the adobeCRM account selected, click the Schema Privileges tab in the User Administration screen (Windows) or click Schema Privileges on the Accounts screen (Mac OS X).
5. Select the adobeCRM database schema in the Schemata pane (Windows) or the Schemas pane (Mac OS X).

   Note: Depending on how you choose to configure your instance of the MySQL 5.1 database server, you may see the schema name as adobecrm (note the name is lowercased). This should not have any impact on the application accessing the database, but it is worth noting the discrepancy.

   You now need to select the appropriate privileges for the adobeCRM user. Since the application is a sample and not an application intended for production use, it can use a shotgun approach for granting user privileges (that is, you will be granting all privileges to the adobeCRM user.)

6. Click the Schema Privileges pane in the User Administration screen (Windows) or the Schema Privileges pane in the Accounts screen (Mac OS X).
7. On Windows, click the << button to assign all privileges (see Figure 7).

8. On Mac OS X, you must first select localhost as the host associated with the adobeCRM user account (see Figure 8). Next, select all the available privileges and add them using the Add Privileges (<) button.

Note: If you were building a mission-critical or production-use application, you would most certainly want to grant only the privileges necessary for the adobeCRM user to get the data it needs. Granting all privileges to a user is not common practice and is strongly discouraged.

After you have assigned the schema privileges to the adobeCRM user, your database is ready to be used by the server application.

Server setup and configuration

The BlazeDS turnkey download includes a preconfigured, fully functioning version of Apache Tomcat, an open source servlet container.

After downloading the BlazeDS turnkey distribution, extract the files to C:/blazeds on Windows or Applications/blazeds on Mac OS X. In order to run the DigiPri Widgets dashboard application, you must have access to this directory so you can start and stop Tomcat.

Configuration

Once you have BlazeDS with Apache Tomcat installed, you need to download and install the MySQL Connector/J Java application archive (JAR file), which is used by the Java application to connect to the MySQL database server:

1. Download and extract MySQL Connector/J.
2. Copy the mysql-connector-java-5.1.12-bin.jar file to Tomcat's lib directory.

Note: The version number (5.1.12) may change; it's OK if the version you download has higher numbers.

It is important to note if you started from a standalone Tomcat installation (instead of the turnkey BlazeDS version) you would have more configuration steps to do. For example, you would have to build and deploy both a web.xml file and a context.xml file, which are responsible for defining various aspects of the Java server application. A detailed explanation of these two files is outside the scope of this article, but for the purposes of the DigiPri Widgets sample application you need not edit them; they are already preconfigured.

Deploying the web application

Now that you've configured Tomcat and the MySQL database connector is in its proper location, you need deploy the DigiPri Widgets dashboard web application itself:

1. Copy the adobeCRM.war (Web Application Archive) sample file to the webapps directory in the Tomcat installation directory. (The WAR file is included in the sample ZIP file that accompanies this tutorial.)
2. Start the Tomcat server by changing to the Tomcat/bin directory and executing startup.bat (Windows) or startup.sh (Mac OS X).
3. After Tomcat starts, access the application in your browser at the following URL:

http://localhost:8400/adobeCRM

If everything is set up correctly, you should see the DigiPri Widgets sales dashboard application with data being returned from the server and showing up in the various report views. If you do not see data being populated in the charts, here is a list of items to troubleshoot.

1. Make sure that you assigned the proper privileges to the adobeCRM account in MySQL Administrator.
2. Double check that the user name and password in the META-INF/context.xml file correspond to your MySQL server user account.
3. Ensure that MySQL server and Tomcat are currently running.

Where to go from here

Now that you have the application up and running, you can read the DigiPri Widgets overview in Part 1 (if you haven't already done so) or proceed to Part 3, Understanding the Dashboard Application, to learn more about Flex 4 integration with the server-side implementation. Alternatively, you can skip to Part 4 to explore the client-side code.