Once in the web browser, the data has to be parsed and split up into different sentences based on what the user wants to do with the data.  Once the data is split into sentences it’s appended to divs that show the sentences in the web browser.  Some of these sentences have to be clickable, they must respond to a “click” event coming from the user.  This is completely ordinary in most JavaScript web apps.  The user clicks, the browser responds.  Imagine my surprise when my sentences weren’t responding to the click input.

I wasn’t surprised for very long, however.  By looking at how I prepared the sentence in the JavaScript code made it pretty obvious what was going on.

data[index] = data[index] + ". <span class=\"my_class\">" + choices[choiceIndex++] + "</span>";

This created the sentence that was to be clickable. It’s just string data that creates a span with a class. This is something jQuery can find by doing $(“.my_class”). Once I have all the spans with that class I can add a click event to them. Well, that’s true, but those spans have to be DOM objects before jQuery can find them.

The way I was doing it, those spans were just string data. Sure, the browser displayed them with the correct style but jQuery was unable to find them because they were not internalized as DOM objects. Opening a JavaScript console with Google Chrome would allow me to run the same code to make the spans respond to click events and it would actually work. Chrome’s console reads the DOM after the page has been rendered and creates the DOM objects based on the rendered page when the spans are in place. This is no good to me. I can’t tell my customer to tell his customers to open a JavaScript console and run this cryptic command after loading the page.

In order to get the behavior we want we have to create DOM objects using jQuery so jQuery can then find these objects to add the click behavior to them. Rather than creating spans as string data we use the jQuery function to create a DOM element with the correct class and text.

elm = $("<span class=\"my_class\">" + choices[choiceIndex++] + ". </span>");
elm.click(function(){
                  alert("Hey! You got the right answer!");
                  document.location = "http://localhost:3000";
                });

The jQuery function, $( ), first looks for elements based on the class, id or attribute selector passed in to it. If there is no selector then the function looks for any tags in the string passed in to it. If there are tags, in our case span tags, jQuery creates the appropriate DOM element based on the content of those tags! This is great! Now I can pass in my string data and have jQuery return a DOM element that I then bind to the click function specified.

Adding the click function later also works now.

$(".my_class").click(function() {
                  alert("Hey! You got the right answer!");
                  document.location = "http://localhost:3000";
                });

I’m happy with the way I can build a DOM element using the jQuery function. In order for jQuery to find the objects we look for those objects have to be DOM elements, not just string data appended to a div. DOM elements respond to events, strings do not.

Last night I wrote a user authorization interceptor that makes sure there is a user associated with each resource request that requires it. I’m structuring most of my new web apps in such a way that user authorization is required for almost all actions.  I had to make a choice of how to enforce user authorization in the app.  The two choices were between a Servlet filter and a HandlerInterceptor.

A Servlet Filter is part of the Java EE Servlet package.  Most of my Java web projects use Servlet Filters in some way so I wasn’t immediately opposed to using one to make sure there is a logged in user associated with a request.  Because I wanted possible errors to be properly rendered in my different view types using Spring I decided to use a HandlerInterceptor.

A HandlerInterceptor is a Spring interface that is pretty much analogous to a Servlet Filter in terms of structure, though it’s a little more focused in purposed.  The HandlerInterceptor is mostly concerned with text-based content, where Filters can be applied to any content type.  Filters are also more appropriate for setting headers and gzipping responses.  The Handler Interceptor is targeted for application logic.

This interceptor only checks to see that there is a user object associated with an resource request before passing it on to the handler (a controller).  In practice this may include more detailed authorization checks but for the example just checking for a user is fine.

@Component
public class UserAuthorizationInterceptor extends HandlerInterceptorAdapter {

  private static final String UNAUTHORIZED_MSG = "You are not logged in.  You must log in or supply an API token.";

  @Override
  public boolean preHandle(HttpServletRequest request,
                        HttpServletResponse response,
                        Object handler) throws Exception {

    String uri = request.getRequestURI();
    User user = (User) request.getSession().getAttribute("user");

    if (user != null || uri.indexOf("login") != -1) {
      return true;
    } else {
      response.sendError(HttpServletResponse.SC_FORBIDDEN, UNAUTHORIZED_MSG);
      return false;
    }
  }
}

Initially I wanted any error messages to be rendered by my Atom, RSS and JSON views. Any error message generated by the application should come back to the user in the requested data format. But this is a RESTful app. The REST philosophy already addresses the only error message that should come out of an authorization check with HTTP status codes. The only error message that should come out of this interceptor is an “unauthorized” message. HTTP supplies the 401 status code to indicate a user is unauthorized.

The implication of using the 401 code is that the user should use HTTP authentication, either basic or digest. That’s not appropriate for an application using OpenID and API tokens for user authentication. Instead the 403 status code is more appropriate. This means the client is forbidden from accessing the requested resource. The server understood the request but the client is not allowed to access the resource, which is exactly the case when there is no logged in user associated with the request.

Because HTTP already provides plenty of status codes for things that can go wrong we should rely on those codes when building RESTful applications. There is no reason to supply an application-generated error message when the protocol supplies everything we need to deal with the problem. The REST philosophy actually makes it much easier to write web apps because we’re using HTTP as it is intended to be used which takes a lot of responsibility off of our application code.

Why would I want JSON out of the app instead of HTML?  Interoperability is one reason.  Now instead of being bound to one web app, my own, my data can be shuttled to other apps in a commonly understood notation without screen scraping.  Of course we can also use Atom and RSS for data that can be massaged into those formats with the ContentNegotiatingViewResolver as well.  For stuff that can’t coerced into standardized XML, JSON is a great choice.

If you don’t know what JSON is, it’s basically a JavaScript text representation of a map that drills down into your object hierarchy if you have one. Let’s say I want to get my user information. The JSON representation is:

{ "firstname":"Anthony", "lastname":"Chaves", "userid":"123456", "address":{ "street":"A Fake Street", "city": "Bradford", "state":"MA" } }

This JSON is valid JavaScript and parsed by the library of your choice. The first three fields are just string data. The address field is another map that contains data about my address. This is produced because my Java class User has a field of class Address. Address contains the street, city and state fields.

To get the JSON output we should use a MappingJacksonJsonView. This view uses the Jackson library to map our Java objects to JSON. We need the Jackson core and mapper jars on our classpath to make this view work. I just copied them into my WEB-INF/lib directory.

It should be noted that I could not get any combination of configuration and Jackson jar files to work using Glassfish 2.1.1. Deploying the app failed due to a java.lang.VerifyError with the message “Cannot extend a final class.” Duh. The same app worked right from the start on Tomcat 6.0.24.

Because we want to preserve the functionality of the web app and its HTML output we can’t cut out the UrlBasedViewResolver completely. We want the app to function as normal when we get requests for .html files but return JSON when we get requests for .json files. So user.html would be used to get the HTML output of a user page and user.json would be used to get the above JSON output for a different app.

Spring 3.0 has a ContentNegotiatingViewResolver that does just this. Based on the client accept header and the file extension, this view resolver determines the best view resolver to pass the request on to after the controller does its processing.

<bean class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver">
  <property name="mediaTypes">
    <map>
      <entry key="html" value="text/html"/>
      <entry key="json" value="application/json"/>
    </map>
  </property>
  <property name="viewResolvers">
    <list>
      <bean class="org.springframework.web.servlet.view.UrlBasedViewResolver">
        <property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
        <property name="prefix" value="/WEB-INF/jsp/"/>
        <property name="suffix" value=".jsp"/>
      </bean>
    </list>
  </property>
  <property name="defaultViews">
    <list>
      <bean class="org.springframework.web.servlet.view.json.MappingJacksonJsonView">
        <property name="prefixJson" value="true"/>
      </bean>
    </list>
  </property>
</bean>

For text/html content the ContentNegotiatingViewResolver sends requests on to the old UrlBasedViewResolver after the controller method returns. For application/json or application/javascript requests the ContentNegotiatingViewResolver passes the request on to the MappingJacksonJsonView. This view parses the object tree into JSON and gives us the output we want.

The object tree is based on the objects in the Spring Web MVC model. This means we have to add them to a ModelMap object in the controller. In an HTML-based web app we might store data in the HttpSession object. For JSON we need it in the ModelMap. Let’s say we’re adding a tag to something.

@RequestMapping(method=RequestMethod.GET)
public String getBookmarksWithTag(@RequestParam(value="tag") String tag, HttpSession session, ModelMap model) {
  User user = (User) session.getAttribute("user");

 doSomethingUseful(user);

  model.addAttribute(user);
  return "tags";
}

By placing the User object into the ModelMap, Spring has a reference to it when it comes time to make some JSON. We still return a string, “tags”, so the UrlBasedViewResolver still returns the same jsp for text/html content. After this controller method returns, Spring takes the result and sends it to the ContentNegotiatingViewResolver. The “tags” return value is not used if the request is sent to the MappingJacksonJsonView. It has no use for jsps. If the request were for text/html the “tags” string would be used by the UrlBasedViewResolver.

Like I said, I’m happy with the new REST support in Spring 3.0 Web MVC. It’s certainly lagging behind Rails in trendy features but it’s far more flexible overall. There is a certain “style” to writing web apps that Rails guys have. I’m convinced it’s just as easy to use this style in Spring as it is to do it in Rails but the huge amount of extraneous documentation and classes in Spring makes it more difficult than it should be to get down to business. I’m not making a statement about the Spring framework itself, it’s certainly possible to do everything I want and need. I just haven’t seen a good style guide or cookbook for RESTful web apps. Maybe it’s because some of the features are still so new, being just added to the 3.0 branch. Maybe we just haven’t found the right idioms yet.

Let’s talk about user authentication in web apps. When a web app keeps track of my data, whether it’s bookmarks, book orders or bank data, I expect to log in with a reasonably secured username and password. If I’m authenticated the web app sets up a cookie to track my session. There are two parts to a session, the client side – a cookie is placed in my browser with a session id, and the server side – the app server uses a map with my user data keyed by my session id stored in the cookie sent back to me.

Once my browser has a session cookie it sends that cookie back to the web app with every HTTP request I make. The app server uses the session id in that cookie to load my user data and, say, add a book to my shopping cart. My user data is updated in the session and the web page I requested is sent back to the browser. The next time I make a request for a web page the session cookie is sent back to the web app and again my user data is loaded from the session map. Though this approach violates a strict RESTful architecture it’s the best we’ve got for now.

As long as I keep requesting web pages while my session is active I keep delaying the session timeout on the app server. A session typically times out on an app server due to the cost of keeping all user data in memory in a session map. With limited memory we have to timeout inactive user sessions so that the app server can serve active users more effectively (i.e. without crashing). If I wait 5 minutes between web requests I’m likely to find my bank session timed out and I have to log in again. When ordering books that timeout period may be 30 minutes or longer. It seems like the more valuable the data, the shorter the session timeout. This is to prevent another user from coming in and reusing a session tracking cookie for “bad things” like transferring all my money to his account.

This brings up the point that though I still have a session id in my browser, the session on the server side no longer exists. What if I wasn’t done shopping for books and computer parts? I have to log in again and start a new session – my browser gets a new cookie with a new session id and the app server starts a new session keyed by my session id. My user data, hopefully my up-to-date shopping cart, is loaded into my new session and I may continue shopping with another 30 minute or so timeout. If I keep requesting web pages my session timeout keeps moving to expire 30 minutes after my last page request. I say 30 minutes but it could be any arbitrary period.

Expiring user sessions is a good practice because it forces users to authenticate themselves every so often. One user doesn’t always use one browser and one browser doesn’t always serve one person. But what if that statement is close enough to true that it might as well be? What if I’ve got 5 browsers where I’m the only user? Sometimes I don’t want to be required to use the login form every time I use a web app.

GMail can remember my login for two weeks. Yahoo! Mail can, too. I don’t have to log in every time I got to those web apps. I wanted the same functionality for a Java-based web app I wrote and I couldn’t find anything to do something similar through the search engines. The Java packages I found stored the user’s login information in the cookie in plain text. The next time the user goes to the web app the form data is auto-populated by the plain-text username and password stored in the cookie. This is a very bad “security” practice and the user *still* needs to visit a login page.

Rather than storing a username and password in a cookie we can do a little better. We can store a “token” in the cookie that is associated with the user. This token does not store the user’s username or password, either in plain-text or encrypted. Instead the token is generated by the web app and placed in a cookie that does not track the user’s session. This means the web app sends one more cookie, the login token, in addition to the session tracking cookie.

Any time after a user is authenticated we can set the login token cookie. This could be as part of the login process if a login form has a “remember me” check box or at the user’s explicit request any time after authentication. How does this work in practice? Let’s look at some code. First we’ll look at the TokenService class.

@Service
public class TokenService {

  @PersistenceUnit(unitName="bookmarksPU")
  EntityManagerFactory emf;

  public String setupNewLoginToken(User user) {
    PersistentLoginToken tonaken = new PersistentLoginToken();
    EntityManager em = emf.createEntityManager();

    em.getTransaction().begin();
    User u = em.find(User.class, user.getId());
    token.setUser(u);
    em.persist(token);
    em.getTransaction().commit();

    return token.getId();
  }

  public User loginWithToken(String tokenId) {
    EntityManager em = emf.createEntityManager();
    em.getTransaction().begin();
    PersistentLoginToken token = (PersistentLoginToken) em.find(PersistentLoginToken.class, tokenId);

    User user = null;
    if (token != null) {
      user = token.getUser();
      em.remove(token);
      em.getTransaction().commit();
    } else {
      em.getTransaction().rollback();
      //TODO this is a forgery attempt
      throw new RuntimeException("Attempted login token cookie forgery");
    }
    return user;
  }
}

TokenService#setupNewLoginToken is called when we have a User object – sometime after authentication or when the user requests it. TokenService#loginWithToken is called in a servlet filter before an HTTP request even makes it to our code. In order for this to work we need to tie a login token to a user. We do that through PersistentLoginToken.

@Entity
@Table(name="persistentLoginTokens")
public class PersistentLoginToken {
  @Id
  @GeneratedValue(strategy=GenerationType.AUTO, generator="uuid-hex")
  private String id;

  @ManyToOne
  private User user;

  public void setUser(User user) {
    this.user = user;
  }

  public User getUser() {
    return user;
  }

  public void setId(String id) {
    this.id = id;
  }

  public String getId() {
    return id;
  }
}

The table required (or generated) by this entity has an id column and a user_id column. We have our JPA provider generate a 128-bit UUID to serve as the token id. The user id is obtained from the user associated with this token. Notice how we do not constrain the number of valid tokens a user can have at any particular time. This means I can have valid login tokens across 5, 10 or 100+ browsers. Each browser would get a new unique token when I log in using that browser.

Back to the setupNewLoginToken method – this works by creating a new PersistentLoginToken object and associating it with a user. When it PersistentLoginToken object is saved the JPA provider generates its UUID and makes an entry in the database. Now that the PersistentLoginToken has a generated UUID we put that UUID into the loginToken cookie and add that cookie to the HttpResponse object. We set the cookie’s expiration time to 1 week, though this can be set to whatever your web app requires.

This login token cookie is sent back to the browser at the end of this response. The browser then sends this loginToken cookie to the web app on every subsequent request. Though this is useless when I have an active session, I really want this cookie around when my session expires on the server side or my session tracking cookie expires on the browser side. Let’s see what happens when I don’t have an active session and I visit the web app.

@Component
public class PersistentLoginFilter implements Filter {

  @PersistenceUnit(unitName="webappPU")
  EntityManagerFactory emf;

  @Override
  public void doFilter(ServletRequest request,
                       ServletResponse response,
                       FilterChain chain) throws IOException, ServletException {

    HttpServletRequest httpRequest = (HttpServletRequest) request;
    HttpServletResponse httpResponse = (HttpServletResponse) response;
    Cookie tokenCookie = getCookieByName(httpRequest.getCookies(), "loginToken");

    HttpSession session = httpRequest.getSession();
    User user = (User) session.getAttribute("user");

    if (user == null && tokenCookie != null) {
      user = tokenService.loginWithToken(tokenCookie.getValue());
      String tokenValue = tokenService.setupNewLoginToken(user);

      httpRequest.getSession().setAttribute("user", user);
      tokenCookie.setMaxAge(0);
      httpResponse.addCookie(tokenCookie);

      tokenCookie = new Cookie("loginToken", tokenValue);
      tokenCookie.setPath("/bookmarks");
      tokenCookie.setMaxAge(168 * 60 * 60);
      httpResponse.addCookie(tokenCookie);
    }

    chain.doFilter(httpRequest, httpResponse);
  }
// other methods omitted
}

The doFilter method looks for a User associated with the current web session. The absence of a User and the presence of a login token cookie indicate it’s time to perform a user lookup and login based on the token cookie. After finding the user based on a valid token the filter gives the user a new login token that is valid for another week. This may or may not be ok for your web app. I just didn’t feel like writing the code to set expiration of the new cookie to the remaining time on the original cookie.

With our User in hand, we set it on the current session and let the request finish processing. All this code is available at http://github.com/anthonychaves/bookmarks under the GPLv3 license. Feel free to modify it, use it and submit feedback. I know it’s not as generic as it could be – feel free to use it as a template for your own code.

But every ORM framework will tell you that the “many” side of the relationship should be the owning side and the “one” side is the inverse. Why? Let’s look at some Java class definitions using JPA.

@Entity
public class Customer implements Serializable {
	@Id
	public String id;

	public String name;
	public String emailAddress;

	@OneToMany
	List<Order> order = new ArrayList<Order>();

	@Version
	public int version;

}

A Customer has a one-to-many relationship with Order.

@Entity
@Table(name="orders")
public class Order implements Serializable {
	@Id
	public String id;

	@ManyToOne
	Customer customer;

}

And the Order references the customer to which it belongs. Here is our bi-directional relationship. But we don’t know why the Order is the owning-side of the relationship yet. If we were to create a database schema based on these classes we would get three tables:

mysql> describe Customer;
+--------------+--------------+------+-----+---------+-------+
| Field        | Type         | Null | Key | Default | Extra |
+--------------+--------------+------+-----+---------+-------+
| id           | varchar(255) | NO   | PRI | NULL    |       |
| emailAddress | varchar(255) | YES  |     | NULL    |       |
| name         | varchar(255) | YES  |     | NULL    |       |
| version      | int(11)      | YES  |     | NULL    |       |
+--------------+--------------+------+-----+---------+-------+

mysql> describe customer_orders;
+-------------+--------------+------+-----+---------+-------+
| Field       | Type         | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| CUSTOMER_ID | varchar(255) | YES  | MUL | NULL    |       |
| ORDER_ID    | varchar(255) | YES  | MUL | NULL    |       |
+-------------+--------------+------+-----+---------+-------+

mysql> describe orders;
+-------------+--------------+------+-----+---------+-------+
| Field       | Type         | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| id          | varchar(255) | NO   | PRI | NULL    |       |
| CUSTOMER_ID | varchar(255) | YES  | MUL | NULL    |       |
+-------------+--------------+------+-----+---------+-------+

The tables that map to our entities look fine. We also get a join table to map from Customer to Order. Even though the Order class can refer directly to its Customer the Customer must look at the join table to get to its Orders.

The SQL query generated by the ORM to get the Orders associated with a customer would join the customer_orders table to get a list of order ids associated with that customer, then join the orders table on those order ids. There is a more direct way we can get there, especially since the orders table already references its customer id. We need to indicate to the JPA runtime that the Customer can reference a column on the orders table. We do that with the mappedBy attribute in @OneToMany.

@Entity
public class Customer implements Serializable {
	@Id
	public String id;

	public String name;
	public String emailAddress;

	@OneToMany(mappedBy="customer")
	List<Order> order = new ArrayList<Order>();

	@Version
	public int version;

}

When we add the mappedBy attribute on the @OneToMany annotation the JPA runtime knows that there is a field in the related object named customer. The column this field maps to is the appropriate foreign key to use to find associated Orders. Creating the database schema with this change to the Customer class @OneToMany annotation we get only two tables.

mysql> describe Customer;
+--------------+--------------+------+-----+---------+-------+
| Field        | Type         | Null | Key | Default | Extra |
+--------------+--------------+------+-----+---------+-------+
| id           | varchar(255) | NO   | PRI | NULL    |       |
| emailAddress | varchar(255) | YES  |     | NULL    |       |
| name         | varchar(255) | YES  |     | NULL    |       |
| version      | int(11)      | YES  |     | NULL    |       |
+--------------+--------------+------+-----+---------+-------+
4 rows in set (0.01 sec)

mysql> describe orders;
+-------------+--------------+------+-----+---------+-------+
| Field       | Type         | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| id          | varchar(255) | NO   | PRI | NULL    |       |
| CUSTOMER_ID | varchar(255) | YES  | MUL | NULL    |       |
+-------------+--------------+------+-----+---------+-------+
2 rows in set (0.01 sec)

Now the JPA runtime knows that the customer_id column on the orders table can map between an Order and a Customer. The owning-side of a bidirectional relationship is the one with the foreign key column on the table – the orders table. The orders table owns the relationship because it is responsible for the column that maps between Customer and Order. The “owning-side” is not a statement about a Customer has many Orders, the logical relationship between entities. It is a statement about which underlying table is responsible for the mapping data between two tables and the entities mapped by those tables.

I was just reminded of my initial questions about why we use these terms when I wrote a @OneToMany(mappedBy=”…”) a few days ago. As always I’m open to comments.

Financially, for a small scale production or testing platform using the Amazon Web Services makes a lot of sense for a company whose core business is not IT-centric. Running a couple m1.small EC2 instances and paying for a backup to S3 or EBS is cheaper than purchasing a box and running the app in colo.

Since the start of the AWS platform I had the opinion that, as one starts using more and more EC2 instances and S3 storage space, there comes a point where it would be cheaper to bring the IT platform in house and hire a staff to run it instead of running on AWS forever. I have no idea where that point is, nor do I know of anyone with credibility who does. I thought the dollar amount where in-housing is cheaper is quite high.

I say those things in the past tense. At the risk of being accused of falling victim to Amazon propaganda, after reading the Economics of the AWS Cloud paper I think the expense of bringing a production app in-house for financial reasons alone is too great to overcome the benefits of using Amazon web services. What Amazon provides in terms of reliability, redundancy, management and scale can not be overcome unless you plan to compete with Amazon. This completely ignores in-housing due to compliance and auditing. AWS is not an option in that case.

The paper makes the argument that we can hit closer to 100% server utilization than an owned IT infrastructure. Though I’m not sure I buy this argument, idle CPU and unused memory are idle wherever they are, using a pay-as-you-go service implies someone might be more aware of hardware utilization because using more costs more in EC2. I guess the comparison is owning 10 boxes at 5% utilization vs. renting 2 EC2 instances at 60% utilization. Over 5 years renting EC2 instances at full price is cheaper than the capital expense of buying those 10 boxes.

The Power Efficiency and Enabling Redundancy sections of the paper are particularly important. Running a data center costs more than just the price of the computers in it. Power and cooling isn’t free. Rack space isn’t free. The investments Amazon can afford to make in improving power efficiency and data center design is much greater than most other data center owners can afford. If you can afford to make this investment you’re already operating at Amazon-scale – why aren’t you competing with them?

Based on the go-big-or-go-home data center, who should build data centers? CDNs, hosting providers, colo facilities and business that are subject to regulation? Is that it? As someone who has been using AWS and other hosting providers for years for small customers and doing hardware recommendations for existing, poorly designed, non-regulated company data centers for large customers, I’m partial to the AWS/hosted approach if there is not already hardware that can do the job on site. Hardware procurement in large companies is a nightmare and hasn’t changed since I started doing this.

So where are we headed with AWS? Are new tech startups going to forego hardware purchases and use AWS as their infrastructure? In the last year I have worked with a lot of people making that choice. What about existing small businesses? I haven’t done a lot of work where people are migrating away from their colo’d software and I don’t expect them to, at least until the next upgrade cycle. Upgrade cycle – that’s another thing Amazon handles “in the cloud” for us. Certainly a small business needs to be aware of the AWS option and I don’t have a lot of experience with the IT companies that small businesses out-source to.

Of course I expect (non-regulated) big business to continue building poorly designed data centers based on use-it-or-lose-it budgets. “Our team has 30 boxes sitting idle and we need to order 10 more!”

These were just some of my thoughts while reading the paper. Leave a comment with any feedback or your own thoughts on the Economics of the AWS Cloud paper.

Let’s start with the <jee:jndi-lookup/> bean. Since a RESTful API probably runs in a web container we need to look up a data source, persistence unit or persistence context. We define the persistence unit in WEB-INF/classes/META-INF/persistence.xml.

<?xml version="1.0"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
  <persistence-unit name="bookmarksPU" transaction-type="RESOURCE_LOCAL">
    <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
    <non-jta-data-source>jdbc/bookmarks</non-jta-data-source>
    <class>net.anthonychaves.bookmarks.models.User</class>
    <class>net.anthonychaves.bookmarks.models.Bookmark</class>
  </persistence-unit>
</persistence>

The bookmarksPU persistence unit is registered with the container when the webapp is deployed. It looks up the jdbc/bookmarks datasource and uses it for access to the database. Setting up this datasource is up to you based on your container.

The bookmarksPU is also bound to a JNDI name, persistence/bookmarksPU. We can inject this persistence unit into our webapp in the form of an EntityManagerFactory after registering a bean in our Spring container. We do this in our Spring configuration file by looking up the persistence unit in JNDI.

<jee:jndi-lookup id="bookmarksPU" jndi-name="persistence/bookmarksPU"/>

In our service layer we have a class UserService.

@Service
public class UserService {

  @PersistenceUnit(unitName="bookmarksPU")
  EntityManagerFactory emf;

  public void saveUser(User user) {
    EntityManager em = emf.createEntityManager();
    em.getTransaction().begin();
    em.persist(user);
    em.getTransaction().commit();
  }

  public User findUser(String name) {
    EntityManager em = emf.createEntityManager();
    Query query = em.createQuery("select u from User u where u.name = ?1")
                    .setParameter(1, name);
    em.getTransaction().begin();
    User user = (User) query.getSingleResult();
    em.getTransaction().rollback();
    return user;
  }
}

Notice two things about this class: it is annotated with the org.springframework.stereotype.Service annotation and its EntityManagerFactory is annotated with the javax.persistence.PersistenceUnit annotation. We want Spring to deal with both of these annotations. We want the component, the class annotated by @Service, registered as a Spring bean without doing it manually in XML. We also want Spring to inject an instance of EntityManagerFactory bound to the persistence/bookmarksPU persistence unit.

One of the nice things about Spring is that we can rely on these annotations so we don’t have to create long XML configuration files. We still need the XML config to tell Spring which classes it should examine for these annotations. Enter the <context:annotation-config/> and <context:component-scan/> beans.

Each of these beans implicitly creates instances of classes that implement the BeanPostProcessor interface. The post processor created by the <context:annotation-config/> bean that is most important to our case is the PersistenceAnnotationPostProcessorBean. This bean finds the bookmarksPU bean created when we performed the JNDI lookup and injects it into the emf field annotated with @PersistenceUnit.

The <context:annotation-config/> bean takes care of the javax.persistence annotation but it does not create a bean definition for the UserService class. To do that we need the <context:component-scan/> bean. This bean scans the specified base package for classes annotated with @Component and its subclasses, which includes @Service. By annotating the UserClass as a @Service we are spared from configuring it by hand in XML.

The <context:component-scan/> bean only searches for annotations relevant to the current application context. In this case we must define the service layer outside of the *-servlet.xml WebApplicationContext. The @Controller annotation is valid in a WebApplicationContext where a @Service annotation is not. We should instead keep our service layer configuration separate from the webapp configuration. In services.xml we have our services defined.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:jee="http://www.springframework.org/schema/jee"
       xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-3.0.xsd

http://www.springframework.org/schema/context

http://www.springframework.org/schema/context/spring-context-3.0.xsd

http://www.springframework.org/schema/jee

                           http://www.springframework.org/schema/jee/spring-jee-2.5.xsd">

  <jee:jndi-lookup id="bookmarksPU" jndi-name="persistence/bookmarksPU"/>

  <!-- here we need component-scan for the services and annotation-config for the persistence unit -->
  <context:component-scan base-package="net.anthonychaves.bookmarks"/>
  <context:annotation-config/>

</beans>

A WebApplicationContext inherits all the bean definitions from any imported ApplicationContexts. If we import the services.xml file in our *-servlet.xml file we will inherit the fully wired UserService bean created by the BeanPostProcessor beans in that ApplicationContext. We have a controller that needs an instance of UserService.

@Controller
@RequestMapping("/user")
public class UserController {

	@Autowired
	UserService userService;

	@Autowired
	ImageCaptchaService icservice;

	@RequestMapping(value="/new", method=RequestMethod.GET)
	public String newUser(ModelMap model) {
		model.addAttribute(new User());
		return "user_new";
	}

	@RequestMapping(method=RequestMethod.POST)
	public String createUser(@ModelAttribute("user") User user,
							 HttpSession session,
							 @RequestParam("j_captcha_response") String captchaResponse) {

		boolean validResponse = icservice.validateResponseForID(session.getId(), captchaResponse);
		if (validResponse) {
		  userService.saveUser(user);
		  session.setAttribute("user", user);
			return "redirect:/b/user";
		} else {
			return "redirect:/b/user/new";
		}
	}

	@RequestMapping(method=RequestMethod.GET)
	public String user(HttpSession session) {
	  if (session == null || session.getAttribute("user") == null) {
	    return "redirect:/b/user/new";
	  }

		User user = (User)session.getAttribute("user");
	  return "user";
	}

	@RequestMapping(method=RequestMethod.POST, value="/login")
	public String login(@RequestParam("name") String username, HttpSession session) {
	  User user = userService.findUser(username);
	  session.setAttribute("user", user);
    return "redirect:/b/user";
	}

	public void setUserService(UserService userService) {
	  this.userService = userService;
	}
}

By specifying the UserService in UserController as @Autowired we expect an AutowiredAnnotationBeanPostProcessor to inject an instance of UserService into an instance of this class. Both the <context:annotation-config/> and <context:component-scan/> beans create instances of AutowiredAnnotationBeanPostProcessor. The <context:annotation-config/> bean creates a PersistenceAnnotationBeanPostProcessor which is not important to us here. We don’t have any persistence units to inject.

The <context:component-scan/> bean creates an AutowiredAnnotationBeanPostProcessor and it also registers a bean definition for the UserController. @Controller is a subclass of @Component and has several annotations that would only be used in a class annotated with @Controller. The <context:component-scan/> bean takes care of mapping any routes and parameters specified by the @RequestMapping, @RequestParam and other @Controller-related annotations.

Our bookmarks-servlet.xml file needs only the <context:component-scan/> bean defined to get our web classes up and running. The full bookmarks-servlet.xml file is very simple.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:jee="http://www.springframework.org/schema/jee"
       xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-3.0.xsd

http://www.springframework.org/schema/context

http://www.springframework.org/schema/context/spring-context-3.0.xsd

http://www.springframework.org/schema/jee

                           http://www.springframework.org/schema/jee/spring-jee-2.5.xsd">

  <import resource="services.xml"/>

  <!-- component-scan creates implicit AutowiredBeanPostProcessor,
             we don't need PersistenceAnnotationPostProcessor -->
  <context:component-scan base-package="net.anthonychaves.bookmarks"/>

  <bean id="viewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolver">
    <property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
    <property name="prefix" value="/WEB-INF/jsp/"/>
    <property name="suffix" value=".jsp"/>
  </bean>

  <bean id="captchaService" class="net.anthonychaves.bookmarks.service.CaptchaServiceSingleton"
        factory-method="getInstance"/>

</beans>

This should hopefully make it very easy for anyone to quickly create at least a skeleton RESTful API with Spring. Comments? Let me know!

A weeks back I helped a development team set up a testing environment for their Ruby on Rails webapp.  The webapp is about 18 months old and had exactly zero tests.  Reverifying its intended behavior was a full time job for some of the developers on the team because there was no way to prove any behavior worked as intended at any given time.  Worse, behavior verification was a manual process and obviously error-prone.

Repeatable tests that prove the software is correct are of high value to this customer.  Testing their application had to be easy.  Writing tests and running them had to be easy.  For an existing webapp with little to no test coverage a black-box testing approach provides a  lot of return for the effort.  Black-box testing allows behavior testing.  We test  webapp behavior by making GET and POST requests to the known URLs the webapp exposes.

Before we set up a test environment for the existing webapp we must decide how to exercise its behavior.  There are a plenty of HTTP libraries available for different languages and platforms.  When you don’t have any tests any testing is better than nothing.  Don’t be afraid if your initial testing framework doesn’t match your webapp language and platform.  We can just as easily test a JSF webapp hosted on Windows with a Ruby client on Linux.  In fact, diversity in the test environment is a good thing.  Multiple black-box clients show how a webapp will perform in the wild.

Automated webapp testing with the Ruby Mechanize library is very easy.  The Ruby environment with RubyGems is required to use the Mechanize library.  There are instructions for setting up a Ruby environment on the Ruby on Rails getting started page.  Follow the instructions for Ruby and RubyGems.

Installing the Mechanize gem is easy.  On Mac OS X 10.5 and Linux the command is:
sudo gem install mechanize

Once you install Mechanize you probably want to play around with it.  You can do so with irb, the interactive Ruby interpreter.  Start irb on the command line by typing irb.  We write Ruby programs directly in irb and irb executes each line as we enter it.  Think of it like a bash shell for Ruby.

Initially irb loads only the core Ruby libraries.  We need to load Mechanize manually with the ‘require’ keyword.

>> require 'mechanize'

I like API documentation in front of me when I code.  The documentation for the version of Mechanize you’re using is on your local box if you installed it with the gem install command as it appeared a few paragraphs up.  Start the gem documentation server by typing ‘gem server’ on the command line.  Now visit http://localhost:8808 in your web browser.  Click the rdoc link in the Mechanize section for the API doc.

The fun stuff happens in the WWW::Mechanize class.  Let’s go back to irb and create an instance of this class:

>> agent = WWW::Mechanize.new

Now we have an instance of an object that makes HTTP GET and POST requests.  Start up your webapp and we can make a request.  Starting with a GET request we call the get method on the Mechanize object.  The get method returns an instance of WWW::Mechanize::Page.

>> page.header.class
=> WWW::Mechanize::Headers
>> page.header
=> {"last-modified"=>"Tue, 16 Jun 2009 02:41:30 GMT", "connection"=>"close", "date"=>"Fri, 17 Jul 2009 00:42:43 GMT", "content-type"=>"text/html", "content-length"=>"7466"}
>> page.body.class
=> String
>> page.body

Go ahead and enter page.body.  I omit the output here because it is a little long.  What you should see is the HTML of the web page you requested with the agent.get(…) method.  agent.get(…) assembles the HTTP headers and makes an HTTP GET request.  This method crosses the network if your webapp runs on a different box.  You can test remote webapps just as easily as local.

Play around with the API.  Next time we’ll cover HTTP POST requests.

I’ll be there!

Building software modules within a team requires communicating, at a minimum,  method or class signatures and a general idea of the functionality.  This may include a detailed design document clearly specifying method signature and a pseudo-code implementation or method stubs and comments about what the method should do right in the source file.  One thing that should never be used for communicating a signature and functionality is dummy code.

Dummy code looks like real code.  It is real code but it rarely works.  Even if it compiles it doesn’t produce the correct result when run.  Nor are there any tests that prove it (in)correct.  Dummy code exists only for the sake of its author’s gratification.

Rather than talk about the desired functionality through some more productive means the dummy code author thinks he is helpfully providing a guesstimate of correct implementation.  What he has actually done is provide a jumbled mess of non-working code cleverly disguised as a working part of the project when he checks it in to the SCM.  The dummy code author thinks someone else will come along and provide the correct implementation “later”.

What he doesn’t realize is that his dummy code is almost indistinguishable from code that should be part of the project.  The next person to try to reuse this code is in for hours of WTF moments trying to figure out WTF the code is supposed to do and why it’s got code branching five levels deep.

At my first post-college job I had a wonderful mentor.  Thys (pronounced Tays, like “taste” without the second ‘t’) and I were talking one day when he asked me a question.  “Anthony, if you were given a task of writing software that would only be run once would you do it quick-and-dirty or with a well-measured, engineered approach?”

How bad could “quick-and-diry” be if the software would run only once?  I thought about it for a moment before answering.  Quick and dirty.

Thys said he would never write quick and dirty software.  Doing so figuratively creates a  monkey on the developerment team’s back.  The software that only needs to run once inevitably needs to run a second time and a third time and eventually run regularly.  Thys helped me realize that software evolves and escapes.  Useful software will run indefinitely.  Any time and effort saved on the initial write will be lost 10 times (I made that number up.  It is actually higher.  Any want to provide real data or examples?) over on the maintenance, bug fixes and rewrites.

Writing dummy code is writing software quick and dirty without any idea of the implementation details.  Bad code and bad algorithms.  The worst of both worlds.  It’s been a long time since Thys and I had that conversation but the years have proven him right again and again.  Any code worth checking in to SCM is worth writing well.  That includes unit tests.

Dummy code has no place in SCM.  If you’re not going to correctly implement a method you stub out then don’t provide an implementation at all.  Leave some comments around the method stub if you have to.  Open a ticket in the issue tracking system to let someone know the method needs an implementation and describe the input and output.  Let the implementer determine which algorithms and data structures to use.

Dummy code is a hazard to software projects.  It violates the principle of least astonishment.  Next time you think about writing some remember that the next person that uses the code will waste time figuring out why it doesn’t work as expected.

If you check code in to your SCM where other people can pull it, take a look at what you’re checking in.  Does it work?  Does it work well?  Are there tests that prove it?  Helping someone by coding less is sometimes the best help of all.