The Integrallis Blog :

Using GORM to Boost Legacy Spring Applications

2009-08-31T16:54:46-04:00

Using GORM with your Spring application can increase the productivity and readability of your code

Groovy and Grails has stormed the Java world as the new way to create reliable Web 2.0 applications in a concise and fast manner. The ability to go from the start of a project to the end, especially for a smaller demo, is exponentially faster. This is due to the many features of Grails. Out of the box applications are easier to build, create, test, and deploy because of the convention over configuration methodology. In addition Grails is written in Groovy, a dynamic language that can run on the JVM and interact as if they were Java classes. Groovy gives the power to write dynamic code with power and features that are normally unavailable in Java. Possibly the best example of this power in Groovy and Grails is the creation of the Grails Object Relational Mapper (GORM).

However, we can’t all just go to our managers and say “Hey, let’s rewrite this entire application in Grails”. We would more than likely get laughed out the door. At many companies it also isn’t feasible to ask for an entire framework shift. However, most of us can request “small changes”, especially if they help save time.

With Spring 2.0 and above we can create Spring beans out of Groovy objects. This gives us a nice ability to use Groovy nomenclature in our Spring code (e.g. the Meta Object Programming (MOP), cleaner syntax, etc). However, what we do not get with straight Groovy is a better way to interact with the database. For that we need the power of GORM. With Grails 1.1 that has become significantly easier.

Why Do I Want To Use GORM?

You may be familiar with Hibernate and wonder why you should bother with GORM. Hibernate is a GREAT ORM, and the framework has been developed steadily since its inception. While Spring’s wrapping of Hibernate has made it easier to interact with the database, it is still missing the readability and ease of use that most modern developers want. The following example demonstrates how GORM brings simplicity to Hibernate code. (Please note that although GORM derives from Hibernate any mention of Hibernate here will specifically be in reference to the pure Java Hibernate form.)

This example starts by performing a simple query to retrieve items from the Todo table in the database where name and description matched some given text. When using Spring’s Hibernate Template, the code would look something like this:

public List find(final String name, final String desc) {
final String hqlQuery =         
    "select t from Todo t where t.name = :name and t.description = :desc";
    return (List) getHibernateTemplate().execute(new HibernateCallback() {
    public Object doInHibernate(Session session) throws HibernateException {
        Query query = session.createQuery(hqlQuery);      
        query.setString("name", name);
        query.setString("desc", desc);
        return query.list();
    }
});    
}

Listing NUS-1

While this code does the job, something more readable would not only make it easier for everyone to understand, but would also cut down on time and errors.

Now if we were using Java Persistence API (JPA) supported queries we could make the code in Listing NUS-1 a bit simpler as shown in Listing NUS-2.

@PersistenceContext
EntityManager manager;

public List find(final String name, final String desc) {
    final String hqlQuery =         
        "select t from Todo t \
        where t.name = :name and t.decscription = :desc";
    return manager.createQuery(hqlQuery)
        .setParameter(“name”, name)
        .setParameter(“desc”, desc)
        .returnResultList();
}

Listing NUS-2

This is more concise and fairly readable, but several queries in a row would require repeating the same block of code many times with slight alterations and would increase our time and effort to do so. You may be asking yourself what is the problem with this? After all I am sure many of you have witten similar or even more verbose code before. The problem lies in the fact that code should be easily readable. As good developers we want to concern ourselves with the business logic, using the write tools. We shouldn’t have to spend too much of our time deciphering easy parts of the code, and queries to the database are often just that. Using GORM helps us to solve that problem, and here’s how.

Let’s take what that code is doing and write it in English. The code is wanting to query the Todo table to find all by name and description. Well how do we write that out? How about this:

Todo.findAllByNameAndDesc(name, desc)

That is simple, concise, and in GORM that line is actual code. This begins to show the ease of using GORM over Hibernate and we will expand on that concept when using Criteria queries later. But first, let’s see how to use GORM in our Spring application. ### Injecting GORM The interesting thing about writing an article on Using GORM with Spring is that there is barely enough setup required to fill a blog entry, let alone an entire article. In fact, you could almost Twitter the entire extra XML needed; however, for the purpose of learning we are going to go into a bit more detail. We will show not only how to set up GORM in Spring but also various options when using Spring. This will require configuring the Spring beans, installing the right JARs, and, most importantly, understanding the various ways to use GORM in your application. ### Configuring the Spring Beans We are going to go over in this section the necessary modifications to the spring files needed for using GORM with Spring. The modifications here will be to your bean configurations and are independent of whether you are using Spring in web environment or a standalone application. That being said of course if you were to be using Spring in a web environment no modifications are needed for the web specific files (like web.xml) The first thing to do is to add an XML namespace to your bean configuration. This one is specifically for GORM: xmlns:gorm="http://grails.org/schema/gorm" Once the namespace is set you will be able to use the GORM Session Factory instead of the Hibernate Session Factory. Listing NUS-3 is an example of the GORM bean definition that would go into your bean definition file..

Listing NUS-3

Luckily, this listing isn't too complicated. Often times with Spring beans one has to define the classes being used; however, with the use of XML namespaces that is not necessary Spring is aware based on the namespace used With that being said Listing NUS-3 serves the same purpose as your standard Hibernate definitions usually do in Spring and that is to define the Session Factory. In fact, most of the items defined will be similar to Hibernate Session Factory listings.

Line 1 is the name space reference to the GORM Session Factory, which is fairly standard stuff. The rest really is general Hibernate type configurations that are specific to GORM. Line 2 is used to specify where your domain objects exist. Remember, with Hibernate you have to define your domain objects. There are basically two ways to do this: one is to define a directory full of hibernate XML mapping files, the other is to specify a directory of domain objects. Line 3, data-source-ref, references a data source that you have defined in Spring. This can be a Java Naming and Directory Interface (JNDI) data source, in memory data source or a more database specific data source. Line 4, message-source-ref, is specific to GORM itself. GORM allows one to define validation constraints in its domain, these constraints then print out messages via a message resource bundle. In Grails this message resource bundle is a predefined name and area, with GORM you will have to specify that item yourself. In GORM these validators are in a specific place with a specific name, but with Spring one can customize the location and name of this resource bundle. On line 5 we start to define the Hibernate properties. If you were using Grails these items would be specified inside your DataSource.groovy file and if you were using JPA would be in the persistence.xml file.

JAR Files Needed

In addition to defining the GORM Session Factory we will also need a few of the Grails JAR files to make this work. Only three jars from Grails are needed and can be included either manually or via your Ivy/Maven configurations:

grails-bootstrap 1.1
grails-gorm 1.1
grails-web 1.1

Introducing Drools 5

2009-08-19T19:03:02-04:00

A Java Rule Engine for the rest of us

For most Java developers the idea of using a Rule Engine evokes thoughts of vendors in suits selling their bosses a complex and expensive piece of software they don’t need and the introduction of something completely foreign and intrusive to their code base. Drools 5 (http://www.jboss.org/drools/) aims to change this perception by bridging the gap between the Java developer and world of Rule-based systems. The Quick and Dirty on Rule Engines

The simplest explanation of what a rule engine is that is a very efficient pattern matcher. It matches data, referred to as “facts” against rules. Rules are simple if-then constructs that operate on the matched data. For example, imagine an example application in which the data is a loan application containing the credit score for the loan applicant. A rule could express a credit score requirement for a loan such as:

“A loan application for ACME loans for which the loan applicant has a credit score lower than 680 will be rejected”

For the context of the this example assume that the following Java classes exist:

Mortgage: Represents a loan product belonging to a lender. It contains amongst other data, the name of the lender providing the loan.
LoanApplication: Represents an application for a specific loan product. It contains information specific to the applicant such as the credit score and the lender associated with the application.
RejectionNotice: Represents a communication to the applicant that the application has been rejected

rule "LowCreditScoreRejection"
dialect "java"
    when
        mortgage:Mortgage(
            lender:lenderName == "ACME"
        )
        application:LoanApplication(
            lender == mortgage.lenderName,
            score:creditScore < 680
        )
    then
        application.reject("the score " + score + " is too low. \n" +
                           "A credit score of at least 680 is required");
        insert(new RejectionNotice(application));
end

Listing SAM-1 A simple rule

The rule named “LowCreditScoreRejection” is a typical Drools Rule Language (DRL) rule. It has two parts; the “when” part, also known as the “predicate”, “premise”, “condition” or simply as the “Left-hand side” (LHS for short) and the “then” part or “consequence”, “action”, “conclusion” or “Right-hand side” (RHS)

The Rule Condition

The “when” part or rule condition determines the patterns to be matched. That is, the types and characteristics of the objects that will activate the rule. In the example shown, we are looking to match two objects, an object of type Mortgage and an object of type LoanApplication. The “mortage” object must have a lenderName (mortgage.getLender) equals to “ACME” and the “application” must have a matching lender name and a creditScore (application.getCreditScore) that is less than 680.

As you can see this rule only gets evaluated if there are two objects of the aforementioned types present and it is only activated if those two objects properties match the conditions in parenthesis.

An observant Java developer will notice that the rule sort of looks like Java code but not quite. The when part list the classes of the objects that must be present and the values of the properties of those instances needed to activate the rule. The when part is purely a pattern matching expression using first order logic. You can think of the when part as the “where” clause in a SQL statement. Just like in a SQL statement you can create aliases for the objects being matches (and their properties). In the “LowCreditScoreRejection” rule we have three aliases “mortgage”, “lender”, “application” and “score”. Once you have aliased a matched object that object can be used somewhere else in the rule condition and also in the rule consequence.

The Rule Consequence

We learned that the rule condition part of the rule determines what pattern of objects that will activate the rule. The “then” part or rule consequence is what happens when the conditions set forth in the “when” part are met. In Drools the consequence is simply a block of Java code. In the “LowCreditScoreRejection” rule example there are two things happening in the “then” part. First we are calling the “reject” method on the application and passing a message telling them why the application is being rejected (notice the use of the alias “score”). Next and last we are creating a new object of type RejectionNotice, passing the application object in the constructor and then passing the newly created object to the insert method. The insert method is a Drools working memory method that tells the rule engine that there is a new object that should be considered when evaluating the rules. In this case the expectation is that there will be another rule that has a condition expecting objects of type RejectionNotice and that will act upon them. The Rule Engine

From the simple example of the “LowCreditScoreRejection” rule we see that a rule engine is a system that matches facts (our data objects) against rules. The rules are then used to infer conclusions about the data. In the example, the conclusions inferred were rejection of the loan application and the creation of the rejection notice. This type of system is what is referred to as a data-driven forward chaining reasoning system. At the heart of the system is an “inference engine”; the component that does the pattern matching, activates the rules and determines how to execute the activated rules. This process is typically referred to as truth maintenance. Under the covers Drools uses a custom version of the popular Rete algorithm (see http://en.wikipedia.org/wiki/Rete_algorithm). As we can see the “forward chaining” process starts with the available facts and uses the rules to infer more facts (such as RejectionNotice) until a desired goal as been reached (determining whether a loan application is approved or rejected and communicating the rejections). Main Drools Classes

The rules like “LowCreditScoreRejection” rule are contained in DRL files (files with the extension .drl) that comply with Drools native rule language syntax. To use the created rules in a Java application you must:

KnowledgeBuilder: A knowledge builder is the class that knows how to load and process DRL files. The impact of parsing and building in memory objects from the DRL file happens at this point. An instance of a knowledge builder can be obtained from the KnowledgeBuilderFactory using the newKnowledgeBuilder() method
KnowledgePackage: A knowledge package is the result of processing a DRL file; a serializable object. The knowledge builder has a getKnowledgePackages() that returns a collection of knowledge packages.
KnowledgeBase: A knowledge base is where the knowledge packages are deployed to so that they can be used at runtime. The knowledge base is the object that will be used to create knowledge sessions. This knowledge base is a thread safe construct that serves as a factory of sessions.
KnowledgeSession: The knowledge session is the object used to interact with the rule engine. It is throught a session that you will make the rule engine aware of the facts (the data) that the rule engine will evaluate against the available rules. Inside the Rule Engine

Inside the rule engine, after you have inserted your facts into a knowledge session and invoked the session fireAllRules() method:

Rules are matched against the facts in the knowledge session using the pattern matcher (Rete algorithm)
The unordered list of activations (the Rules that apply based on the facts) is ordered internally (by a conflict resolver) in the session’s agenda
The first Rule in the agenda is the executed, possibly triggering steps 1 and 2 again

This loop is how a Rule Engine infers knowledge from existing facts using rules. You can see that a Rule Engine using pattern matching to reduce/transform the problem space to arrive at a set of facts that can be considered a solution to the problem at hand. Getting Started with Drools 5: Classifying you Twitter network

Rule Engine development introduces enough conceptual complexity (mainly inherited from the A.I. lingo and academia) that feels fairly unapproachable us Java developers. So, let tackle a simple but yet representative problem using Drools 5.

JSecurity Permissions in Grails

2009-03-03T20:44:40-05:00

One of the security plugins I have looked at with the most interest is the JSecurity plugin. I was attracted to the JSecurity because it seemed to provide a good mix of out of the box support but also being flexible enough for customizations.

On the surface JSecurity provides much of the normal security you'd expect from any framework. There is out of the box support for login/logout authentication, support for role based lock downs, and finally even the ability to create permission based security. It's the last one I wanted to write about.

Understanding how to do normal authentication with JSecurity and implementing roles is pretty straight forward and the documentation on the grails wiki found here. Where I believe the documentation lacks a bit on is using permissions. That being said, the documentation on the wiki is very good at understanding WHAT permissions are and creating custom ones but not necessarily how to create basic ones in the first place.

I am going to assume you have all used JSecurity or can go to the previous URL and read about it and will discuss implementing permissions for JSecurity. Sometimes knowing when to use permissions can be rather complex. And sometimes justifiably so, the way to use permissions (and of course there are many ways to use them) is when you keep needing to fine tune access to a particular source on a per user basis. Take a typical web application with a user list. We may want to allow someone to have read access to the list, another to have read and write, and another to have read, write, delete. To perform this check with roles we would basically have to have 3 different roles and assign them when needed. The problem with this solution is it basically gets messy fast especially if you have quite a bit of resources you want to lock down in this way. Permissions are designed to solve this problem exactly, by allowing a finer grain access on a resource. Let's dive into how to create permissions in JSecurity.

How do we perform this in Grails with JSecurity? JSecurity essentially has three tables that handle permissioning: JsecPermission, JsecUSerPermissionRel, and JsecUserRoleRel. We will look at how these tables are going to help us create and lock down pages on a per user basis.

Let's first discuss how JSecurity interprets permisssions to begin with. JSecurity permission is more complex than some because it does not force one to treat every resource (ie: web page, file system, specific part of the app) equally. JSecurity allows you to define what the permission resource IS in the first place. For example the permission logic for a web URL like our in example of a user page, to-do page, etc would differ from a file resource if you were creating a documentation management site. The wiki for the JSecurity shows examples of a FilePermission or a ProjectPermission, anything that implements the Permission interface. Each of these classes will have an implies() methods that actually determines HOW one is to interpret the permission. This is great because it gives the user the maximum flexibilty in determining how they want there permission applied. Now while i say that is great, let's face it most of us are going to use permissions for as I described above in Grails, to lock down a particular controller / action. The good news is out of the box Grails JSecurity plugin provides a specialized permission for controller based security. They have what is called a basic permission 'org.jsecurity.grails.JsecBasicPermission'. This permission is good for when you want to apply the concept of controller / action security. And it is this particular use case I am going to show how to use below.

To start with even though we have the permission as a resource on the class path its name needs to be stored to the database so the system can do reflection on it later. The first table we need to add to is the JsecPermission table. This table is simply going to keep a list of all the permission classes we have and the possible actions for each. So for our controller / action lockdowns we will simply add a reference to the JsecBasicPermission into the database:

Creating the Database Permission

def perm = new JsecPermission(type: 'org.jsecurity.grails.JsecBasicPermission', possibleActions: '*').save()

Now as you have noticed i have used an * for the possible actions, this is more to fill in the blanks than for anything useful. By default with the JsecBasePermission it really does not care about the actions used here. Now just because this particular permission is not using possible actions does not mean that another permission in the future could use it nor does it mean it HAS to use it either. This is part of JSecurity's methodology of trying to keep maximum flexibility.

Assigning the User to the Permissions Now that we created the permission let's assign it to a user you have already created. To assign it you basically have two choices. Either assign it to a role or assign the permission directly to the user. I am going to do the latter and assign it to the user. In the following code we are taking our user and our permission and allowing the actions of delete and edit.

new JsecUserPermissionRel(
    user : user,  
    permission: perm, 
    target : 'user', 
    actions : 'delete, edit').save()

Locking Down the Resource

So now that we have the permission we are going to lock down the security for the controller, and here is where it may get a bit tricky to understand. First off remember we have not done any permissioning for create or list, so by default we do not want to do any permissioning check for those because we have not assigned any. So in our filter lets add two permissioning interceptors for delete and edit only:

user(controller: "register", action: "delete") {      
    before = { 
        accessControl { 
            permission(type: 'user', actions: actionName)
        }      
    } 
}  

user(controller: "register", action: "edit") {      
    before = {
        accessControl { 
            permission(type: 'user', actions: actionName) 
        }      
    } 
}

Now the application will check for permissions with edit and delete only, and unless you are assigned will take you to a page saying that you aren't allowed.

Now where I said it can get confusing is the naming as you go through, and this is where we harp back to saying that the permissions in JSecurity is very much user based. While this provides a huge degree of flexibility it can also cause naming you thought should go together not always go together. So take where we initially defined type in the JsecPermission table. This type was our fully qualified class type. However, the type down in the filter we define has nothing to do with the JsecPermission type. This type is instead going to relate to the target we defined in JsecUserPermissionRel. This is an important distinction to make, and one that confused me at first when using the JsecBasicPermission. The actions part, that is more self explanatory and the actions you pass in will be the actions that it will check against.

Building Tempo with Rails, Part VI

2007-12-26T12:59:47-05:00

In this installment we are going to build the Dashboard page of the Tempo application. The first incarnation of the Dashboard page will serve as the entry point/main page of the application and its main function will be to provide an interface for users to report time against a project-activity combination.

The user story that we are targeting is:

TMPO-29: “User enters Time” Business Critical [OPEN] 40 points 0% unassigned

The description above is from the Agile Project Management and Collaboration tool Caimito One. The “User enters Time” story is business critical, it is still OPEN, we have estimated 40 complexity points to it, is 0% completed and it has not been assigned to any team member (or no team member has volunteered for it!)

The description of the user story is "As a User I would like to enter time against a project and activity by providing a starting and ending time"

User Interface

Based on the story description I’ve come up with a rough sketch of what I picture the Dashboard page looking like after the first pass:

The sketch above shows 3 different areas:

Date Selection: A Calendar-style component that will enable the user to select a given (active) date to enter time
Time Entry Details: A form that will provide drop-downs for the Project, Activity, Start Time, End Time for the TimeEntry as well as a text area for a description. Optionally the user will be allowed to enter time as a number of hours to be reported against the given date (with no specific start or end times(1)).
Daily Summary: A table displaying the time entries reported for the active date.

(1) Notice that I’ve just created a new requirement that was not present in the original User Story. In our work to fulfill the main User Story we will set the stage to satisfy this new requirement but we should really create a new issue (story) to tackle that new piece of functionality (of course first we should check with the project owner and/or stakeholders)

Dashboard Controller

I started by creating the skeleton code and tests for the Dashboard Controller:

script/generate rspec_controller dashboard   
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/dashboard
      exists  spec/controllers/
      exists  spec/helpers/
      create  spec/views/dashboard
      create  spec/controllers/dashboard_controller_spec.rb
      create  spec/helpers/dashboard_helper_spec.rb
      create  app/controllers/dashboard_controller.rb
      create  app/helpers/dashboard_helper.rb

Since we want the dashboard to be the default page for our application we can modify the config/routes.rb accordingly:

map.connect '', :controller => "dashboard", :action => "index"

With the skeleton in place I can now do a little planning about what I need to build.

A bit of Design

Here's what I know about the Dashboard page so far:

The Dashboard page can only be shown if there is a user logged in. (done, taken care by the restful authentication plug-in)
When the user first navigates to the Dashboard page, the current date should be shown in the calendar date picker and on the “blog” style display on the time entry form
The Daily Work table should show all TimeEntries for the current user for the selected date
When the user selects a new date form the calendar date picker the "current date" (the date which under the times entered will be reported) should change.

Create the Views

Let’s start by creating an index.rhtml template in the Views/dashboard directory. The index template will render three partials; one for a blog-style date, the TimeEntry form and one for the Daily Work table. The partials will be _current_date.rhtml, _form.rhtml and _time_entries.rhtml respectively.

views/dashboard/index.rhtml

The listing below shows the contents for index.rhtml. I used some of the CSS styles provided by ActiveScaffold to keep the look and feel consistent.


    
    <% form_tag :action => 'create' do %>
      <%= render :partial => "current_date" %>
      
        <%= render :partial => 'form' %>
        
          <%= submit_tag "Create" %>
        
      
    <% end %>
  






  <%= render :partial => "time_entries" %>

The index.rhtml view renders a form (which body is contained in the _form.rhtml partial), the current date which is render by the partial _current_date.rhtml. Finally at the bottom we have a section that contains the daily work table summary which is rendered by the _time_entries.rhtml partial. Let's take a look at each one of those partials next:

views/dashboard/_current_date.rhtml

The idea here is to render a blog style data block as shown below:

To render the blog style date I have a CSS snippet that I use to style a partial containing the current date. The partial _current_date.rhtml is shown below:


  
    <%= "#{Time::RFC2822_MONTH_NAME[@current_date.month-1]}" %>
  
  
    <%= "#{@current_date.day}" %>
  
  
    <%= "#{@current_date.year}" %>

Notice that I use an instance variable current_date that will be set in the index method of the dashboard controller if it cannot be retrieved from the session:

  def index
    unless session[:current_date] 
      session[:current_date] = Time.today  
    end
    @current_date = session[:current_date]
  end

In the controller the method to render the partial and update the instance and the session variable follows:

  def current_date
    session[:current_date] = Time.parse(params[:current_date])
    @current_date = session[:current_date]
    render :partial => 'current_date'
  end

The CSS code for the dateblock is shown below (I've found it on a CSS site but I can't remember where):

/*-------------------------------------------------
DATE BLOCK
-------------------------------------------------*/
.dateblock {
  text-align: center;
  width: 50px;
  font-family: sans-serif;
  border: solid 1px black;
  padding-top: 5px;
  color: white;
  background-color:black;
  margin-top: 10px;
  margin-bottom: 10px;
  line-height: 1.22em;
  font-family: sans-serif;
}

.dateblock_month {
  font-size: 12px;
}

.dateblock_day {
  font-size: 26px;
  position: relative;
  top: -2px; 
}

.dateblock_year {
  font-size: 12px;
  position: relative;
  top: -2px;
}

views/_time_entries.rhtml

For the Daily Work table showing all TimeEntries for the current user for the selected date we use the _time_entries.rhtml partial. This partial makes use of ActiveScaffold's ability to embed a scaffold in another controller, or view. To accomplish this we use the

render :activescaffold => 'timeentries'

which will call the render_component passing a specific set of conditions (to be appended to the SQL select statement) and a custom label for the scaffold table:


<%= render :active_scaffold => 'time_entries', 
           :conditions => 
             ["user_id = ? AND YEAR(start) = ? AND MONTH(start) = ? AND DAY(start) = ?",
              @current_user.id, @current_date.year, @current_date.month, @current_date.mday], 
           :label => 
             "Time Entries for #{Time::RFC2822_DAY_NAME[@current_date.wday]}, #{Time::RFC2822_MONTH_NAME[@current_date.month-1]} #{@current_date.day} #{@current_date.year}" %>

In the controller we need to modify the index method to also filter the collection of TimeEntry objects retrieved:

  def index
    unless session[:current_date] 
      session[:current_date] = Time.today  
    end
    @current_date = session[:current_date]
    @time_entries = TimeEntry.find(:all, :conditions => ["user_id = ? AND YEAR(start) = ? AND MONTH(start) = ? AND DAY(start) = ?", @current_user.id, @current_date.year, @current_date.month, @current_date.mday])
  end

We also need a time_entries method to render the TimeEntry(s) based on the current_date in the session:

  def time_entries
    session[:current_date] = Time.parse(params[:current_date])
    @current_date = session[:current_date]
    render :partial => 'time_entries'
  end

The daily work table should now display all the TimeEntry(s) for the current/selected date:

Building Tempo with Rails, Part V

2007-12-06T20:36:09-05:00

This installment was supposed to be about building the Dashboard page of the Tempo application. Instead, I'm addressing some bugs reported by readers.

Fixing Bugs TDD-style

An observant reader pointed out that one of the tests for the TimeEntry class broke when testing using a date range across a month boundary.

The offending code is shown below:

  def split!
    remaining_time_entries = []
    if needs_splitting
      # save the original end time
      original_end = self.end 
      # first change the current TimeEntry to the end_of_day of the start day
      self.end = self.start.change(:hour => 23, :min => 59, :sec => 59)
      (self.start.day+1..original_end.day).each do |day|
        time_entry = self.clone
        time_entry.start = time_entry.start.change(:mday => day).beginning_of_day
        if day == original_end.day
          time_entry.end = original_end
        else
          time_entry.end = time_entry.start.change(:hour => 23, :min => 59, :sec => 59)
        end
        remaining_time_entries << time_entry
      end   
    end
    remaining_time_entries
  end

Even though the code above was created in a TDD fashion and several of the tests created exercised the code, the tests failed to cover all of the possible cases.

The lesson here is that when dealing with date ranges, you should test across months and year boundaries. The code above only works when the two datetimes are in the same month and year which is a critical flaw. The code uses the day method to loop form the start day to the end day of the range. This will obviously break across months and of course across years.

One good thing about the test above was (as some might argue whether this is a good thing or not) is that I used a date range that started on the current date and time. In a continuous integration scenario this broken test would had revealed itself in the hourly build.

I've also made the same mistake (of using the day method) to check if a range of dates needed splitting, here's the original code:

def needs_splitting
  self.start.day < self.end.day
end

First, let's prove that the code is indeed broken. To accomplish this I've written a test that crosses a month boundary:

it "should know how to split a time entry across multiple days over a month boundary" do
  time_entry = create_time_entry
  time_entry.start = Time.local(2007,"nov",30,23,0,0)
  time_entry.end = 5.hours.since(time_entry.start)
  entries = time_entry.split!
  entries.should_not be_empty
  total = 0.0
  entries.inject(0) {|total, e| total += e.total_hours}
  total += time_entry.total_hours
  total.should eql(5.0)
  time_entry.needs_splitting.should_not be_true
end

The above test fails with the existing code. Now we can refactor the code to pass the test.

  def needs_splitting    
    (self.start.year != self.end.year) ||
    (self.start.month != self.end.month) ||
    (self.start.day != self.end.day) 
  end

  def split!
    remaining_time_entries = []
    if needs_splitting
      # save the original end time
      original_end = self.end 
      # first change the current TimeEntry to the end_of_day of the start day
      self.end = end_of_day(self.start)
      days = ((original_end - self.start) / 86400).ceil.to_i  
      (1..days).each do |day|
        time_entry = self.clone
        time_entry.start = time_entry.start.advance(:days => day).beginning_of_day
        time_entry.end = time_entry.end.advance(:days => day)
        if same_day(time_entry.end, original_end)
          time_entry.end = time_entry.end.change(:hour => original_end.hour, :min => original_end.min, :sec => original_end.sec)   
        else
          time_entry.end = end_of_day(time_entry.start)
        end
        remaining_time_entries << time_entry
      end   
    end
    remaining_time_entries
  end

The needs_splitting method now checks the year, month and day. The split! method now finds the total number of whole days (plus one) in the datetime range. It then creates new TimeEntry(s) for each of the whole days (24 hours each) and a partial one of the last day on the range. To advance each one of the days I use the advance method (see Rails extensions to the Time class).

Building Tempo with Rails, Part IV

2007-11-12T09:45:27-05:00

In the last three installments of this series we concentrated our efforts on building the most important entities of the Tempo domain. If you are anything like me you need visual feedback to truly get a sense of progress, if anything for the psychological effect of seeing something working (other than on the command line)

Before we jump into building the visual aspects of the application we should finish configuring the restful_authentication system we installed in installment #1.

Configuring Restful Authentication

The first step is to protect all controllers in our application by applying a before filter that will trigger the authentication logic. In Rails the ApplicationController is the ideal place to do so since is the default parent class for all controllers in an application:

class ApplicationController < ActionController::Base
  include AuthenticatedSystem

  session :session_key => '_tempo_session_id'

  before_filter :login_required
end

In the file application.rb we include the AuthenticatedSystem and apply the before filter :login_required which will cascade down to any new controllers we create.

The restful_authentication plugin creates two controllers, the UsersController; a typical CRUD controller for User objects and the SessionsController which is the controller responsible the login/session management logic.

Taking a peek at the Session controller we see that it is set to skip the :login_required filter:

class SessionsController < ApplicationController

  skip_before_filter :login_required

  ...

end

In the Views/sessions directory we customize the new session view (a.k.a the login screen):


  
    Welcome to Tempo, please log in
    
      <% form_tag session_path do -%>
        Username:
        <%= text_field_tag 'login' %>

        Password:
        
          <%= password_field_tag 'password' %>
          (I forgot my password/username)
        

        <%= check_box_tag 'remember_me' %>Remember me on this computer

        <%= submit_tag 'Log in' %>
      <% end -%>

Permanent Scaffolding?

To give us a jump start in the right direction I'm going to make use of a Rails scaffolding plug-in that should allow us to get some fairly decent web pages up and running in no time. There seems to be two contenders in the area of "permanent" Rails scaffolding plugins, one is the Streamlined Framework produced by the brilliant folks at Relevance the other one is ActiveScaffold created by the same team that built the now deprecated AjaxScaffold.

Both frameworks attempt to provide you with a way to generate ActiveRecord-driven scaffolding screens that are configurable and flexible enough that you theoretically won't have to later tear them down to build the "real" pages of you application. I've briefly looked at both frameworks previously and they both seem fairly even in terms of features. So just for the sake of trying something new I'm gonna use ActiveScaffold for the Tempo time tracking application.

ActiveScaffold

The ActiveScaffold website has quite a bit of documentation that should help you get started. I in particular found their "How to Approach Active Scaffold" article useful in understanding where it would be a good idea to use the framework.

To get started with ActiveScaffold in the Tempo project you'll need to first install the plug-in using Piston:

piston import http://activescaffold.googlecode.com/svn/tags/active_scaffold vendor/plugins/active_scaffold
Exported r633 from 'http://activescaffold.googlecode.com/svn/tags/active_scaffold' to 'vendor/plugins/active_scaffold'

Once you have installed the plug-in all that you need to do to enable the scaffolding for one of you model objects is to add a minimal amount of code to your controllers:

class UsersController < ApplicationController 
  active_scaffold :user
end

In your application layout head section you also need to include:

<%= javascript_include_tag :defaults %>
<%= active_scaffold_includes %>

That will give you the basic ActiveScaffold CRUD functionality.

Building Tempo with Rails, Part III

2007-10-31T12:21:41-04:00

Now that we have a basic understanding of BDD with RSpec let's pick a business critical user story and build it from tests outwards. With Tempo being a time tracking system the most crucial story should be a "User enters Time".

TimeEntry

At the core of this story is the model class TimeEntry. In Tempo we want users to be able to enter time by:

a) picking a beginning time an an end time for a given date
b) picking a beginning date-time and an end date-time

For billing purposes it is usually convenient to split the hours in a range of date-times into chunks of hours per day (for the ranges that span over multiple days). The way I envision these two entry methods are:

a) a simple page that defaults to the current date and that allows the user to pick two times for the given day along with other information required (project, activity, etc.)
b) a page with two date/time pickers that enables the user to pick a range (or some fancier UI control if I can find one)

In the spirit of TDD let's start with the skeleton RSpec specification for TimeEntry. In the spec/models directory of the application create the Ruby file time_entry_spec.rb:

describe TimeEntry do

  before do
    @time_entry = TimeEntry.new
  end

  it "should be invalid without an associated User" do
  end

  it "should be invalid without an associated Project" do
  end

  it "should be invalid without an associated Project Activity" do
  end

  it "should know that it needs to be split across days" do
  end

  it "should know how to split a time entry across multiple days" do
  end

  it "should not have a value higher than 24 hours" do
  end

end

Notice that I've added an expectation that a given time entry should know that it needs to be split across multiple days and it also should know how to perform this split.

If I run the tests now they should obviously fail. We don't even have a TimeEntry class in place:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
/.../lib/active_support/dependencies.rb:266:in `load_missing_constant': uninitialized constant TimeEntry (NameError)

Let's get pass that one problem and create the model:

script/generate rspec_model TimeEntry
      exists  app/models/
      exists  spec/models/
      exists  spec/fixtures/
      create  app/models/time_entry.rb
      create  spec/fixtures/time_entries.yml
overwrite spec/models/time_entry_spec.rb? [Ynaqd] n
        skip  spec/models/time_entry_spec.rb
      exists  db/migrate
      create  db/migrate/004_create_time_entries.rb
/>

Notice that the generate task will try to overwrite the spec we just wrote so answer NO (n) to the overwrite question as shown above. Let's add the basic fields we would expect to find in our TimeEntry class/table:

class CreateTimeEntries < ActiveRecord::Migration
  def self.up
    create_table :time_entries do |t|
      t.column :user_id, :integer
      t.column :project_id, :integer 
      t.column :projects_activity_id, :integer
      t.column :start, :datetime
      t.column :end, :datetime
      t.column :hours, :float
      t.column :comment, :string 
    end
  end

  def self.down
    drop_table :time_entries
  end
end

Run the migration to get the table created:

rake db:migrate
(in /Users/bsbodden/Documents/projects/tempo)
== CreateTimeEntries: migrating ===============================================
-- create_table(:time_entries)
   -> 0.0414s
== CreateTimeEntries: migrated (0.0416s) ======================================

If we run the tests, they all pass now, that's not good, not quite TDD, so let's add some substance and break things as they should:

Let's start with the easy stuff:

  before do
    @time_entry = TimeEntry.new
    @user = User.new
  end

  it "should be invalid without an associated User" do
    @time_entry.should_not be_valid
    @time_entry.errors.on(:user).should eql("must have an associated user")
    @time_entry.user = @user
    @time_entry.should be_valid
  end

Run the tests again and we now have our first 'expected' failure:

1)
'TimeEntry should be invalid without an associated User' FAILED
expected valid? to return false, got true
./spec/models/time_entry_spec.rb:14:

Finished in 0.06691 seconds

8 examples, 1 failure

As we learned in part II, to pass this test we need a one liner to add an ActiveRecord validation:

class TimeEntry < ActiveRecord::Base
  has_one :user

  validates_presence_of :user, :message => 'must have an associated user'
end

Test again to confirm that the validation test passes:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
........

Finished in 0.071294 seconds

8 examples, 0 failures

Next one down the line is the test for an associated project:

  before do
    @time_entry = TimeEntry.new
    @user = User.new
    @project = Project.new
  end

  it "should be invalid without an associated Project" do
    @time_entry.should_not be_valid
    @time_entry.errors.on(:project).should eql('must have an associated project')
    @time_entry.project = @project
    @time_entry.should be_valid
  end

Running the test again should confirm that we do not have a Project model yet:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
..FFFFFF

1)
NameError in 'TimeEntry should not have a value higher than 24 hours if expressed as a single hour value'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

2)
NameError in 'TimeEntry should be broken into two or more TimeEntry instances if it date-time range spans over multiple days'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

3)
NameError in 'TimeEntry should either consist of a date-time range or a single hour value'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

4)
NameError in 'TimeEntry should be invalid without an associated Project Activity'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

5)
NameError in 'TimeEntry should be invalid without an associated Project'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

6)
NameError in 'TimeEntry should be invalid without an associated User'
uninitialized constant Project
./spec/models/time_entry_spec.rb:12:

Finished in 0.121636 seconds

8 examples, 6 failures

Add the Project model to the mix using the rake task:

script/generate rspec_model Project  
      exists  app/models/
      exists  spec/models/
      exists  spec/fixtures/
      create  app/models/project.rb
      create  spec/fixtures/projects.yml
      create  spec/models/project_spec.rb
      exists  db/migrate
      create  db/migrate/005_create_projects.rb

Modify the migration to add the basic fields expected in a Project:

class CreateProjects < ActiveRecord::Migration
  def self.up
    create_table :projects do |t|
      t.column :name, :string
      t.column :description, :string
      t.column :owner_id, :integer
    end
  end

  def self.down
    drop_table :projects
  end
end

and run the migration:

rake db:migrate
(in /Users/bsbodden/Documents/projects/tempo)
== CreateProjects: migrating ==================================================
-- create_table(:projects)
   -> 0.0377s
== CreateProjects: migrated (0.0380s) =========================================

Let's test again with the Project model in place:

/> rake spec
(in /Users/bsbodden/Documents/projects/tempo)
......F..

1)
'TimeEntry should be invalid without an associated Project' FAILED
expected "must have an associated project", got nil (using .eql?)
./spec/models/time_entry_spec.rb:24:

Finished in 0.081038 seconds

9 examples, 1 failure

Great, now we broke what we wanted to break ;-)

Let's now add the validations for project:

class TimeEntry < ActiveRecord::Base
  has_one :user
  has_one :project

  validates_presence_of :user, :message => 'must have an associated user'
  validates_presence_of :project, :message => 'must have an associated project'
end

Let's test one more time:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
......FF.

1)
'TimeEntry should be invalid without an associated Project' FAILED
expected valid? to return true, got false
./spec/models/time_entry_spec.rb:26:

2)
'TimeEntry should be invalid without an associated User' FAILED
expected valid? to return true, got false
./spec/models/time_entry_spec.rb:19:

Finished in 0.083707 seconds

9 examples, 2 failures

Let's fix our problems by adding a module with a helper create method for TimeEntries and we'll just nil the associations that we are looking to test:

module TimeEntrySpecHelperMethods
  def create_time_entry(options = {})
    @user = User.new
    @project = Project.new
    TimeEntry.create({ :user => @user, :project => @project }.merge(options))
  end
end

describe TimeEntry do

  include TimeEntrySpecHelperMethods

  it "should be invalid without an associated User" do
    time_entry = create_time_entry(:user => nil)
    time_entry.should_not be_valid
    time_entry.errors.on(:user).should eql('must have an associated user')
    time_entry.user = @user
    time_entry.should be_valid
  end

  it "should be invalid without an associated Project" do
    time_entry = create_time_entry(:project => nil)
    time_entry.should_not be_valid
    time_entry.errors.on(:project).should eql('must have an associated project')
    time_entry.project = @project
    time_entry.should be_valid
  end

Pending Tests in RSpec

What do you know! it always helps to have an expert near by, Joe O'brien from the EdgeCase just stopped by and schooled me on some of the subtleties of RSpec. If you remember I started with a skeleton for a test that was passing and that's not quite following TDD since we should have a test that initially fails. Otherwise, in a team environment there is a big chance that we will "forget" to implement the test.

A very useful trick when you are "scaffolding your tests" like I was is to remove the block, that is the do..end and RSpec will report the tests as pending. So my test now looks like:

require File.dirname(__FILE__) + '/../spec_helper'

module TimeEntrySpecHelperMethods
  def create_time_entry(options = {})
    @user = User.new
    @project = Project.new
    TimeEntry.create({ :user => @user, :project => @project }.merge(options))
  end
end

describe TimeEntry do

  include TimeEntrySpecHelperMethods

  it "should be invalid without an associated User" do
    time_entry = create_time_entry(:user => nil)
    time_entry.should_not be_valid
    time_entry.errors.on(:user).should eql('must have an associated user')
    time_entry.user = @user
    time_entry.should be_valid
  end

  it "should be invalid without an associated Project" do
    time_entry = create_time_entry(:project => nil)
    time_entry.should_not be_valid
    time_entry.errors.on(:project).should eql('must have an associated project')
    time_entry.project = @project
    time_entry.should be_valid
  end

  it "should be invalid without an associated Project Activity"

  it "should know that it needs to be split across days" 

  it "should know how to split a time entry across multiple days" 

  it "should not have a value higher than 24 hours" 

end

Notice the do..ends are gone in the unimplemented tests. When we run the test we now get:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
...PPPP..

Finished in 0.074545 seconds

9 examples, 0 failures, 4 pending

Pending:
TimeEntry should know that it needs to be split across days (Not Yet Implemented) 
TimeEntry should not have a value higher than 24 hours (Not Yet Implemented)
TimeEntry should know how to split a time entry across multiple days (Not Yet Implemented) 
TimeEntry should be invalid without an associated Project Activity (Not Yet Implemented)

Now that is cool! Thanks Joe.

Next we'll tackle a more challenging test and associated functionality:

TimeEntry "should know that it needs to be split across days"

This test should check that a TimeEntry can detect that it spans over multiple days. The test is simple, set the start and end dates so that they span over multiple days and check that a method, let's call it "needs_splitting" returns true.

  it "should know that it needs to be split across days" do
    time_entry = create_time_entry
    time_entry.start = 2.hours.ago(Time.today.beginning_of_day)
    time_entry.end = 5.hours.since(time_entry.start)
    time_entry.needs_splitting.should be_true
  end

Run the test and watch it fail:

rake spec
(in /Users/bsbodden/Documents/projects/tempo)
...PFP..

1)
NoMethodError in 'TimeEntry should know that it needs to be split across days'
undefined method `needs_splitting' for #
./spec/models/time_entry_spec.rb:40:

Finished in 0.088024 seconds

8 examples, 1 failure, 3 pending

Building Tempo with Rails, Part II

2007-10-22T09:44:53-04:00

Welcome back to part II of this series. Like I mentioned at the end of the first post; now we start the real work.

BDD, TDD and DDD

The sentence below summarizes what our development strategy will be:

"We are going to flesh the domain (DDD) with behaviours using (BDD) that we will express as tests (TDD) before writing any code"

We are going to be using RSpec, a Ruby XUnit framework that facilitates the writing of tests that test behavior rather than state, in the spirit of Behavior-Driven Development (BDD). With RSpec we will write the tests that will guide the development of our application. We will try to stick with Test-Driven Development (TDD) as closely as possible. RSpec can be thought of as a domain specific language for behavior testing via expectations.

If you have been using Test::Unit and you want to use RSpec you don't have to chose one over the other. Although if you have to make a choice, RSpec will give you more readable tests.

If you want to get some background on the ideas behind BDD take a peek at

Installing RSpec

As we did with Restful Authentication plugin we'll use Piston to install RSpec:

piston import svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec 
   vendor/plugins/rspec
Exported r2563 from 'svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec' 
to 'vendor/plugins/rspec'

Installing RSpec On Rails

An RSpec plugin that integrates with Rails exist which gives you the ability to create specs (read behavior tests) for your models, views, controllers and helpers. To install the RSpec On Rails plugin we again use Piston:

piston import svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec_on_rails 
   vendor/plugins/rspec_on_rails
Exported r2563 from 'svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec_on_rails' 
to 'vendor/plugins/rspec_on_rails'

To create the necessary RSpec directories and bootstrap code you need to run the rspec rake task:

script/generate rspec
      exists  spec
      create  spec/spec_helper.rb
      create  spec/spec.opts
      create  previous_failures.txt
      create  script/spec_server
      create  script/spec

Building Tempo's Domain

Now we are ready to tackle the domain of the application

Initial Domain Model

I know it is a cliché but I actually modelled the domain on a paper towel which I later scanned (Jim Weirich is much more classy and uses fine napkins). Below is my first pass at the nouns that immediately came to mind when thinking about tracking time in the context of a project at a consulting firm:

Based on the noun list above I created a simple UML-like diagram (in later issues of this blog I'll create something nicer):

The list below spells out what my thinking was when creating this model:

A User is associated with a Person *
A User can be part of zero or more Projects
A Project belongs to a Client *
A Project has some Project Activities associated which are a subset of a global list of Activities
A TimeEntry represents time entered against a project by a User in the context of a particular Activity

(1*) my thinking here is that I would have non-user entities in the system therefore I wanted to separate the Person/People (3*) don't know yet if a Client is a Person, User or other Entity

Building Tempo with Rails, Part I

2007-10-20T15:11:53-04:00

This is the first blog entry in a series about the process of going from idea to running software, while following all of the practices that we praise and push at our clients.

Tempo

At Integrallis we have been using an open source PHP-based Time Tracking Tool for a few years now. Don't get me wrong, we are thankful that this tool was out there to help us run our business but it's missing several features that we consider key, we don't have anybody on staff that knows PHP and the app is just plain ugly ;-) So we decided to write our own, Yeah, yeah we are suffering from the not invented here syndrome but in my defense I thought it would make for a nice series of blog entries/tutorials on how we are approaching the building of this application using Ruby on Rails. So let's start by describing in just a few paragraphs what is that we are looking to build.

"Tempo is a project based time tracking web application targeted primarily at small consulting firms and independent consultants"

To track the development of Tempo we are using the agile project management tool Savila created by our friends at Caimito Technologies. We are starting with a few simple user stories that should take us to the basic functionality required.

The initial user stories revolve around the basics of a time tracking system, basic project/tasks management and the authentication system.

Getting Started

Before we get to the user stories let's make sure that you have everything that you need to get started. We are using Rails version 1.2.3, Ruby 1.8.6 and MySQL 5.0.24.

There are countless Rails tutorials on the web. If you've never worked with Rails I suggest you go through one the top RoR tutorials

I have created a skeleton rails application (hopefully you know how to do that by know but just in case you don't, simply type:

rails tempo

We can use the about script to see what we have so far...

script/about


About your application's environment
Ruby version                 1.8.6 (i686-darwin8.9.1)
RubyGems version             0.9.2
Rails version                1.2.3
Active Record version        1.15.3
Action Pack version          1.13.3
Action Web Service version   1.2.3
Action Mailer version        1.3.3
Active Support version       1.4.2
Application root             /Users/bsbodden/Documents/projects/tempo
Environment                  development
Database adapter             mysql
Database schema version      4

At this point you should be able to get your skeleton application running.

Initial User Stories

The table and the Savila screenshot below show the user stories that we will be tackling on "Sprint #1" of the Tempo development. The duration of the Spring should be around 2 weeks (I'm building Tempo on my spare time ;-)

Story Id	Short Description	Status	Complexity	Business Value
TMPO-4	Login into the site	OPEN	10 points	Business Critical
TMPO-15	Site Admin adds global Activities	OPEN	20 points	Business Critical
TMPO-19	Site Administrator Creates a Project Owner Account	OPEN	20 points	Business Critical
TMPO-21	Site Administrator creates a User Account	OPEN	20 points	Business Critical
TMPO-25	Site Admin creates a Project	OPEN	20 points	Business Critical
TMPO-27	Site Administrator assigns a User as Project Owner for a given Project	OPEN	20 points	Business Critical
TMPO-29	User enters Time	OPEN	40 points	Business Critical

Managing Plug-ins with Piston

Before we start downloading and installing plugins I decided that I needed a better way to manage the plugins in my application. To accomplish this I installed Piston. Piston enables you to better manage the vendor branch. It does a better and simpler job that using svn:externals, and you can "install" plugins into your vendor/plugins directory and lock them to a certain version.

Install Piston

Install the piston gem by using the following command:

gem install -y piston

Bulk updating Gem source index for: http://gems.rubyforge.org
Successfully installed piston-1.3.3

Restful Authentication

Since a lot of the initial stories revolve around a User, a good starting point is to get an authentication system going. Since I want to also make Tempo a Restful Rails application. I will based my authentication system on the Restful Authentication plugin, which is a restful version of the familiar actsas_authenticated. Let's use Piston to import the restfulauthentication plugin and create our user model and sessions controller. I find that very often in web-based application the User model is a good starting point from where to flesh out the rest of the system.

Install Restful Authentication Plugin

piston import http://svn.techno-weenie.net/projects/plugins/restful_authentication 
   vendor/plugins/restful_authentication

Exported r2983 from 'http://svn.techno-weenie.net/projects/plugins/restful_authentication' 
to 'vendor/plugins/restful_authentication'

Generate User model and the Sessions controller

script/generate authenticated user sessions

----------------------------------------------------------------------
Don't forget to:

  - add restful routes in config/routes.rb
    map.resources :users
    map.resource  :session

 Rails 1.2.3 may need a :controller option for the singular resource:
  - map.resource :session, :controller => 'sessions'


Try these for some familiar login URLs if you like:

  map.signup '/signup', :controller => 'users', :action => 'new'
  map.login  '/login', :controller => 'sessions', :action => 'new'
  map.logout '/logout', :controller => 'sessions', :action => 'destroy'

----------------------------------------------------------------------

      exists  app/models/
      exists  app/controllers/
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/sessions
      exists  test/functional/
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/users
      exists  test/functional/
      exists  test/unit/
      create  app/models/user.rb
      create  app/controllers/sessions_controller.rb
      create  app/controllers/users_controller.rb
      create  lib/authenticated_system.rb
      create  lib/authenticated_test_helper.rb
      create  test/functional/sessions_controller_test.rb
      create  test/functional/users_controller_test.rb
      create  app/helpers/sessions_helper.rb
      create  app/helpers/users_helper.rb
      create  test/unit/user_test.rb
      create  test/fixtures/users.yml
      create  app/views/sessions/new.rhtml
      create  app/views/users/new.rhtml
      create  db/migrate
      create  db/migrate/001_create_users.rb
/>

As the plugin clearly suggests I added the following code to my routes.rb file in /config

  # Restful Authentication routes
  map.resources :users
  map.resource  :session, :controller => 'sessions'

  # Map to familiar URLs
  map.signup '/signup', :controller => 'users', :action => 'new'
  map.login  '/login', :controller => 'sessions', :action => 'new'
  map.logout '/logout', :controller => 'sessions', :action => 'destroy'

Ok now we have basic authentication and some tests to prove that. We could go ahead and add out changes to the User model but first let's run the migration in development and make sure that all the tests that the plugin generator created pass.

If you haven't done it yet, go ahead and configure the database and create the mysql instance for tempo_development

Running our first migration for Tempo

rake db:migrate
(in /Users/bsbodden/Documents/projects/tempo)
== CreateUsers: migrating =====================================================
-- create_table("users", {:force=>true})
   -> 0.0591s
== CreateUsers: migrated (0.0593s) ============================================

Running the existing tests

rake
(in /Users/bsbodden/Documents/projects/tempo)

Started
..............
Finished in 0.219704 seconds.

14 tests, 26 assertions, 0 failures, 0 errors

Yay! You can test the app (assuming that you've started the server) by pointing your browser to http://localhost:port /signup /login /logout

Now the real work starts, in the next installment of this series we will tackle the development of the domain using DDD (Domain Driven Development) and TDD (Test Driven Development).