LCDS ships with the default Tomcat roles based security ready to go. You simply add some users to the tomcat-users.xml and there you go. This is probably fine for some, but for my needs I want to be able to authenticate against a MySQL database. I addition, I want to use strong encryption to protect my users personal information, as well as potentially sensitive business data. In this article I am going to explain how to configure Tomcat and Livecycle Data Services to do just that. It is actually fairly painless, once you get all the pieces put together. Hopefully this will be an area of the LCDS documentation that will get some attention in the future.

There are many robust frameworks available to Java that provide authentication functionality. In addition to that, they provide a level of complexity that I want to avoid. My primary purpose is creating enterprise Flex/AIR applications with a strong service layer provided by LCDS. I simply don't want to learn the intrict workings of Spring, JBoss Websphere, or any of the other fine solutions that might solve this particular problem. What I want is a simple solution that provides the functionality I need without a host of extra features I won't ever use. My finite capacity for new information needs all the filtering it can get.

The following assumes you are using the turnkey Tomcat LCDS installation.

Setting up the MySQL Database

Any JDBC connectable database solution should work, so long as the proper tables are in place. MySQL is used in this example simply for convenience.

Tomcat's realms (discussed below) require some specific tables in your database. It needs a User table that identifies the users and their passwords. In addition, there needs to be a user_roles table that corresponds to each user and their role(s) in the application.

1
2
3
4
5
6
7
8
9

create table users (
  username         varchar(15) not null primary key,
  password         varchar(15) not null
);
 
create table user_roles (
  username          varchar(15) not null,
  role              varchar(15) not null,
  primary key (username, role)

);

The above would be the be sufficient to provide JDBCRealm the information it needs for authentication. While I'm sure it would be possible to extend the JDBC realm further than I do in this walk-through

Configuring the Realm

Tomcat implements realms for security. At its simplest form we have the RealmBase class. This provides the functionality to parse simple XML files for users, passwords, and roles. In addition, there is a realm class JDBCRealm. This realm is a lot closer to what we actually need, and would probably be sufficient in many cases. While the JDBCRealm provides for the digesting of passwords into encrypted hashes for storage in the databse, I want to use a more robust encryption solution. Jasypt (Java Simplified Encryption) provides this, as well as transparent integration with Hibernate. This lets me put user's passwords in the database with salted hashes, and also provides the flexibility to encrypt virtually any other field in my data model.

To facilitate this addition, we need to extend the JDBCRealm, overriding the authenticate method to remove the default digest calls and replace them with the Jasypt StrongPasswordEncryptor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

package realm;
 
import org.apache.catalina.realm.*;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
 
import java.security.*;
import java.sql.Connection;
import java.util.ArrayList;
 
import org.jasypt.util.password.StrongPasswordEncryptor;
 
public class MyRealm extends JDBCRealm {
 
      private static Log containerLog = LogFactory.getLog(SAIRealm.class);
 
      StrongPasswordEncryptor passwordEncryptor = new StrongPasswordEncryptor();
 
      @Override
      public synchronized Principal authenticate(Connection dbConnection,
                                                 String username,
                                                 String credentials)
      {
            if (username == null) {
                  return (null);
            }
 
            String dbCredentials = getPassword(username);
 
            boolean validated = passwordEncryptor.checkPassword(credentials, dbCredentials);
            if (validated) {
                  if (containerLog.isTraceEnabled())
                       containerLog.trace(sm.getString("jdbcRealm.authenticateSuccess",
                       username));
            } else {
                  if (containerLog.isTraceEnabled())
                       containerLog.trace(sm.getString("jdbcRealm.authenticateFailure",
                       username));
                  return (null);
            }
 
            ArrayList<string> roles = getRoles(username);
 
            return (new GenericPrincipal(this, username, credentials, roles));
      }
}

This class needs to be compiled and placed into a Jar (FlexBuilder/Exlipse makes this easy through the file>export menu). The compiled class can now be added to the {lcds}/tomcat/lib folder so that it will be available to the server.

Now that we've added our custom realm to the server, we need to add it to the configuration files so that it is recognized.

In {lcds}\tomcat\conf\server.xml find the existing realm, and remove it (this might be something you can configure, multiple realms, but I didn't figure it out and don't need the stock XML database so I just killed it):

1
2
3
4
5
6
7
8
9
10

<engine name="Catalina" defaultHost="localhost">
      ...
      <realm className="realm.MyRealm"
           debug="99"
           driverName="com.mysql.jdbc.Driver"
           connectionURL="jdbc:mysql://localhost/mydatabase?user=dbUsername&amp;password=dbPassword"
           userTable="user" userNameCol="username" userCredCol="password"
           userRoleTable="user_roles" roleNameCol="role"/>
      ...
</engine>

In addition, your application's context file needs to supply information about the realm:

{lcds}/tomcat/conf/Catalina/localhost/{application_context}.xml

1
2
3
4
5
6
7

<realm className="realm.MyRealm"
           debug="99"
           driverName="com.mysql.jdbc.Driver"
           connectionURL="jdbc:mysql://localhost/mydatabase?user=dbUsername&amp;password=dbPassword"
           userTable="user" userNameCol="username" userCredCol="password"
           userRoleTable="user_roles" roleNameCol="role"/>
     <valve className="flex.messaging.security.TomcatValve"/>

I don't know if the additional database information is actually neccessary here, but it doesn't hurt anything, so there it is. This is also the place to define the Tomcat Valce so that Flex/LCDS can communicate with our custom realm. Note that it is important to FULLY qualify your classname for both the custom realm and the database connector classes.

Configuring the Services

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<security>
        <login-command class="flex.messaging.security.TomcatLoginCommand" server="Tomcat">
            <per-client-authentication>false</per-client-authentication>
        </login-command>
        <security-constraint id="jdbc-auth">
            <auth-method>Custom</auth-method>
            <roles>
                  <role>super</role>
                  <role>admin</role>
                  <role>user</role>
                  <role>client</role>
            </roles>
        </security-constraint>
      </security>

This is the basic configuration. Now you simply need to add the security tag to your destinations to enable.

1
2
3
4
5
6

<destination id="SecurePojo1">
        ...
        <security>
            <security-constraint ref="jdbc-auth"/>
        </security>
</destination>

You can also apply the constraint globally.

1
2
3
4

<service>
     ...
    <default-security-constraint ref="jdbc-auth"/>
</service>

or to individual methods

1
2
3
4
5
6
7
8
9
10
11
12

<destination id="sampleIncludeMethods">
    <properties>
        <source>my.company.SampleService</source>
        <include-methods>
            <method name="fooMethod"/>
            <method name="barMethod" security-constraint="jdbc-auth"/>
        </include-methods>
    </properties>
    <security>
        <security-constraint ref="jdbc-auth"/>
    </security>
</destination>

The Client

All of the complex bits are now taken care of. When you try to access a tagged destination you are flatly denied. To authenticate from Flex, your ChannelSet will need to login to the service. I use AIR, so I define my ChannelSets in the application, but Flex apps will automagically configure this for you and they are 'hidden'. To get at your ChannelSet in flex you need to use the ServerConfig class:

1
2
3
4

import mx.messaging.config.ServerConfig;
...
myChannelSet=ServerConfig.getChannelSet(remoteObject.destination);
myChannelSet.login("username","password");

If you have place in the main mxml file of your application and stare at the LCDS/Tomcat console, you should see a successful login. If not, I apologize for failing you up to this point ;(

One thing that the realm does NOT provide is a way to add new users or manipulate the database. I plan on getting into this in future articles, so stay tuned.

These files need to be added to the {lcds}/tomcat/lib folder:
icu4j-4_0.jar
jasypt-1.5.jar
commons-codec-1.1.jar
commons-lang-2.1.jar
mysql-connector-java-5.1.6-bin.jar
myrealm.jar

The Tools:

Flex Builder 3

You can use any IDE that you prefer, but I will be using Flex Builder 3 (with Java Development Tools installed).

LiveCycle Data Services [Download]

For the purposes of demonstration, and many production needs that don't require the additional processing power, the free version of LCDS with the single CPU limitation is more than adequate. Why not use BlazeDS? Well, BlazeDS doesn't have the RTMP support or the Hibernate adapters that are included with its big brother LCDS. My primary goal is to get Hibernate functioning with Flex/AIR, and LCDS is the shortest (easiest?) route that I am currently aware of. There are several ongoing projects to bring a hibernate adapter to BlazeDS, and it will be interesting to follow what comes about from those efforts.

Cairngorm Enterprise 2.2.1

Cairngorm is a versatile, lightweight MVC framework updated and maintained by Adobe. It is an open-source project, and extremely useful in a wide variety of use cases. That said, it doesn't provide me with the full feature set I desire in my MVC solution. It does, however, provide a most excellent service locator pattern that works extremely well with LCDS. The service locator is the only aspect of Cairngorm I am going to use in this exercise.

PureMVC Multicore 1.0.5

PureMVC is a robust open source MVC solution. It is a weightier than cairngorm in its approach, but that extra weight provides useful patterns for approaching view-centric RIA development. Simply put, I can't live without the Mediator's control over my view components. The Proxy pattern provides a highly controlled method for accessing, sorting, and maintaining my data. The Command is essentially the same as the system found in Cairngorm, but for the purposes of this project I will be using mostly PureMVC with cairngorm's EnterpriseServiceLocator providing the connectivity with LCDS on the backend.

Hibernate

Hibernate is an Object/Relational Management framework for Java. It provides seemingly magical functionality in this capacity. It isn't really magic, as digging through its open source will demonstrate, but it is highly configurable and generally easy to use. It abstract painful CRUD operations and solves the majority of the problems you encounter when combining relational databases with object oriented software systems.

Hibernate Tools

Hibernate tools is an Eclipse (Flex Builder) plugin that will reverse engineer Java objects and Hibernate config files from your database.

MySQL

MySQL is the relational database of choice for this series. It should be relatively painless to utilize your preferred relational database, but for the sake of simplicity, and my lack of experience with other systems, that is what I will be utilizing here.

This is a lot of ground to cover. It is a daunting task, but the results are worth the effort. Once you have a level of comfort with the tools, the resulting systems provide a maintainable structure that provides your users with a rich visual experience. Data is maintained and updated across all clients accessing the system. LCDS allows for users to interact with one another, provides offline synchronization capabilities, as well as a robust persistence framework via the LCDS Hibernate adapter. Flex provides a consistent cross-platform user experience and applications are easily brought to the desktop with the AIR runtime.

The Project:

This project is a simple image gallery that stores images in albums.

The Setup:

It is assumed that you can download and install all of the above tools, so I am not going to detail that process. There are some details in the process that I will cover here. These are annomolies, or frustrating problems that took some measure of significant time searching down solutions for.

MySQL

This is the database schema that will be used in the project. It is a simple two table structure. Note that we are using the INNOdb engine for the tables. I use XAMPP for my localhost configuration, and INNOdb is actually disabled by default. It is important to use INNOdb, as it supports foreign key constraints. These constraints will be used by the Hibernate Tools reverse engineering scripts to determine relationships across our object classes. While it isn't strictly necessary to use these tools, it saves a lot of initial typing.

This database structure is simple on purpose. You could add many other tables/fields to make this a more robust system. For the purposes of demonstration we will be applying KISS principles. Some ideas for expantion would be user accounts, thumbnails, slideshows, tagging, rating, or any other features that you might find in a photo album.

Create a database called 'slideshow' and apply the above SQL to create the two tables we will use for this demonstration.

LCDS

The default installation of LCDS contains some sample projects as well as a template project called LCDS. Because of limitations with the free single-cpu license, you are not able to run multiple applications. I move the default samples project out and rename the lcds project to slideshow (or better yet, move the lcds folder out and place a renamed copy of it back in the webapps folder.) You will also need to rename the context file that initializes the transaction manager utilized by Hibernate located in the {lcds-root}/tomcat/conf/Catalina/localhost folder. I removed the lcds-samples.xml, as well as the lcds.xml files after first making a copy of lcds.xml and renaming it slideshow.xml to match our application.

NOTE: If you are using Flex Builder, you will need to install the Java Development Tools. If you are using Eclipse, you will need to install the Flex Builder plugin. In this demonstration, I am using Flex Builder 3 with the Java Development Tools added on.

In Flex Builder create a new Java Project named Slideshow. Select the Create project from existing source option and navigate to {lcds-root}/tomcat/webapps/slideshow/WEB-INF. Choose next, and ensure that the Default output path is set to Slideshow/classes. By default, this might be set to bin-debug, and this is not appropriate for an LCDS application. The server will not know where to look for the compiled classes! Click Finish.

Initial Slideshow project structure

Open the Hibernate perspective in Flex Builder. In the Hibernate Configurations tab, right-click and select Add Configuration... to open the configuration dialog. Name the configuration slideshow-hibernate, select your project, hit Setup... for your property file and select Create new... and place it in the root of your project. Click Setup... for your configuration file and select Create new... to create an initial hibernate.cfg.xml that we will use to connect to our database for reverse engineering of the tables into Java POJOs and Hibernate mapping files. Select MySQL 5(InnoDB) as the database dialect, org.gjt.mm.mysql.Driver as the Driver class, jdbc:mysql://localhost/slideshow as your connection URL, and enter your database username/password before clicking finish. The configuration should now be available in the Hibernate Configurations tab. Open the Database, and you should see your database and the tables contained within:

Hibernate Configuration Wizard results

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<session-factory>
<property name="hibernate.connection.driver_class">org.gjt.mm.mysql.Driver</property>
<property name="hibernate.connection.password">mypassword</property>
<property name="hibernate.connection.url">jdbc:mysql://localhost/slideshow</property>
<property name="hibernate.connection.username">root</property>
<property name="hibernate.dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
</session-factory>
</hibernate-configuration>

The resulting hibernate.cfg.xml should look like the above.

From the Run menu, select Hibernate Code Generation, and select Open Hibernate Code Generation Dialog... to create a reverse engineering configuration to generate our POJOs and Hibernate mapping files. Click the "New launch configuration" icon and rename the configuration "slideshow-configuration". In the Console configuration dialog select our slidwshow-hibernate configuration that we created in the previous step. Brows to the src directory of our project in the Output directory selection. Click the "Reverse engineer from JDBC Connection" checkbox. Enter "slideshow.data" in the package text input area. Click the setup button for reveng.xml and choose "Create new..." and place the file in the root of our project. Move to the "Exporters Tab" and choose Domain code (.java), Hibernate XML Mappings (.hbm.xml), and Hibernate XML Configuration (.cfg.xml). Didn't we already create a hibernate.cfg.xml? Yes, but this generated version will be placed in the src directory, and will contain the appropriate references to our mapping files. The first configuration is simply to tell the generator where to connect to our database. Switch to the Refresh tab and select "Refresh resources upon completion." so that our project structure will be refreshed after we click Run. Click Run.

From the Package Explorer tab, you will see that our .java classes have been generated, as well as their appropriate sidecar .hbm.xml files. The album class containes a Set called images, and the Image class contains an Album property. Take a look at the .hbm.xml files and take note of the defined relationships. The Hibernate reverse engineering has successfully traversed our database structure and created the appropriate relationsips!

It is worth noting that the Hibernate reverse engineering tools could concievably take care of the following steps. This is on my list of things to explore, but for now we will define our LCDS destinations and Actionscript value objects the old fashioned way. By hand. Yick.

As a final step we will add cascading and a retrieve all query to our album.hbm.xml like this:

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
<!-- Generated Aug 17, 2008 1:02:52 PM by Hibernate Tools 3.2.2.GA -->
<hibernate-mapping>
<class name="slideshow.data.Album" table="album" catalog="slideshow">
<id name="id" type="java.lang.Integer">
<column name="id" />
<generator class="identity" />
</id>
<property name="name" type="string">
<column name="name" length="256" />
</property>
<property name="description" type="string">
<column name="description" length="1024" />
</property>
<property name="isActive" type="java.lang.Boolean">
<column name="is_active" />
</property>
<property name="displayOrder" type="int">
<column name="display_order" not-null="true" />
</property>
<property name="updatedOn" type="timestamp">
<column name="updated_on" length="19" />
</property>
<property name="createdOn" type="timestamp">
<column name="created_on" length="19" />
</property>
<property name="mp3Url" type="string">
<column name="mp3_url" length="256" />
</property>
<set name="images" inverse="true" cascade="all">
<key>
<column name="album_id" not-null="true" />
</key>
<one-to-many class="slideshow.data.Image" />
</set>
</class>
<query name="all.albums">from Album</query>
</hibernate-mapping>

These two changes are the only changes neccessary. The generator has taken care of everything else.

Defining the LCDS Destinations

Now that we have set up the server side Java application, it is neccessary to create destinations for our client to communicate with. In the flex directory of our project, there are a number of xml configuration files. The default configuration will be sufficient in all cases except for the data-management-config.xml. This is the file that will contain our destinations.

This is the basic configuration for our destinations defining the relationships between our objects:

The Client

The client will be an Adobe AIR client. Why AIR? Well, for this particular demonstration, an image gallery, it is neccesary to pull images from the users harddrive and upload them as bytearrays to the server for storage in the database. With the current Flash Player Runtime (9 at the time of this writing) you cannot do this due to security sandbox restrictions. The good news is that this particular restriction is being relaxed in Flash Player 10, but for now it is not possible outside of AIR, or with roundtrip trickery via a web service.

"But wait, I thought we were applying KISS principles? Cairngorm AND PureMVC? What's up with that?"

Cairngorm is a nice framework, but PureMVC provides robust control over your view layer that Cairngorm lacks. Cairngorm's ServiceLocator (or EnterpriseServiceLocator in this case) is extremely convenient and provides easy access to our data services. In the context of this application, the ServiceLocator is the only piece of Cairngorm we are going to use. When I originally built this application, it was actually as a means to learn about the Cairngorm framework, but I found myself missing PureMVC the entire time I was working with it. So I am taking this opportunity to demonstrate the combination of these two frameworks as a means to create a robust MVC driven LCDS connected application.

Flex Project Structure

The project structure is typical PureMVC, with model, view and controller folders added under the slideshow package. The focus of this tutorial is the server side configuration. I'm not going to go into detail about constructing the client application, but I am going to summarize what the classes do:

Slideshow.mxml
This is our main application window. It calls a reference to the SlideshowServiceLocator component to initialize the EnterpriseServiceLocator singleton class. It also contains references to our two Value Object classes. This is neccesary to send typed objects back and forth over the wire. Until the VOs are called, they will be transfered as generic objects. Slideshow.mxml also initializes the PureMVC ApplicationFacade.

SlideshowServiceLocator.mxml
This component is an extension of the Cairngorm Enterpriese EnterpriseServiceLocator class. This is the place where you define your channels and services to facilitate communication with the LCDS rtmp end-point. If you want to change the end-point from localhost to reflect your personal configuration or a remote server, this is the place to do it.

*Command.as
These classes initialize the PureMVC proxy and view components.

*Events.as
These are custom events. They are very simple extensions of the Event class, but they carry references to value objects to make life easier.

*VO.as
The value objects mirror the POJO objects on our server side. They are [Managed], meaning they are monitored for changes by LCDS. Managed classes are [Bindable] by default. There is also additional metadata referencing the remote class so that our objects will be stongly typed over the wire.

ApplicationMediator.as
This is the mediator for the main application window. It registers the mediators that monitor and control the sub-components of the application.

*Mediator.as
The mediators monitor for changes in our view components and respond to notifications from commands, proxies, and other mediators. In this application, there are not many notifications being sent around, but I left the methods in place for future expansion.

AlbumListProxy.as
This proxy is where we grab the list of albums from the server. This proxy grabs an instance of the EnterpriseServiceLocator and calls the "albums.all" query to fill the data property of the proxy. When the list of albums is retrieved, we assign each album an individual proxy to lord over it.

AlbumProxy.as
AlbumProxy contains methods to manipulate albums. Add images, delete images, delete the album, etc. While it is wholly possible to place these methods inside the actual view components (ServiceLocator makes it very easy), it is better form to seperate the manipulation of our data model from our view layer. View components should be stupid, ignorant of anything outside of displaying the data passed to them. With this application, I actually did data manipulation in the view components, but then refactored to follow the proxied data methodology. This is how I approach these things a lot of the times. Create a monolithic view component, break it into smaller components, mediate those deserving of such treatment, and finally proxy the data manipulation methods contained in the objects. I've found that as I gain experience, I am able to plan the broader structure without having to use this approach, but "make it work, then make it work better" is still a valid approach.