z2-Environment

h1. Sample that combines HBase with full-stack Spring and Hibernate usage

(HOLD ON FOR A SECOND - STILL WORKING ON IT)

This sample consists of an application that loads large Mbox archive files into HBase and extracts email addresses using a map reduce job. Extracted email addresses are then written to a relational database and offered for editing.

Being a full stack sample it shows how to design a multi-module application with a service tier that can be seamlessly used from a Web app as well as from an application-level map-reduce job.

*Note*: This sample still uses v2.2 of z2 - so making sure the correct versions are specified below is crucial.

*Note*: Due to HBase, you will need to run this on Linux or Mac OS.

Proceed to [[Sample-hbase-mail-digester#How-this-works|how this works]], if you do not want to run the sample but only learn about it.

h2. Install

Here is the quick guide to getting things up and running. This follows closely [[How_to_run_a_sample]] and [[Install_prepacked_CDH4]].

h3. Checkout

Create some installation folder and check out the z2 core and the HBase distribution, as well as the sample application. 

<pre><code class="bash">

git clone -b v2.2 http://git.z2-environment.net/z2-base.core

git clone -b v2.2 http://git.z2-environment.net/z2-samples.cdh4-base

git clone -b master http://git.z2-environment.net/z2-samples.hbase-mail-digester

</code></pre>

(Note: Do not use your shared git folder, if you have any, as the neighborhood of these projects may be inspected by z2 later on).

h3. Prepare

We need to apply some minimal configuration for HBase. At first, please follow [[Install_prepacked_CDH4]] on how to configure your HBase checkout. There are a few steps that need to be taken once only but still have to.

Assuming HBase has started and all processes show as described, there is one last thing to get running before starting the actual application:

{{include(How to run Java db)}}

h2. Start

Now that all databases are up we can start the application simply by running (as always):

<pre><code class="bash">

# on Linux / Mac OS:

cd z2-base.core/run/bin

./gui.sh

# on Windows:

cd z2-base.core\run\bin

gui.bat

</code></pre>

At first startup this will download some significant amount of dependencies (Spring, Vaadin, etc.). So go and get yourself some coffee....

When started, go to http://localhost:8080/digester-admin. You should see this:

!start.png!

h2. Using the application

To feed data into the application, please download some mail archive in mbox format, e.g. from http://tomcat.apache.org/mail/. Upload the file to the digester application as outlined on the first tab. Mails from mail archives are imported into the HBase database.

When imported, run the analysis map-reduce job by clicking on "Start analysis job". The purpose of this job is to identify mail senders and provide some data like email address, full name, and number of mails into the relational database powered by Derby.

When there is only little data in HBase, progress reporting is rather coarse-grained. After a while you should see:

!job.png!

And work should be completed shortly after. When done, check the extracted sender data:

!counts.png!

h2. How this works

Let's go module by module in "z2-samples-hbase-mail-digester":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester

*com.zfabrik.samples.digester.mail.domain*

This modules defines data types and storage access for HBase stored e-mail messages. The interface "EmailRepository":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.domain/java/src.api/com/zfabrik/samples/digester/mail/EMailRepository.java is the main storage access interface. It's implementation can be found at "EmailRepositoryImpl":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.domain/java/src.impl/com/zfabrik/samples/impl/digester/mail/EmailRepositoryImpl.java.

The Spring Bean "HBaseConnector":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.domain/java/src.impl/com/zfabrik/samples/impl/digester/mail/HBaseConnector.java, used by the e-mail repository manages HBase connections.

*com.zfabrik.samples.digester.mail.admin*

This module defines the _Mails_ tab that is loaded via an extension point (see [[Vaadin-addon]] for more details on what that is) from the main tab (defined in *com.zfabrik.samples.digester.admin* - below). Also it defines the _Mail file import_ activity (another extension point). The Mails tab is defined via the component "com.zfabrik.samples.digester.mail.admin/mailListView":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.admin/mailListView.properties and the Mail file import activity via the component "com.zfabrik.samples.digester.mail.admin/actionsView":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.admin/actionsView.properties.

As this module interacts mainly with the e-mail repository, it imports it from "com.zfabrik.samples.digester.mail.domain/emailRepository":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.domain/emailRepository.properties in its "application context":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hbase-mail-digester/revisions/master/entry/com.zfabrik.samples.digester.mail.admin/java/src.impl/META-INF/applicationContext.xml