How to get started with Java ActionPack

Berin Loritsch — Mon, 06 Aug 2007 12:45:00 +0000

I’ve left hints about my Java Actionpack, but there really isn’t much out there about it for the general world. So how about I give you a quick primer about how to use it? First off, you will have to check it out with Subversion. There’s a slight conflict with the web site being pulled from SVN and browsing the repository, so you’ll have to use the SVN client instead of mounting the directory or browsing it online. I’ll have to work with my ISP on that.

svn co http://d-haven.org/svn/open/trunk/actionpack

It’s world readable, but only authorized people can write. For now, that’s just me but I’ve not really solicited any help at this point. Since that’s not the point right now, let’s worry about how to get it installed and running. Once you’ve checked it out, you’ll need to build it. Go to the directory where you checked it out and build it with ANT . Yes we kept it simple and only used ANT.

ant jar

The ant script builds two jars, “java-actionpack.jar” and “java-actionapack-test.jar”. The first file is what you will include in your webapp to make the magic happen. The second jar provides the helpers and mocks to help you test the controllers in your application. I’m assuming at this point you know how to set up a web application, how to include your code, and configure a web.xml file. So I’m only going to talk about what is specific to Java Actionpack. Obviously, java-actionpack.jar goes in your WEB-INF/lib folder. You’ll need to add the following to your web.xml file to use Java Actionpack:

  <filter>
     <filter-name>ActionPack</filter-name>
     <filter-class>org.dhaven.actionpack.Dispatcher</filter-class>
     <init-param>
       <param-name>routes.file</param-name>
       <param-value>WEB-INF/app.routes</param-value>
     </init-param>
     <init-param>
       <param-name>controller.package</param-name>
       <param-value>com.mycom.app.controllers</param-value>
     </init-param>
     <init-param>
       <param-name>environment</param-name>
       <param-value>development</param-value> 
<!--       <param-value>test</param-value> -->
<!--       <param-value>production</param-value> -->
     </init-param>
  </filter>

  <filter-mapping>
    <filter-name>ActionPack</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

The only thing that is critical for you to add in is the “controller.package” parameter. This tells Actionpack where to look for your controllers. By default it is simply “controllers”, but that doesn’t really make sense for most people. The default value for “environment” is development, and this really is a way to help you to have logic depending on what environment you are in. The framework will log a message each time a controller is called with an action that doesn’t exist. The message won’t be logged in testing or production. I’ve used it to provide a message about the testing data that our client requires but shouldn’t be there in production. You can access it in your code by looking at the static variable Controller.environment, and the value is from the Environment enum. Finally the “routes.file” parameter allows you to override the default location for the routes file. The default value is what you see in the configuration snippet above.

So what happens if you don’t have a routes file at all? Java Actionpack will create some wiring for you. It will provide the following mappings by default:

/{controller}/{action}/{id}
/{controller}/{action}

That will provide the familiar mapping of what controller you want, which action on that controller, and the option of passing an ID. The way the routes file works is that the curly brackets refer to a request attribute . So why attributes instead of parameters? Mainly so that the application isn’t so easily manipulated by anyone who knows how to type URL parameters. The request attribute controller specifies which controller you are calling. The controller is inside the controller package you set up, and it transforms the name so that it capitalizes the first letter and tacks on Controller to the end. For example if the request is /message/view/34 and you use the configuration above, the class that Actionpack finds is com.mycom.app.controllers.MessageController . The action attribute specifies the method that will be called. With the example URL, we will call MessageController.view() . It’s up to the view() method to read the id attribute and do something with it. Let’s implement this example method:

public class MessageController extends Controller {
    public void view() {
        String id = (String)request.getAttribute("id");

        request.setAttribute("message", Messages.findById(id));
    }
}

You might wonder why I chose to place the message object into the request attribute. It’s really up to you where you put it (the RequestWrapper allows you to override request parameters as well), but this works well if you use the Expression Language and JSPs. You would just refer to the object in the parameter marker like this: ${ message.body } . This calls the method getBody() on the message object you passed in to the request attribute. You’ll also notice that the request object is available as a class attribute, as well as the context object and the response object. They follow the same format as you would expect for a JSP class to keep things familiar. I.e. the names are “request”, “context”, and “response” respectively.

So what about the view? Since Java Actionpack is supposed to be as non-intrusive as possible (yet still opinionated), Java Actionpack will look in the WebApp context for the file called by the controller/action name. So for our example URL from above, we would look at “message/view.jsp”. The progression is this: it looks for a JSP file (”.jsp”), then an HTML file (”.html”), and then finally is just passes the url “message/view” to the system to process. If you want your own supercool view technology as a Servlet, then you just have to set it up to react to the URL scheme we just outlined. Java Actionpack is a filter, but it uses the request dispatcher to pass that URL on. We favored the JSP technology partly because more people would be familiar with it, and partly because it finally grew up enough to be nice to use.

So what happens if Actionpack can’t do anything with the URL? Let’s say the request comes in for “index.html” or “site.css”, or even “fantastic/example.pdf”. If the “controller” attribute doesn’t match an existing controller, Java Actionpack gets out of the way, and lets your application deal with it as it normally would. If the controller is matched, but there is no method for the action attribute, Actionpack will process any filters set up in the controller and process the action calling the action_missing(String actionName) callback (which by default will log what happened in DEVELOPMENT mode). Finally it will dispatch to the view as it normally would. It comes in useful when you have to protect a whole bunch of actions that need a user to have a certain role, but some of the pages are static. Why should you have to create a method if there is nothing to do in it?

These are the basics, and there’s more to it. But for now, I just wanted to share how to get it downloaded so you can play around with it. It should feel natural to a Java developer, and natural enough to someone who has experience with Ruby on Rails. I’ll have to do a few more focused tutorials with it.

Just a Thought...: How to get started with Java ActionPack

How to get started with Java ActionPack