A little bit about aspect oriented programming (AOP)

For the last few couple of years, as the hardware kept getting cheaper and more powerful, the programming languages core concern has been moved from performance to clarity and maintainability.

While in the past you had to keep asking yourself which algorithm was the best to, say, iterate over a list, now it is far from being a major concern. What it gives us, developers, is a chance to focus our precious time and effort on more important matters in our daily jobs, like readability and maintainability.

With these new priorities in mind, the industry have come up with the object oriented paradigm - which focus on mapping real world entities straight to code equivalents.

However, a big troublemaker we still face every now and then while developing software are the crosscutting concerns - generating replicated code all around our projects.  The main examples I can come up with about this are:

• Logging;
• Authentication;
• Open/Close connections;
• Exception handling.

These concerns not seldom can be seen being dealt with using very similar (if not the exact same) blocks of code alongside many of our classes, even though it is a relatively unique matter.

To address this problem came the aspect oriented paradigm. Its purpose is to complement the OOP, eliminating the need for replication and adding clarity to your code. What follows in this article is a very quick example of the possible benefits that using aspects can bring you while developing software.

Learning by Example

The immediate concern I have about having code all over the place to handle a concern that should be centralized is that, when this thing needs to be changed for some reason, you will have to manually go to every point where the code is replicated and fix it. Every good programmer knows that manual tasks like this are bound to catastrophic failure.

Next, let’s implement an Account class, that will provide deposit and withdraw functionality. We shall start, of course, by the tests:

[TestMethod]
public void WithdrawShouldDecreaseBalance()
{
    Account account1 = AccountBuilder.New
        .BelongingTo("MACSkeptic")
        .WithInitialBalance(200.95M)
        .IdentifiedBy(773)
        .Instance;

    Assert.AreEqual(100.95M, account1.Withdraw(100).CurrentBalance);
    Assert.AreEqual(0.0M, account1.Withdraw(100.95M).CurrentBalance);
    Assert.AreEqual(-10.0M, account1.Withdraw(10.00M).CurrentBalance);
}

[TestMethod]
public void DepositShouldIncreaseBalance()
{
    Account account1 = AccountBuilder.New
        .BelongingTo("MACSkeptic")
        .WithInitialBalance(-50.42M)
        .IdentifiedBy(666)
        .Instance;

    Assert.AreEqual(-0.42M, account1.Deposit(50).CurrentBalance);
    Assert.AreEqual(79.58M, account1.Deposit(80).CurrentBalance);
}

To satisfy the behavior denoted just above we shall implement the Account class, like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Codevil.MACSkeptic.PostSharpExample.Entities
{
    public class Account
    {
        public long Number { get; set; }
        public string Owner { get; set; }
        public decimal CurrentBalance { get { return this.currentBalance; } }

        private decimal currentBalance;

        public Account(long number, string owner)
            : this(number, owner, 0)
        {
        }

        public Account(long number, string owner, decimal initialBalance)
        {
            this.Number = number;
            this.Owner = owner;
            this.currentBalance = initialBalance;
        }

        public Account Deposit(decimal howMuch)
        {
            Console.WriteLine(string.Format(
                "New deposit transaction on account {0}. Balance before operation is ${1}.",
                this.Number,
                this.CurrentBalance));

            Console.WriteLine(string.Format(
                "Depositing ${0} on account {1}.", howMuch, this.Number));

            this.currentBalance += howMuch;

            Console.WriteLine(string.Format(
                "Finished deposit transaction on account {0}. Balance after the operation is ${1}.",
                this.Number,
                this.CurrentBalance));

            return this;
        }

        public Account Withdraw(decimal howMuch)
        {
            Console.WriteLine(string.Format(
                "New withdraw transaction on account {0}. Balance before operation is ${1}.",
                this.Number,
                this.CurrentBalance));

            Console.WriteLine(string.Format(
                "Withdrawing ${0} on account {1}.", howMuch, this.Number));

            this.currentBalance -= howMuch;

            Console.WriteLine(string.Format(
                "Finished withdraw transaction on account {0}. Balance after the operation is ${1}.",
                this.Number,
                this.CurrentBalance));

            return this;
        }
    }
}

As you can see, our account allows for deposits and withdrawals with no concern about the overall balance at the moment. Which means, if you withdraw more than you have, you’re going to get in debt.

To keep things simple and focus on what really matters here, I’m using the console as the log of the application.

By the code above, we can already spot a clear repetition pattern on the logging concern related code. Let’s try to fix it with traditional OO refactoring, extract method:

public Account Deposit(decimal howMuch)
{
    this.LogTransactionStarting("deposit");
    this.LogTransactionDetails("Depositing", howMuch);
    this.currentBalance += howMuch;
    this.LogTransactionFinished("deposit");
    return this;
}
public Account Withdraw(decimal howMuch)
{
    this.LogTransactionStarting("withdraw");
    this.LogTransactionDetails("Withdrawing", howMuch);
    this.currentBalance -= howMuch;
    this.LogTransactionFinished("withdraw");
    return this;
}
private void LogTransactionStarting(string action)
{
    Console.WriteLine(string.Format(
        "New {2} transaction on account {0}. Balance before operation is ${1}.",
        this.Number,
        this.CurrentBalance,
        action));
}
private void LogTransactionDetails(string action, decimal howMuch)
{
    Console.WriteLine(string.Format(
        "{2} ${0} on account {1}.", howMuch, this.Number, action));
}
private void LogTransactionFinished(string action)
{
    Console.WriteLine(string.Format(
        "Finished {2} transaction on account {0}. Balance after the operation is ${1}.",
        this.Number,
        this.CurrentBalance,
        action));
}

Ok, that’s a little better now, with a little less repetition, right? But, as you can see, the account class still has to be concerned with keeping a log of its transactions. Using just OO we could move the logging methods to another class, like a service. But still we would have to call them explicitly from inside the account class. The problem with this is that, when you read this code, you will most likely get distracted from the main point (the business logic) because of the logging concerned method calls.

There is a well known saying about how you design your classes on an OOP project: if you have to use an "and" to describe what your class does, that smells like bad design - more specifically, your class is most likely overloaded with responsibilities that shouldn’t be there. In our example so far, the account class is concerned with the account movements and the logging.

Here we can classify the main points at which we wish to add logging:

• Before any transaction;
• Right when the transaction will be executed, with details concerning values involved;
• Right after the transaction.

A very interesting and powerful tool for aspect development in .NET is the PostSharp framework - its slogan: "make sense, not code" says a lot about the main idea of the AOP. For the next tasks on this article, we will need to download PostSharp (I’m using the version 1.5). It can be downloaded clicking here (you will need to register, which is free, by clicking here).

After installing PostSharp, it is time to add references to PostSharp.Laos and PostSharp.Public to our project, like this:

PostSharp’s detailed documentation can be accessed by clicking here.

Our account class will make use of the following aspect concepts/classes:

• OnMethodBoundaryAspect
• OnMethodInvocationAspect

First things first, let’s get to the on method boundary aspect implementation:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using PostSharp.Laos;
using Codevil.MACSkeptic.PostSharpExample.Entities;

namespace Codevil.MACSkeptic.PostSharpExample.Aspects
{
    [Serializable]
    public class LogAccountStatusBeforeAndAfterTransaction : OnMethodBoundaryAspect
    {
        public override void OnEntry(MethodExecutionEventArgs eventArgs)
        {
            Account account = (Account)eventArgs.Instance;
            Console.WriteLine(string.Format(
                "New {2} transaction on account {0}. Balance before operation is ${1}.",
                account.Number,
                account.CurrentBalance,
                eventArgs.Method.Name));
        }
        public override void OnExit(MethodExecutionEventArgs eventArgs)
        {
            Account account = (Account)eventArgs.Instance;
            Console.WriteLine(string.Format(
               "Finished {2} transaction on account {0}. Balance after the operation is ${1}.",
               account.Number,
               account.CurrentBalance,
               eventArgs.Method.Name));
        }
    }
}

The aspect "on method boundary" allows us to determine pieces of code that will be executed right before and right after the original method was called, like you can see in the snippet just above.  It is very important to notice that all aspect implementations with PostSharp must be serializable.

Since we moved the "before transaction" and "after transaction" logging concern to this aspect, let’s see how it can help us with our account class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Codevil.MACSkeptic.PostSharpExample.Aspects;

namespace Codevil.MACSkeptic.PostSharpExample.Entities
{
    public class Account
    {
        public long Number { get; set; }
        public string Owner { get; set; }
        public decimal CurrentBalance { get { return this.currentBalance; } }
        private decimal currentBalance;

        public Account(long number, string owner)
            : this(number, owner, 0)
        {
        }

        public Account(long number, string owner, decimal initialBalance)
        {
            this.Number = number;
            this.Owner = owner;
            this.currentBalance = initialBalance;
        }
        [LogAccountStatusBeforeAndAfterTransaction]
        public Account Deposit(decimal howMuch)
        {
            this.LogTransactionDetails("Depositing", howMuch);
            this.currentBalance += howMuch;
            return this;
        }
        [LogAccountStatusBeforeAndAfterTransaction]
        public Account Withdraw(decimal howMuch)
        {
            this.LogTransactionDetails("Withdrawing", howMuch);
            this.currentBalance -= howMuch;
            return this;
        }
        private void LogTransactionDetails(string action, decimal howMuch)
        {
            Console.WriteLine(string.Format(
                "{2} ${0} on account {1}.", howMuch, this.Number, action));
        }
    }
}

We can see the attributes added on lines #27 and #34 - they just mark where the logging aspect is supposed to act.

Now, let’s see how the "on method invocation" aspect works on practice:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using PostSharp.Laos;
using Codevil.MACSkeptic.PostSharpExample.Entities;

namespace Codevil.MACSkeptic.PostSharpExample.Aspects
{
    [Serializable]
    public class LogAccountTransactionDetails : OnMethodInvocationAspect
    {
        public override void OnInvocation(MethodInvocationEventArgs eventArgs)
        {
            Account account = (Account)eventArgs.Instance;
            Console.WriteLine(string.Format(
                "{2} ${0} on account {1}.",
                eventArgs.GetArgumentArray().First(),
                account.Number,
                eventArgs.Method.Name));
            eventArgs.Proceed();
        }
    }
}

Again, we’ve just moved the original implementation of the logging method (which was once on the account class) to here. Here it is interesting to notice that the eventArgs parameter gives us access to some really neat stuff, like:

• The current instance of the class in which the aspect is being applied;
• The method being called;
• The parameters used on the method call.

Notice the call to the method "proceed" above (line #21)? This method tells the weaver that the original method should be called right at this point. This concept has some immediate consequences, if needed, we could:

• Switch the original parameters with new ones - to do that, you just need to pass the new ones to the proceed method;
• Not even call the original method - to do that, you just need to omit the call to the proceed method altogether.

With this, we’ve just moved every last bit of logging concern straight out of our account class, into our logging aspects. So, let’s see how the account class has changed:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Codevil.MACSkeptic.PostSharpExample.Aspects;

namespace Codevil.MACSkeptic.PostSharpExample.Entities
{
    public class Account
    {
        public long Number { get; set; }
        public string Owner { get; set; }
        public decimal CurrentBalance { get { return this.currentBalance; } }
        private decimal currentBalance;

        public Account(long number, string owner)
            : this(number, owner, 0)
        {
        }

        public Account(long number, string owner, decimal initialBalance)
        {
            this.Number = number;
            this.Owner = owner;
            this.currentBalance = initialBalance;
        }
        [LogAccountStatusBeforeAndAfterTransaction]
        [LogAccountTransactionDetails]
        public Account Deposit(decimal howMuch)
        {
            this.currentBalance += howMuch;
            return this;
        }
        [LogAccountStatusBeforeAndAfterTransaction]
        [LogAccountTransactionDetails]
        public Account Withdraw(decimal howMuch)
        {
            this.currentBalance -= howMuch;
            return this;
        }
    }
}

Before anything else, by using a regular expression we can clean up this code even more:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Codevil.MACSkeptic.PostSharpExample.Aspects;

namespace Codevil.MACSkeptic.PostSharpExample.Entities
{
    [LogAccountStatusBeforeAndAfterTransaction(
		AttributeTargetMembers = "regex:(Deposit)|(Withdraw)")]
    [LogAccountTransactionDetails(
		AttributeTargetMembers = "regex:(Deposit)|(Withdraw)")]
    public class Account
    {
        public long Number { get; set; }
        public string Owner { get; set; }
        public decimal CurrentBalance { get { return this.currentBalance; } }
        private decimal currentBalance;

        public Account(long number, string owner)
            : this(number, owner, 0)
        {
        }

        public Account(long number, string owner, decimal initialBalance)
        {
            this.Number = number;
            this.Owner = owner;
            this.currentBalance = initialBalance;
        }
        public Account Deposit(decimal howMuch)
        {
            this.currentBalance += howMuch;
            return this;
        }
        public Account Withdraw(decimal howMuch)
        {
            this.currentBalance -= howMuch;
            return this;
        }
    }
}

No more logging concern inside our account class ;).

It gets even better! Now that we have a little better understanding of the PostSharp framework, we can get rid of the "on method boundary" aspect. To do so, we just need to make some adjusts to the "on method invocation aspect", like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using PostSharp.Laos;
using Codevil.MACSkeptic.PostSharpExample.Entities;

namespace Codevil.MACSkeptic.PostSharpExample.Aspects
{
    [Serializable]
    public class LogAccountTransactionDetails : OnMethodInvocationAspect
    {
        public override void OnInvocation(MethodInvocationEventArgs eventArgs)
        {
            Account account = (Account)eventArgs.Instance;

            LogTransactionStarting(eventArgs, account);
            LogTransactionDetails(eventArgs, account);
            eventArgs.Proceed();
            LogTransactionFinished(eventArgs, account);
        }
        private static void LogTransactionDetails(
			MethodInvocationEventArgs eventArgs, Account account)
        {
            Console.WriteLine(string.Format(
                "{2} ${0} on account {1}.",
                eventArgs.GetArgumentArray().First(),
                account.Number,
                eventArgs.Method.Name));
        }
        private static void LogTransactionStarting(
			MethodInvocationEventArgs eventArgs, Account account)
        {
            Console.WriteLine(string.Format(
                "New {2} transaction on account {0}. Balance before operation is ${1}.",
                account.Number,
                account.CurrentBalance,
                eventArgs.Method.Name));
        }
        private static void LogTransactionFinished(
			MethodInvocationEventArgs eventArgs, Account account)
        {
            Console.WriteLine(string.Format(
               "Finished {2} transaction on account {0}. Balance after the operation is ${1}.",
               account.Number,
               account.CurrentBalance,
               eventArgs.Method.Name));
        }
    }
}

Notice that first we log the transaction start (line #17), then the transaction details, including parameters (line #18), only then we call the original method (line #19), and then, finally we log the transaction end (line #20). With this, we just replicated the original behavior using the two aspects, but using only the "on method invocation" =). Now, let’s get rid of our, now useless, aspect "on method boundary" on the account class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Codevil.MACSkeptic.PostSharpExample.Aspects;

namespace Codevil.MACSkeptic.PostSharpExample.Entities
{
    [LogAccountTransactionDetails(
		AttributeTargetMembers = "regex:(Deposit)|(Withdraw)")]
    public class Account
    {
        public long Number { get; set; }
        public string Owner { get; set; }
        public decimal CurrentBalance { get { return this.currentBalance; } }
        private decimal currentBalance;
        private const decimal DefaultInitialBalance = 0;

        public Account(long number, string owner)
            : this(number, owner, DefaultInitialBalance)
        {
        }
        public Account(long number, string owner, decimal initialBalance)
        {
            this.Number = number;
            this.Owner = owner;
            this.currentBalance = initialBalance;
        }

        public Account Deposit(decimal howMuch)
        {
            this.currentBalance += howMuch;
            return this;
        }
        public Account Withdraw(decimal howMuch)
        {
            this.currentBalance -= howMuch;
            return this;
        }
    }
}

Even in this small example you can see how we just got rid of, at the very least, 6 lines of alien code that were inside of our account class (6 lines considering the best case scenario using just OOP, if you moved the logging implementation to a service). These lines were strictly concerned with logging, which should be none of our account class concern. In their place, we had to add just a single line declaring an aspect of the behavior desired across our account class.

Just to keep things clear, my point here is not that less code is necessarily better (although it usually is), but that you should separate the responsibilities very clearly and write the code where it really belongs.

That’s all for now folks, I hope you’ve liked this and got a grasp on how powerful AOP can be. I strongly recommend that those interested in using aspects in real projects get to read carefully the PostSharp documentation to check the details about optimization and performance.

Like usual, the codebase for this article is on my github, and can be downloaded here. Feel free to leave your doubts, criticisms, suggestions and feelings at the comments.

Cheers, and see you next time ;).

References:

• PostSharp - main site: http://www.postsharp.org/
• PostSharp - register: http://www.postsharp.org/forum/ucp.php?mode=register
• PostSharp - documentation: http://doc.postsharp.org/1.5/
• Why Aspects/PostSharp: http://www.postsharp.org/about/video

Recommended Reading:

• AOP: http://gzaib.blogspot.com/2009/08/aspect-oriented-programming.html
• Importance of clear separation of concerns: https://mice.cs.columbia.edu/getTechreport.php?techreportID=438

After a little more than one year of heavy code production and few innovations, although I could explore some interesting stuff like WCF and RESTful, our team finally got a time to “invent” something new. This time, we have to rewrite a legacy system (mainly a single stored procedure *arghh*) that verifies the clients with overdue payments, notifies them about it and stop provisioning services until their debts are paid off. As it can be imagined, it has many responsibilities belonging to different domains, consequently, belonging to different teams of our company.

My team is responsible for verifying the financial issues and should inform another team, which takes care of services provisioning, about the debtors. Thus, it is necessary to define how our systems will communicate with each other. One of the suggested solutions was AMQP standard for message queuing and that’s exactly what I will talk about.

AMQP stands for Advanced Message Queuing Protocol and its main purpose is to enable full functional interoperability between conforming clients and messaging middleware servers (aka. brokers). That is, AMQP defines a standard protocol for publishing, queueing, storing and consuming messages. The message producer utilizes a client API to publish message into a server. The server/broker will then place the message into a queue and store it while it is not consumed. At last, a consumer application will accept the messages stored in a queue and remove them from it.

The AMQP overall model is represented below:

Server

An AMQP server, like RabbitMQ or Qpid, is a data server that accepts messages, routes them to different consumers (queues) according to some arbitrary criteria (bindings) and store the messages while not consumed.

Virtual Hosts

A virtual host is somewhat similar to a workspace where a user connects. It comprises a set of exchanges, message queues and bindings. Even though an user is authenticated into the server, it may not successfully connect into a virtual host if it is not authorized. The authorization for the server users are granted for each virtual host.

Exchange

It can be said that the exchange possess the most important role among the AMQP middleware server components. It is delegated to route the messages to the queues matching the routing information, like an routing key, with the previously set bindings. Exchanges can also route messages according to its type. Some of them are explained below:

1. Direct: direct type exchange routes a given message matching exactly the message routing key with the queue binding key. This type of exchange is a MUST in AMQP server implementation.
2. Fanout: fanout type exchange routes a given message to all bound queues regardless of it’s routing key. The fanout also is a MUST in the broker.
3. Topic: topic type exchange routes a given message verifying if the message key matches the queue binding key. For instance, let’s suppose that we have created a queue belonging to an exchange of type topic and it is bound to the exchange with a binding key like “sport.#”. Now, imagine a message sent to the exchange with a routing key “sport.soccer”. The key “sport.#” says that any message with a key “sport.anything” must be routed to the queue with such binding key. The ‘#’ means matches zero or more words and ‘*’ means matches one word. Topic is a SHOULD be implement type in AMQP server.

Bindings

A binding is a constraint between a queue and an exchange, setting a criterion for message routing.

Routing Keys/Binding Keys

As explained above, routing keys are message identifiers. In the other hand, binding keys are bindings identifiers. Duh, you may say. I agree. But it is pretty much that. Binding keys exists to tell the exchange that a message with a key that matches the routing key should be addressed to its related queue.

Message Queues

Message queues are the consumer’s message inboxes. It keeps the messages in memory or disk until they are read by the consumer in a FIFO politics.

To illustrate AMQP messaging flow in a more comprehensible manner, let’s take a look at the following comic (special thanks to KreuZ for helping me with the figures), representing a Direct Type Exchange:

In these frames, we have a Message producer that sends a message with a “cars” key to the Exchange. We have also two queues: John’s queue and Kate’s queue. John’s queue says that he likes “cars”. That is, he is bounded to the exchange saying that any message related to “cars” (binding key) is of his business.

When the Exchange receives the given message, he knows that John’s queue is interested in "cars”, Kate’s queue is interested in “cookies”, and that he has a message about “cars” in hands. So, with these information, he passes the message to John’s queue but not to Kate’s queue, since the message “subject” matches exactly with what John’s queue wants.

Well, that’s an introductory post about AMQP that I wanted to have it here because my next post will be about real code using AMQP implementations. For more information about AMQP, please refer to its site.

Finally, I hope that the illustration helps for a better understanding of the basic principles of AMQP protocol and I would appreciate your comments and mainly, suggestion and critics.

The "Beyond The Buzzwords" series is focused on giving those who are starting to write automated tests a practical overview, so that they begin to get a grasp on the mechanics of doing it. Also, to encourage those who don’t do it yet to begin doing so. That said, the idea is to not be over theoretical and purist, scaring away newcomers - but keeping both feet firmly on the arduous ground in which lies the path to solid automated testing practices.

This is the second article in the series. Today I’m going to talk about TDD - taking a slightly different approach on the bookstore application we developed on the last one.

TDD stands for Test Driven Design - it means to let your tests guide your software development at each and every step of the way to quality and highly maintainable code. It is mainly based on a relentless three step heartbeat-like pattern that must not be disturbed:

Red => Green => Refactoring => Red…

This very simple pattern stands at the very core of the TDD mindset. So, let’s take a look at the meaning of each work [if you have not guessed it already]:

• Red stands for writing a test that describes a single simple and punctual functionality, then running that test to watch it fails. Yes, you should [must] write your tests first, otherwise they’ll nothing but re-hashes of your actual implementation code, therefore testing nothing in terms of domain logic per se.
• Green stands for writing the bare minimum of code necessary to make the test pass. This is important, don’t jump to implement extra functionality just because you’re already coding anyway - keep it minimal, simple and focused on making the test pass, you can care about design later.
• Refactoring stands for making your code better, from a design perspective, applying some refactoring principle [Martin Fowler wrote a book on this subject, published in 1999 - with this being a pretty good catalogue of commonly used refactoring patterns]. That must only be done when all your tests are passing, and they should still pass once you’ve done refactoring - otherwise it means that your embellishment  of the code actually broke it.

If you are willing to take the textbook approach to TDD, then the aforementioned definitions mean that not a single line of code shall be written if there isn’t a test failing because of the lack of that very specific line. And this is definitely a statement not to be taken lightly.

While BDD seems to lack support from proper tools for the modern widespread mainstream programming languages (JBehave and NBehave still have ways to go before standing up to cucumber) - TDD, on the other hand, has  plenty of them for virtually any platform you pick. Since our bookstore is a rails application, we’ll be using the ruby option that I like the most: rspec.

Let’s just say we are given the exact same story to work with than last time, in case you’ve forgot it:

As the bookstore owner
I want to be able to register new books including rating and author
So that I don’t need to call the IT guys to do it for me manually every single time

That being said, let’s see how it works on practice:

rails bookstore_tdd --database=mysql
cd bookstore_tdd
rake db:create:all
rake db:migrate
script/generate rspec

The last command shown above shall generate some infrastructure for testing with rspec on your rails application.

Now, let’s create the book model, instead of the default rails generator we’re going to use the rspec one, like this:

script/generate rspec_model book title:string author:string rating:decimal synopsis:text

Also let’s create the books table both on development and on test environment

rake db:migrate
rake db:migrate RAILS_ENV=test

Since we’ve used the rspec generator for the model, it already created an skeleton so that we can test it, you can check it on the spec/models/book_file.rb file. It should look like this:

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

describe Book do
  before(:each) do
    @valid_attributes = {
      :title => "value for title",
      :author => "value for author",
      :rating => 9.99,
      :synopsis => "value for synopsis"
    }
  end

  it "should create a new instance given valid attributes" do
    Book.create!(@valid_attributes)
  end
end

Since the whole code for persistence of the book model is handled by the active record framework, we don’t need to bother to write tests to ensure that it works - since such test suite is already done by those who develop it.

But, for the sake of exemplifying the possibilities, let’s say that our business policy says that it is OK to have a book without synopsis and/or rating, but its title and author are mandatory properties. The previous statement describes a very specific rule to our application - the best way to express it is writting a test to make it clear. Well written tests can virtually replace any need for external documentation - in other words: your tests should describe as clearly as possible the particularities of your application.

Keep in mind that rspec is a very flexible tool, and can be used in many different ways to accomplish the same goal. I’m going to show an approach that I am particularly inclined to use very often. Let’s change the placeholder code that was automatically inserted on the book spec to this:

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

describe Book, "with all attributes properly set" do
  before(:each) do
    @valid_attributes = {
      :title => "value for title",
      :author => "value for author",
      :rating => 9.99,
      :synopsis => "value for synopsis"
    }
  end

  it "should create a new instance given valid attributes" do
    lambda { Book.create!(@valid_attributes) }.should_not raise_error
  end
end

describe Book, "missing rating and synopsis" do
  before(:each) do
    @valid_attributes = {
      :title => "value for title",
      :author => "value for author"
    }
  end

  it "should be OK, since rating and synopsis are optional" do
    lambda { Book.create!(@valid_attributes) }.should_not raise_error
  end
end

describe Book, "missing author" do
  before(:each) do
    @invalid_attributes = {
      :title => "value for title",
      :rating => 9.99,
      :synopsis => "value for synopsis"
    }
  end

  it "should not be allowed, because author is mandatory" do
    # lambda { Book.create!(@invalid_attributes) }.should raise_error <= this is another way to do it
    book = Book.create(@invalid_attributes)
    book.errors_on(:author).should_not be_empty
  end
end

describe Book, "missing title" do
  before(:each) do
    @invalid_attributes = {
      :author => "value for author",
      :rating => 9.99,
      :synopsis => "value for synopsis"
    }
  end

  it "should not be allowed, because title is mandatory" do
    # lambda { Book.create!(@invalid_attributes) }.should raise_error  <= this is another way to do it
    book = Book.create(@invalid_attributes)
    book.errors_on(:title).should_not be_empty
  end
end

That was a lot of code, so let’s take a look at some crucial concepts:

• With rspec you don’t write tests for your classes, you write a description about what is expected from them - therefore the use of the “describe” syntax
• Some people defend fewer contexts for each model, I particularly like to create a new describe block for each kind of scenario
• Rspec defines the methods “should” and “should_not” for every object, so you can evaluate the result using them - a full list of the possibilites can be consulted here

You probably have noticed that each test has been written using the prefix “it” followed by a natural language sentence, right? Because of that, the outcome we get when we run our specs [rake spec] is something like this:

FF..

1)
'Book missing title should not be allowed, because title is mandatory' FAILED
expected empty? to return false, got true
./spec/models/book_spec.rb:59:

2)
'Book missing author should not be allowed, because author is mandatory' FAILED
expected empty? to return false, got true
./spec/models/book_spec.rb:43:

Finished in 0.054108 seconds

4 examples, 2 failures

As I already stated before, from the excerpt shown just above - if you plan your tests to pinpoint each specifical detail of functionality you might even be able to never again need to run a debugging session. By looking at the result shown above we can notice the “FF..” on the beginning, it means that there are two tests failing [F] an two passing [.].

Since it failed, it is time to write the code to make it pass. On the book model, add the validation for the mandatory fields, like this:

class Book < ActiveRecord::Base
  validates_presence_of [:title, :author]
end

Running the specs again show us that it worked:

....

Finished in 0.061223 seconds

4 examples, 0 failures

Homework: write tests to guarantee that duplicated titles are not allowed.

Now we need to add another test, describing our application. Let’s create the books controller, once again, we’re using the rspec generator

script/generate rspec_controller books

Go to the spec/controllers/books_controller_spec.rb and let’s write our test for the action “create”:

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

describe BooksController do
  it "should have an action that allow the creation of new books" do
    controller.should respond_to(:create)
  end
end

Ideally speaking, you will want to keep each “example” (the term rspec uses for each individual test) to the minimum assertions possible. That will make things more traceable later. Run the spec and watch it fail!

Now, time to write the minimum code necessary to make it pass, on the books controller:

def create
end

Run the specs again and see that its all green now.

Now we need to write another test, since clearly just having a method create on our books controller won’t do us any good. What’s missing is that the create method should receive the parameters to create a new book on the database and do it.

But this is a problematic point: if we write the test to actually persist our book on the database, we will be depending on book model logic again - which has already been tested somewhere else. This is not going to be a unit test at all, but a full stack one - which is bound to become slow pretty fast. Not to mention that if the controller tests depend on the model, and you screw up the model, the controller tests will also fail, totally ruining the traceability that your test suite should provide.

The solution for that is another widespread term: dependency injection. Any decent modern language have a whole bunch of frameworks for dependency injection a.k.a. inversion of control. What it means is that your implementation should be flexible enough to depend on the interface of its dependencies, not on their implementation. Putting it in simple terms, let’s say you’re programming an entity on C#, that depends on a repository for persistence, you should create an interface for this repository and have your entity provide some way of replacing the actual implementation with a fake one (mostly for the purpose of decoupled testing). But, since we’re working with ruby, and it has open classes, it is not even needed to bother with providing ways for dependency injection - just keep the concept in mind.

To properly make use of dependency injection, we need to setup fake implementation for the dependencies of our classes. Let’s look at our bookstore: the books controller depends on the book model, so we need to replace the model implementation on the controller with a fake one, that provides us with full control over it. What I’m talking about right now can be mainly categorized between two big concepts of unit testing: mocks and stubs. The difference between the two is very subtle on the first sight, so further reading about these two concepts is strongly advised. There are also some other important ones, like fakes and spies. But that isn’t needed for now, just try to get a grasp on their purpose in this practical example, continuing our bookstore:

describe BooksController, "creating a valid book" do
  before(:each) do
    @params_for_save = { "title" => "advanced joseki", "author" => "honinbou shusaku" }
    @book = mock_model(Book)
    Book.stub!(:new).and_return(@book)
  end

  def call_create
    post :create, { :book => @params_for_save }
  end

  it "should instantiate a new book with the given parameters" do
    Book.should_receive(:new).with(@params_for_save).and_return(@book)
    call_create
  end
end

One thing at a time, let’s look ath the “before each” method first:

• @params_for_save is just a helper to avoid repetition of the same hash of parameters over and over and over again
• @book represents a mocked instance of the book model - we’ll see more about this later on
• Book.stub! says that the Book (app/model/Book.rb) class will be replaced with this stub. When the method “new” is called, this stub will return our mocked book, instead of creating a new instance

What we gained from that? Let’s say the “new” (initialize) method of the original book model does something like checking the database for some condition, or calling an webservice, or whatever… by replacing the Book class implementation with this stub, we’re totally decoupling our controller test from any of that. These aspects of the Book model should have been already tested elsewhere (on the specific Book model spec) - so we can just assume that they will work and focus on what we are testing right now: the controller.

The “call_create” is just a helper method, once again to avoid repetition. What it does is just simulate a post (like a form would do) to the create method, passing the parameters like if it was being passed by the real form.

The example says that in the method we are testing (create), the constructor of the Book class shall be called, passing the parameters received on the post request - and when it is called, it will return our mocked book model. Running the specs now will fail, because our “create” method isn’t calling the constructor of the Book class, as the example describes it should.

To fix that we must instantiate a new book on the controller.

@book = Book.new params[:book]

This will make the specs run successfully! So, time to ellaborate on our examples:

describe BooksController, "creating a valid book" do
  before(:each) do
    @params_for_save = { "title" => "advanced joseki", "author" => "honinbou shusaku" }
    @book = mock_model(Book, :save! => true)
    Book.stub!(:new).and_return(@book)
  end

  def call_create
    post :create, { :book => @params_for_save }
  end

  it "should instantiate a new book with the given parameters" do
    Book.should_receive(:new).with(@params_for_save).and_return(@book)
    call_create
  end

  it "should save the book on the database" do
    @book.should_receive(:save!).and_return(true)
    call_create
  end

  it "should notice the user about the success" do
    call_create
    flash.now[:notice].should match(/.*successfully.*/)
  end
end

Things to notice:

• The mock_model call on the “before each” method has been slighly modified. That tells our mock that “save!” is a valid method, and when called it should return true. That means that when the controller calls it, during the test, it won’t actually save the book on the database, but just get a true return - just like the actuall Book would do if the save operation were successful
• There were added two new examples, which I think shouldn’t be a problem to understand. I’ve added two at once for the sake of eliminating the repetition on this article - while developing you should write one test (example, whatever you call it) and watch it fail, make it pass, then write another one and so on… Keep that in mind, because from now on I will quicken up the pace

Running the specs it shall fail - then let’s make it pass:

class BooksController < ApplicationController
  def create
    @book = Book.new params[:book]
    @book.save!
    flash[:notice] = "The book was saved successfully"
    render :text => ""
  end
end

Running the specs now shall give you an all green result.

To wrap it up, let’s see how we can add a error scenario to our controller test - like an invalid book. It will probably look something like this:

describe BooksController, "creating an invalid new book" do
  before(:each) do
    @params_for_save = { "title" => "the god delusion", "author" => "richard dawkins" }
    Book.stub!(:new).and_return(@book = mock_model(Book, :save! => true))
  end

  def call_create
    post :create, { :book => @params_for_save }
  end

  it "should instantiate a new book with the given parameters" do
    Book.should_receive(:new).with(@params_for_save).and_return(@book)
    call_create
  end

  it "should notice the user that the book is invalid" do
    @book.should_receive(:save!).and_raise(StandardError.new("Error saving the book"))
    call_create
  end

  it "should notice the user about the failure" do
    @book.should_receive(:save!).and_raise(StandardError.new("Error saving the book"))
    call_create
    flash.now[:notice].should match(/.*error.*/)
  end
end

Notice how I said that I was going to use an invalid book but used the exact same (business-wise VALID) parameters? That’s the wonder of mocking and stubbing - the controller test doesn’t need to and shouldn’t [must not! if you're purist enough] know what is a valid book at all. It just needs to know how the controller should react given that the book model showed that it is not valid. Once again: the test to check if a book is been properly validated have already been tested on the model level specs.

So, let’s make the tests pass - shall we?

class BooksController < ApplicationController
  def create
    @book = Book.new params[:book]
    @book.save!
    flash[:notice] = "The book was saved successfully"
    render :text => ""
  rescue
    flash[:notice] = "There was an error saving the book"
    render :text => ""
  end
end

That will make all specs pass.

Notice that I didn’t mentioned anything about views - while rspec, not to mention the entire rails structure, gives you a pretty good support for testing them, I usually don’t do it on the unit test level [it probably is due to my lack of ability to do it properly, but the code simply tends to become really messy and not very readable]. So I try to leave it to cucumber.

As usual you can get the code used for this article on github. Please leave your impressions on the comments section.

This post is going to be the first of a series "Beyond The Buzzwords" of two (maybe three). This being a subject that has been getting some hype everywhere now doesn’t seem to be the kind of thing you would normally see here. We generally like to talk about the state of the art, and about things you can’t just google for - replicating knowledge like oh so many other blogs out there do, doesn’t particularly appeal to any of us.

But, since a great friend of mine asked for some very specific material about tests on rails, I decided to direct the effort to make something a little more presentable and put it here, so that anyone can benefit from it (and/or, most likely, criticize it).

• Intro
• pre-reqs
• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• END

rails --database=mysql bookstore
cd bookstore
rake db:create:all
rake db:migrate

script/generate cucumber

gedit features/register_new_books.feature &

Feature: Register new books
In order to make my bookstore expansible
As a bookstore owner
I want to be able to register new books

Scenario Outline: User register a new book successfully
Given I am on the new book register page
Then I should see "Title"
And I should see "Author"
And I should see "Rating"
And I should see "Synopsis"
When I fill in "book[title]" with "<book_title>"
And I fill in "book[author]" with "<book_author>"
And I fill in "book[rating]" with "<book_rating>"
And I fill in "book[synopsis]" with "<book_synopsis>"
And I press "Save"
Then I should not see "<book_title>"
And I should not see "<book_author>"
And I should not see "<book_rating>"
And I should not see "<book_synopsis>"
And I should see "successfully"
And the book with the title "<book_title>" should have been saved on the database

Examples:
| book_title          | book_rating | book_synopsis     | book_author         |
| the god delusion    | 9           | too soft          | richard dawkins     |
| the antichrist      | 9           | ubermesnch        | friedrich nietzsche |
| holy bible          | 0           | childish folklore | charlatans          |

rake features

Feature: Register new books
  In order to make my bookstore expansible
  As a bookstore owner
  I want to be able to register new books

  Scenario Outline: User register a new book successfully
    Given I am on the new book register page
    Then I should see "Title"
    And I should see "Author"
    And I should see "Rating"
    And I should see "Synopsis"
    When I fill in "book[title]" with "<book_title>:"
    And I fill in "book[author]" with "<book_author>:"
    And I fill in "book[rating]" with "<book_rating>:"
    And I fill in "book[synopsis]" with "<book_synopsis>:"
    And I press "Save"
    Then I should be on the new book register page
    And I should see "Title"
    And I should see "Rating"
    And I should see "Author"
    And I should see "Synopsis"
    And I should not see "<book_title>"
    And I should not see "<book_author>"
    And I should not see "<book_rating>"
    And I should not see "<book_synopsis>"
    And I should see "successfully"                    

    Examples:
      | book_title       | book_rating | book_synopsis  | book_author         |
CLUE  | the god delusion | 9           | too soft | richard dawkins     |
==>   Can't find mapping from "the new book register page" to a path.
==>   Now, go and add a mapping in
==>   /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb (RuntimeError)
==>   /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb:22:in `/^I am on (.+)$/'
CLUE  features/register_new_books.feature:7:in `Given I am on the new book register page'
      | the antichrist   | 9           | ubermesnch     | friedrich nietzsche |
      Can't find mapping from "the new book register page" to a path.
      Now, go and add a mapping in
      /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb (RuntimeError)
      /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb:22:in `/^I am on (.+)$/'
      features/register_new_books.feature:7:in `Given I am on the new book register page'
      | holy bible       | 0           | childish folklore    | charlatans          |
      Can't find mapping from "the new book register page" to a path.
      Now, go and add a mapping in
      /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb (RuntimeError)
      /home/macskeptic/workspace/rails/bookstore/features/support/paths.rb:22:in `/^I am on (.+)$/'
      features/register_new_books.feature:7:in `Given I am on the new book register page'

3 scenarios (3 failed)
60 steps (3 failed, 57 skipped)

gedit features/support/paths.rb &

when /the new book register page/
'/books/new'

No route matches "/books/new" with {:method=>:get} (ActionController::RoutingError)
(eval):2:in `/^I am on (.+)$/'
features/register_new_books.feature:7:in `Given I am on the new book register page'

gedit app/controllers/books_controller.rb &

class BooksController < ApplicationController

def new
render :text => ""
end

end

expected the following element's content to include "Title":
(Spec::Expectations::ExpectationNotMetError)
features/register_new_books.feature:8:in `Then I should see "Title"'

3 scenarios (3 failed)
60 steps (3 failed, 54 skipped, 3 passed)

gedit app/controllers/books_controller.rb &

render :text => "Title Synopsis Author Rating"

Could not find field: "book[title]" (Webrat::NotFoundError)
(eval):2:in `/^I fill in "([^\"]*)" with "([^\"]*)"$/'
features/register_new_books.feature:12:in `When I fill in "book[title]" with "<book_title>"'

3 scenarios (3 failed)
60 steps (3 failed, 42 skipped, 15 passed)

gedit app/views/books/new.html.erb &

<% form_for @book, :url => { :action => 'create' } do |f| -%>
<% field_set_tag 'New Book' do -%>
<p>
<%= f.label 'title'%><br />
<%= f.text_field 'title'%>
</p>
<p>
<%= f.label 'author'%><br />
<%= f.text_field 'author'%>
</p>
<p>
<%= f.label 'rating'%><br />
<%= f.text_field 'rating'%>
</p>
<p>
<%= f.label 'synopsis'%><br />
<%= f.text_area 'synopsis'%>
</p>
<p>
<%= f.submit 'Save' %>
</p>
<% end -%>
<% end -%>

script/generate model book title:string author:string rating:decimal synopsis:text
rake db:migrate

gedit app/controllers/books_controller.rb &

def new
@book = Book.new
end

No action responded to create. Actions: new (ActionController::UnknownAction)
/usr/lib/ruby/1.8/benchmark.rb:308:in `realtime'
(eval):2:in `/^I press "([^\"]*)"$/'
features/register_new_books.feature:16:in `And I press "Save"'

3 scenarios (3 failed)
48 steps (3 failed, 18 skipped, 27 passed)

gedit app/controllers/books_controller.rb &

def create
render :text => ""
end

def create
render :text => "successfully"
end

TODO (Cucumber::Pending)
features/register_new_books.feature:22:in `And the book with the title "<book_title>" should have been saved on the database'

3 scenarios (3 pending)
48 steps (3 pending, 45 passed)

gedit features/step_definitions/book_steps.rb &

Then /the book with the title "([^\"]*)" should have been saved on the database/ do |book_title|
Book.find_by_title(book_title).should_not be_nil
end

expected nil? to return false, got true (Spec::Expectations::ExpectationNotMetError)
features/register_new_books.feature:22:in `And the book with the title "<book_title>" should have been saved on the database'

3 scenarios (3 failed)
48 steps (3 failed, 45 passed)

gedit app/controllers/books_controller.rb &

def create
Book.create(params[:book])
render :text => "successfully"
end

Feature: Register new books
  In order to make my bookstore expansible
  As a bookstore owner
  I want to be able to register new books

  Scenario Outline: User register a new book successfully
    Given I am on the new book register page
    Then I should see "Title"
    And I should see "Author"
    And I should see "Rating"
    And I should see "Synopsis"
    When I fill in "book[title]" with ""
    And I fill in "book[author]" with ""
    And I fill in "book[rating]" with ""
    And I fill in "book[synopsis]" with ""
    And I press "Save"
    Then I should not see "<book_title>"
    And I should not see "<book_author>"
    And I should not see "<book_rating>"
    And I should not see "<book_synopsis>"
    And I should see "successfully"
    And the book with the title "<book_title>" should have been saved on the database

    Examples:
      | book_title       | book_rating | book_synopsis     | book_author         |
      | the god delusion | 9           | too soft          | richard dawkins     |
      | the antichrist   | 9           | ubermesnch        | friedrich nietzsche |
      | holy bible       | 0           | childish folklore | charlatans          |

3 scenarios (3 passed)
48 steps (48 passed)

Today’s post is about more than a simple punctual matter that I’ve come across at some moment in my day to day activities or on my restless nights of endless hacking.

Despise my overall remarkable programmer geekiness, I am first and foremost a philosopher. As a consequence to that, I love to I/O - big essays - so if you want to skip the background story and get right into the fun part, just jump straight to last tab below, ok? If you want to be even more hasty, you can go straight to the github project page and check it out there.

• Historical Motivation
• Understanding the Repository pattern
• Implementing the Repository

This remembers me of the good ol’ crazy nonsense errors from Oracle:

The screen is all blurred to maintain privacy because that’s my work PC.

I’ve got this pretty awesome message by trying to save a file during a build. That’s the kind of thing that makes a programmer day.

For the last few weeks, I’ve been working with PayPal API at my job. Besides the usual PayPal payment method, PayPal provides a direct credit card transaction solution too and it’s named Website Payments Pro. When we’re dealing with credit card numbers, we should be careful with fraudulent, illegal and false number cards. In my past experience, I’ve seen some credit card validators but never worried about how it was done. But this time, I had to take a look on how the validator works because of Discover credit card, which is not in use in Brazil.

A very quick search in the internet and I found the base algorithm to validate the most common credit card brands (Visa, MasterCard, Diners Club, Amex and Discover). It is the Luhn Algorithm. The Luhn Algorithm doubles every second digit from the rightmost of the provided number. For instance, if we have a number 529126, it will double the bolded digits. Then, it sums the doubled digits and undoubled digits ( (5×2) + 2 + (9×2) + 1 + (2×2) + 6) = 10 + 2 + 18 + 1 + 4 + 6 = (1 + 0) + 2 + (1 + 8 ) + 1 + 4 + 6 = 23 ). At last, it will verify if the resulted number is a multiple of 10.

So, let’s run into the code. The Luhn Algorithm implemented by me looks like the following:

public static bool LuhnAlgorithm(string creditCardNumber)
{
    bool alt = false;
    int sum = 0;

    if (String.IsNullOrEmpty(creditCardNumber))
    {
        throw new ArgumentNullException("creditCardNumber", String.Format(CultureInfo.CurrentCulture, "the credit card number can't be null!"));
    }

    if (!Regex.IsMatch(creditCardNumber, @"^\d*$"))
    {
        throw new ArgumentException("Invalid Credit Card Number", "creditCardNumber");
    }

    foreach (char digit in Reverse(creditCardNumber))
    {
        int digitToSum = int.Parse(digit.ToString());
        if (alt)
        {
            digitToSum = digitToSum * 2;
            if (digitToSum > 9)
            {
                digitToSum -= 9;
            }
        }

        sum += digitToSum;
        alt = !alt;
    }

    return (sum % 10 == 0);
}

The Reverse method is:

public static string Reverse(string s)
{
    char[] charArray = s.ToCharArray();
    Array.Reverse(charArray);
    return new string(charArray);
}

Now that we have the credit card number validator, we should check if the number is valid for the provided brand. To accomplish this task, we will use Regular Expressions. The table below shows how each brand implements their credit card numbers:

And that’s it. Just validates the credit card string number with the regular expression after the Luhn Algorithm and you will have a reliable credit card validator. The complete method will be like this:

public static bool ValidateCreditCardNumber(string creditCardNumber, string creditCardType)
{
    if (!LuhnAlgorithm(creditCardNumber))
    {
        return false;
    }

    switch (creditCardType)
    {
        case "visa":
            return ValidateVisa(creditCardNumber);
        case "masterCard":
            return ValidateMasterCard(creditCardNumber);
        case "diners":
            return ValidateDinersClub(creditCardNumber);
        case "amex":
            return ValidateAmex(creditCardNumber);
        case "discover":
            return ValidateDiscover(creditCardNumber);
        default:
            return false;
    }
}

The discover validator method:

public static bool ValidateDiscover(string creditCardNumber)
{
    return (Regex.IsMatch(creditCardNumber, @"^6011[\d]{12}$"));
}

Imagine the following scenario: You have a project that you just developed in your local machine and want to deploy it into the CI (Continuous Integration) and approval environments. In this project, there is a configuration file (app.config) that contains a few settings, for instance, connection strings and log file directory.

Quite common isn’t it? So, how do you handle with the annoying issue of changing your app.config file for all these environments?

Editing the configuration file in each environment doesn’t seem to be a smart solution. During the development, we can add further settings into the app.config. Updating the config file later (during the deployment) for every environment is a hard and unreliable manner to do this because we can miss some changes.

Another choice that I’ve seen consists in having a copy in your project for each environment. Well, this is much better. We will have app.config, app.config.ci, app.config.approval and app.config.production to satisfy our environments. So, whenever we need to add or change any settings, we can edit all these config files during the development phase. To deploy, just rename the correct file to app.config and that’s it. But the problem that I see in this solution is that our SCM will run crazy with all the renamings.

For example: rename app.config to app.config.local and app.config.ci to app.config. SCM will tell you that app.config has been modified, app.config.local has been created and app.config.ci has been deleted. What a mess!

Another issue of this solution is that it doesn’t help us when we want automatated deployment. It depends on manual editing of the config files or a dependency on a script to do the job.

To avoid these painful processes, we can use the project’s configurations and after build tasks set in .csproj file. I will explain in the following steps:

• 1st Step
• 2nd Step
• 3rd Step

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <connectionStrings>
    <add name="applicationConnection" connectionString="Data Source=localServer..." />
  </connectionStrings>
</configuration>

<configuration>
  <connectionStrings>
    <add name="applicationConnection" connectionString="Data Source=approvalServer..." />
  </connectionStrings>
</configuration>

<configuration>
  <connectionStrings>
    <add name="applicationConnection" connectionString="Data Source=ciServer..." />
  </connectionStrings>
</configuration>

<configuration>
  <connectionStrings>
    <add name="applicationConnection" connectionString="Data Source=productionServer..." />
  </connectionStrings>
</configuration>

Today I’m going to show some very short snippet about posting files with ruby, and receiving them in a rails controller.

For all examples I’ll be using the rest-client gem (”sudo gem install rest-client”).

The fist thing we’re going to do is to implement a very basic file post in ruby - there is basically two methods:

1. You can post the contents of the file straight to the request body (I’m going to call it the “raw way”);
2. You can pass the file contents as a parameter inside your request, like any other (I’m going to call it the “pretty way”).

One method is not necessarily better than the other, how you should do it depends a lot more on how your target service is implemented.

Posting a file, the “pretty way”:

PRETTY_UPLOAD = "http://localhost:3000/files/upload_pretty/pretty_file.txt"

def self.post
    pretty_resource = RestClient::Resource.new PRETTY_UPLOAD

    pretty_file = "./pretty_file.txt"

    File.open pretty_file, "wb" do |file|
      file.write "some random pretty content"
    end

    pretty_resource.post :file => File.read(pretty_file)
end

Posting a file, the “raw way”:

RAW_UPLOAD = "http://localhost:3000/files/upload_raw/raw_file.txt"

def self.post
    raw_resource = RestClient::Resource.new RAW_UPLOAD

    raw_file = "./raw_file.txt"

    File.open raw_file, "wb" do |file|
      file.write "some random raw content"
    end

    raw_resource.post File.read(raw_file)
end

Now, getting a file - since there is basically just one way to get it, I’ve made just one method - getting a file on ruby:

DOWNLOAD = "http://localhost:3000/files/download/raw_file.txt"

def self.get
    resource = RestClient::Resource.new DOWNLOAD

    downloaded_file = "./downloaded_file.txt"

    response = resource.get
    # you can access the headers (response.headers) or the
    # http response (response.net_http_res) if you need to

    File.open downloaded_file, "wb" do |file|
      file.write response.to_s
    end
end

That’s pretty much all you need on the client side (reading the contents of a regular http request should be no different at all than reading an attached file).

Time to go to the server side, shall we? Here good old rails kicks ass per se.

All I needed to do was to set up a custom route (just to make things more clear):

map.files ':controller/:action/:name.:extension'

Then, for the controller, I’ve set up two methods to receive the posted file - pay attention to the slightly different approach for the “pretty way” and the “raw way” of posting a file.

Receiving a file, the “pretty way”:

def upload_pretty
    file_name = "#{params[:name]}.#{params[:extension]}"
    file_contents = params[:file]
    File.open "tmp/#{file_name}", "wb" do |file|
      file.write file_contents
    end

    render :text => "ok"
end

Receiving a file, the “raw way”:

def upload_raw
    file_name = "#{params[:name]}.#{params[:extension]}"
    file_contents = request.raw_post
    File.open "tmp/#{file_name}", "wb" do |file|
      file.write file_contents
    end

    render :text => "ok"
end

I also provided a method for the client to download back the files, so that you can check on the contents to see that it went through flawlessly:

def download
    file_name = "#{params[:name]}.#{params[:extension]}"
    send_file "tmp/#{file_name}"
    # you can also use: send_data File.read("tmp/#{file_name}")
end

And that’s basically it, as simple as it can be.

As usual, you can download the sample code clicking here.

That’s a very quickly put together piece of code which, most likely, can be greatly improved - but I think it is just good enough to show the basics of how to get and post files on ruby and rails.

Criticism is always welcome.

A quick tip for those who want to get a grasp on what CouchDB actually is before actually going to the trouble of setting up the whole environment (Erlang + CouchDB installation process seems to be a pain on Windows).

A friend of mine, who got all hyped about it when I told him about CouchDB sent me a link with an online interactive interpreter for people to toy with it. You can access it here.

To be able to actually do anything with it though, you’re going to need some knowledge of functional programming, specially map and reduce concepts.