Tapestry Training -- From The Source

Let me help you get your team up to speed in Tapestry ... fast. Visit howardlewisship.com for details on training, mentoring and support!

Thursday, December 31, 2009

Clojure 1.1 is out ... plus videos about new features

So, Clojure 1.1 is now available, with lots of cool new features, including transients, pre & post conditions, futures, promises and a boat load of other stuff. Rich Hickey has put together release notes.

Meanwhile, if you are curious about some of these new features, check out this series of videos by Sean Devlin.

CodeMash I'll be speaking about Clojure and Tapestry at CodeMash 2.0.1.0 this year, January 13-15.

Monday, December 28, 2009

Securing Tapestry pages with Annotations, Part 1

Everyone wants all sorts of integrations for Tapestry with other frameworks, but sometimes rolling your own is actually easier. Let's start with securing access to pages, a subject that still keeps coming up on the mailing list. I thought I'd show a little bit about how I tackle this problem generally.

People have been asking for a single definitive solution for handling security ... but I don't see any single solution satisfying even the majority of projects. Why? Because there are simply too many variables. For example, are you using LDAP, OpenAuth or some ad-hoc user registry (in your database)? Are pages accessible by default, or in-accessible by default? Are you using role-based security? How do you represent roles then? Creating a single solution that's pluggable enough for all these possibilities seems like an insurmountable challenge ... but perhaps we can come up with a toolkit so that you can assemble your own custom solution (more on that later).

One approach to security could be to define a base class, ProtectedPage, that enforced the basic rules (you must be logged in to use this page). You can accomplish such a thing using the activate event handler ... but I find such an approach clumsy. Anytime you can avoid inheritance, you'll find your code easier to understand, easier to manage, easier to test and easier to evolve.

Instead, let's pursue a more declarative approach, where we use an annotation to mark pages that require that the user be logged in. We'll start with these ground rules:

  • Pages are freely accessible by anyone, unless they have a @RequiresLogin annotation
  • Any static resource (in the web context directory) is accessible to anybody
  • There's already some kind of UserAuthentication service that knows if the user is currently logged in or not, and (if logged in) who they are, as a User object

So, we need to define a RequiresLogin annotation, and we need to enforce it, by preventing any access to the page unless the user is logged in.

That poses a challenge: how do you get "inside" Tapestry to enforce this annotation? What you really want to do is "slip in" a little bit of your code into existing Tapestry code ... the code that analyzes the incoming request, determines what type of request it is (a page render request vs. a component event request), and ultimately starts calling into the page code to do the work.

This is a great example of the central design of Tapestry and it's IoC container: to natively supporting this kind of extensibility. Through the use of service configurations it's possible to do exactly that: slip a piece of code into the middle of that default Tapestry code. The trick is to identify where. This image gives a rough map to how Tapestry handles incoming requests:

Tapestry Request Processing

In fact, there's a specific place for this kind of extension: the ComponentRequestHandler pipeline service1. As a pipeline service, ComponentRequestHandler has a configuration of filters, and adding a filter to this pipeline is just what we need.

Defining the Annotation

First, lets define our annotation:

@Target( { ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresLogin {

}

This annotation is designed to be placed on a page class to indicate that the user must be logged in to access the page. The retention policy is important here: it needs to be visible at runtime for our runtime code to see it and act on its presence.

An annotation by itself does nothing ... we need the code that checks for the annotation.

Creating a ComponentRequestFilter

Filters for the ComponentRequestHandler pipeline are instances of the interface ComponentRequestFilter:

/**
 * Filter interface for {@link org.apache.tapestry5.services.ComponentRequestHandler}.
 */
public interface ComponentRequestFilter
{
    /**
     * Handler for a component action request which will trigger an event on a component and use the return value to
     * send a response to the client (typically, a redirect to a page render URL).
     *
     * @param parameters defining the request
     * @param handler    next handler in the pipeline
     */
    void handleComponentEvent(ComponentEventRequestParameters parameters, ComponentRequestHandler handler)
            throws IOException;

    /**
     * Invoked to activate and render a page. In certain cases, based on values returned when activating the page, a
     * {@link org.apache.tapestry5.services.ComponentEventResultProcessor} may be used to send an alternate response
     * (typically, a redirect).
     *
     * @param parameters defines the page name and activation context
     * @param handler    next handler in the pipeline
     */
    void handlePageRender(PageRenderRequestParameters parameters, ComponentRequestHandler handler) throws IOException;
}

Our implementation of this filter will check the page referenced in the request to see if it has the annotation. If the annotation is present and the user has not yet logged in, we'll redirect to the Login page. When a redirect is not necessary, we delegate to the next handler in the pipeline2:

public class RequiresLoginFilter implements ComponentRequestFilter {

  private final PageRenderLinkSource renderLinkSource;

  private final ComponentSource componentSource;

  private final Response response;

  private final AuthenticationService authService;

  public PageAccessFilter(PageRenderLinkSource renderLinkSource,
      ComponentSource componentSource, Response response,
      AuthenticationService authService) {
    this.renderLinkSource = renderLinkSource;
    this.componentSource = componentSource;
    this.response = response;
    this.authService = authService;
  }

  public void handleComponentEvent(
      ComponentEventRequestParameters parameters,
      ComponentRequestHandler handler) throws IOException {

    if (dispatchedToLoginPage(parameters.getActivePageName())) {
      return;
    }

    handler.handleComponentEvent(parameters);

  }

  public void handlePageRender(PageRenderRequestParameters parameters,
      ComponentRequestHandler handler) throws IOException {

    if (dispatchedToLoginPage(parameters.getLogicalPageName())) {
      return;
    }

    handler.handlePageRender(parameters);
  }

  private boolean dispatchedToLoginPage(String pageName) throws IOException {

    if (authService.isLoggedIn()) {
      return false;
    }

    Component page = componentSource.getPage(pageName);

    if (! page.getClass().isAnnotationPresent(RequiresLogin.class)) {
      return false;
    }

    Link link = renderLinkSource.createPageRenderLink("Login");

    response.sendRedirect(link);

    return true;
  }
}

The above code makes a bunch of assumptions and simplifications. First, it assumes the name of the page to redirect to is "Login". It also doesn't try to capture any part of the incoming request to allow the application to continue after the user logs in. Finally, the AuthenticationService is not part of Tapestry ... it is something specific to the application.

You'll notice that the dependencies (PageRenderLinkSource, etc.) are injected through constructor parameters and then stored in final fields. This is the preferred, if more verbose approach. We could also have used no constructor, a non-final fields with an @Inject annotation (it's largely a style choice, though constructor injection with final fields is more guaranteed to be fully thread safe).

The class on its own is not enough, however: we have to get Tapestry to actually use this class.

Contributing the Filter

The last part of this is hooking the above code into the flow. This is done by making a contribution to the ComponentEventHandler service's configuration.

Service contributions are implemented as methods of a Tapestry module class, such as AppModule:

  public static void contributeComponentRequestHandler(
      OrderedConfiguration configuration) {
    configuration.addInstance("RequiresLogin", RequiresLoginFilter.class);
  }

Contributing modules contribute into an OrderedConfiguration: after all modules have had a chance to contribute, the configuration is converted into a List that's passed to the service implementation.

The addInstance() method makes it easy to contribute the filter: Tapestry will look at the class, see the constructor, and inject dependencies into the filter via the constructor parameters. It's all very declarative: the code needs the PageRenderLinkSource, so it simply defines a final field and a constructor parameter ... Tapestry takes care of the rest.

You might wonder why we need to specify a name ("RequiresLogin") for the contribution? The answer addresses a somewhat rare but still important case: multiple contributions to the same configuration that have some form of interaction. By giving each contribution a unique id, it's possible to set up ordering rules (such as "contribution 'Foo' comes after contribution 'Bar'"). Here, there is no need for ordering because there aren't any other filters (Tapestry provides this service and configuration, but doesn't make any contributions of its own into it).

Improvements and Conclusions

This is just a first pass at security. For my clients, I've built more elaborate solutions, that include capturing the page name and activation context to allow the application to "resume" after the login is complete, as well as approaches for automatically logging the user in as needed (via a cookie or other mechanism).

Other improvements would be to restrict access to pages based on some set of user roles; again, how this is represented both in code and annotations, and in the data model is quite up for grabs.

My experience with different clients really underscores what a fuzzy world security can be: there are so many options for how you represent, identify and authenticate the user. Even basic decisions are underpinnings are subject to interpretation; for example, one of my clients wants all pages to require login unless a specific annotation is found. Perhaps over time enough of these use cases can be worked out to build the toolkit I mentioned earlier.

Even so, the amount of code to build a solid, custom security implementation is still quite small ... though the trick, as always, is writing just the write code and hooking it into Tapestry in just the right way.

I expect to follow up this article with part 2, which will expand on the solution a bit more, addressing some more of the real world constraints my customers demand. Stay tuned!


1 In fact, this service and pipeline were created in Tapestry 5.1 specifically to address this use case. In Tapestry 5.0, this approach required two very similar filter contributions to two similar pipelines.

2 If there are multiple filters, you'd think that you'd delegate to the next filter. Actually you do, but Tapestry provides a bridge: a wrapper around the filter that uses the main interface for the service. In this way, each filter delegates to either the next filter, or the terminator (the service implementation after all filters) in a uniform manner. More details about this are in the pipeline documentation.

Monday, December 14, 2009

Upcoming Public Training: London and Paris

SkillsMatter Logo This is a big announcement ... something I've been working on pretty much since I left Formos. I've partnered up with SkillsMatter to provide my three-day, hands-on Tapestry training as a public enrollment course!

This is the exact same course I provide as on-site training, but we'll be doing it at the SkillsMatter offices in London on February 10th, and then in Paris on the 15th.

This is a big experiment for me and for SkillsMatter in terms of growing the size of the Tapestry community. In fact, SkillsMatter has really upped the ante here by offering 2-for-1 on the London training ... that's a great way to kick things off!

I can't emphasize enough what a great opportunity this is for people to get accelerated Tapestry training at a discount (even before factoring in the 2-for-1 offer). I'm really looking forward to bringing many new developers into the fold!

In addition, there will be a special, free evening event at each location. Details on that to follow. I look forward to meeting even more of you there!

Friday, December 04, 2009

Devoxx Videos up at Parleys.com

My sessions for this year's Devoxx are available from Parleys.com: Tapestry and Clojure. You can watch the first two minutes for free (so if you idea of fun is to watch me check with the sound guy and look uncomfortable while waiting for the session to start ... you are in like Flynn); after that it's a subscription service to gain access to all of the Parleys.com content.

Change of pace: Arduino

As a total change of pace, I've been playing around with actual hardware, in the form of an Arduino board. This is a hoot, an actual computer that you can carry around in your hand. They call it physical computing.

I'm just getting started with it, in my tiny shards of free time. Your code is in C (and a smattering of C++). I've hooked up four LEDs and two buttons that allow me to cycle the LEDs forward or backward. Since you're working at such a low level, you have to be aware of tiny factors such as key bounce (closing a switch will, for a short period, yield unstable results due to physical and electrical factors).

There's a tool called Fritzing to help you document your projects. It's very alpha, but the simple results are rather nice:


The code is still evolving:

#define FIRST_LED 12
#define LED_COUNT 4
#define DEBOUNCE_PERIOD 50 // ms

class Debounce
{
public:
  Debounce(int pin);
  boolean read();
private:
  int _pin;
  int _previousValue;
  int _lastButtonDebounce;
  boolean _enabled;
};

Debounce::Debounce(int pin)
{
  _pin = pin;
  _previousValue = LOW;
  _lastButtonDebounce = 0; // never
  _enabled = true;

  pinMode(_pin, INPUT);  
}

boolean Debounce::read()
{
  int currentValue = digitalRead(_pin);

  long now = millis();

  if (currentValue != _previousValue)
  {
    _lastButtonDebounce = now;
    _previousValue = currentValue;
    return false;
  }

  if (now - _lastButtonDebounce < DEBOUNCE_PERIOD) {
    return false;
  }


  // It's gone HIGH to LOW

  if (currentValue == LOW) {
    _enabled = true;
    return false;
  }

  // It's gone LOW to HIGH

  if (_enabled) {
    _enabled = false;
    return true;
  }

  return false;
}

// First press will move to the first LED.
int currentLed = -1;

Debounce advanceButton = Debounce(2);
Debounce retreatButton = Debounce(3);

void setup()
{
  for (int i = 0; i < LED_COUNT; i++) {
    int pin = FIRST_LED - i;
    pinMode(pin, OUTPUT);
    digitalWrite(pin, HIGH);
  }

  delay(250);

  for (int i = 0; i < LED_COUNT; i++)
  {
    digitalWrite(FIRST_LED - i, LOW);
  }
}

void advance()
{
  if (currentLed >= 0)
    digitalWrite(FIRST_LED - currentLed, LOW);

  if (++currentLed == LED_COUNT)
    currentLed = 0;

  digitalWrite(FIRST_LED - currentLed, HIGH);
}

void retreat()
{
  if (currentLed >= 0)
    digitalWrite(FIRST_LED - currentLed, LOW);

  if (--currentLed < 0)
    currentLed = LED_COUNT - 1;

  digitalWrite(FIRST_LED - currentLed, HIGH);
}

void loop()
{
  if (advanceButton.read()) advance();

  if (retreatButton.read()) retreat();
}

Fun stuff ... and I don't see me writing a web framework for it, which is a change of pace.

My ultimate goal is to write Arduino apps in a Clojure DSL, and have Clojure generate the machine code for the AVR processor that runs the Arduino. Of course, that means learning AVR machine code and writing a lot of code to compile and assemble the DSL into something that can execute inside the Arduino.

Plan B: Perhaps its time to learn Forth?

Thursday, December 03, 2009

Tapestry and Kaptcha

Another bit of interesting work I did, for another client, was to implement a CAPTCHA system. I chose the library Kaptcha and built services and components around it.

If you follow the documentation for Katpcha, you'll see that you're supposed to configure it inside web.xml and add a servlet. That's not the Tapestry way, especially for something that will likely be split off into its own library at some point and there's no reason that all the necessary plumbing can't occur within the context of Tapestry's APIs.

The essence of a CAPTCHA is two fold: first, a secret string is generated on the server side. On the client-side, an image and a text field are displayed. The image is a distorted version of the secret text. The user must type the text ... humans being better able to pull meaning out of the distortion than any typical program.

Back on the server side, we compare what the user entered against the secret string.

I broke the implementation up into three pieces:

  • A Tapestry service to handle generating the secret string and the image
  • A Tapestry component to display the image
  • A second component to handle the text field

In practice, all it takes to use this is the following:

  <t:kaptchaimage t:id="kaptcha"/>
  <br/>
  <t:kaptchafield image="kaptcha"/>

The two components work together to select the secret word, display the image, and validate that the user has entered the expected value.

Let's look at how this all comes together.

KaptchaProducer Service

Kaptcha includes an interface, Producer, that has most of what I want:

package com.google.code.kaptcha;

import java.awt.image.BufferedImage;

/**
 * Responsible for creating captcha image with a text drawn on it.
 */
public interface Producer
{
  /**
   * Create an image which will have written a distorted text.
   * 
   * @param text
   *            the distorted characters
   * @return image with the text
   */
  BufferedImage createImage(String text);

  /**
   * @return the text to be drawn
   */
  String createText();
}

I extended this to add methods for determining the width and height of the captcha image:

package com.myclient.services.kaptcha;

import com.google.code.kaptcha.Producer;

/**
 * Extension of KatpchaProducer that exposes the images width and height (in
 * pixels).
 * 
 */
public interface KaptchaProducer extends Producer {

  int getWidth();

  int getHeight();
}

My implementation is largely a wrapper around Kaptcha's default implementation:

package com.myclient.services.kaptcha;

import java.awt.image.BufferedImage;
import java.util.Map;
import java.util.Properties;

import com.google.code.kaptcha.impl.DefaultKaptcha;
import com.google.code.kaptcha.util.Config;

public class KaptchaProducerImpl implements KaptchaProducer {

  private final DefaultKaptcha producer;

  private final int height;

  private final int width;

  public KaptchaProducerImpl(Map<String, String> configuration) {
    producer = new DefaultKaptcha();

    Config config = new Config(toProperties(configuration));

    producer.setConfig(config);

    height = config.getHeight();
    width = config.getWidth();
  }

  public int getHeight() {
    return height;
  }

  public int getWidth() {
    return width;
  }

  public BufferedImage createImage(String text) {
    return producer.createImage(text);
  }

  public String createText() {
    return producer.createText();
  }

  private static Properties toProperties(Map<String, String> map) {

    Properties result = new Properties();

    for (String key : map.keySet()) {
      result.put(key, map.get(key));
    }

    return result;

  }
}

What's all the business with the Map<String, String> configuration? That's a Tapestry IoC mapped configuration, that allows us to extend the configuration of the Kaptcha Producer ... say, to change the width or height or color scheme.

Note that this was my choice, to have a centralized text and image producer, so that all CAPTCHAs in the application would have a uniform look and feel. Another alterntiave would have been to have the KaptchaImage component (described shortly) have its own instance of DefaultKaptcha, with parameters to control its configuration.

KaptchaImage Component

So with this service in place, how do we generate the image? This is done in three steps:

  • Selecting a secret word and storing it persistently in the session
  • Rendering an <img> element, including a src attribute
  • Providing an image byte stream when asked by the browser
package com.myclient.components;

import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;

import javax.imageio.ImageIO;

import org.apache.tapestry5.ComponentResources;
import org.apache.tapestry5.Link;
import org.apache.tapestry5.MarkupWriter;
import org.apache.tapestry5.annotations.Persist;
import org.apache.tapestry5.annotations.SupportsInformalParameters;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.Response;

import com.myclient.services.kaptcha.KaptchaProducer;

/**
 * Part of a Captcha based authentication scheme; a KaptchaImage generates a new
 * text image whenever it renders and can provide the previously
 * rendred text subsequently (it is stored persistently in the session).
 * 
 * The component renders an <img> tag, including width and height
 * attributes. Other attributes come from informal parameters.
 */
@SupportsInformalParameters
public class KaptchaImage {

  @Persist
  private String captchaText;

  @Inject
  private KaptchaProducer producer;

  @Inject
  private ComponentResources resources;

  @Inject
  private Response response;

  public String getCaptchaText() {
    return captchaText;
  }

  void setupRender() {
    captchaText = producer.createText();
  }

  boolean beginRender(MarkupWriter writer) {
    Link link = resources.createEventLink("image");

    writer.element("img",

    "src", link.toAbsoluteURI(),

    "width", producer.getWidth(),

    "height", producer.getHeight());

    resources.renderInformalParameters(writer);

    writer.end();

    return false;
  }

  void onImage() throws IOException {

    BufferedImage image = producer.createImage(captchaText);

    response.setDateHeader("Expires", 0);
    response.setHeader("Cache-Control",
        "no-store, no-cache, must-revalidate");
    response.setHeader("Cache-Control", "post-check=0, pre-check=0");
    response.setHeader("Pragma", "no-cache");

    OutputStream stream = response.getOutputStream("image/jpeg");

    ImageIO.write(image, "jpg", stream);

    stream.flush();

    stream.close();
  }
}

This component (which has no template) has two render phase methods. In setupRender() we choose the secret word; since the captchaText field has the @Persist annotation, it's value will be stored in the session.

Inside beginRender() is where we render the image. We also generate a callback link for an event named "image". The URL Tapestry generates will identify the page and component within the page, as well as this event name.

Notice how we use the getWidth() and getHeight() extensions on the service interface to set these attributes of the <img> tag.

Later, the browser will send a request for the event, and the onImage() event handler method will be invoked. This is where we get the image bytestream from the service and pump it down to the client. As you can see, we set a bunch of header values to ensure that the browser won't cache the image.

KaptchaField Component

The last part of the overall puzzle is the text field. Again, there are two main responsibilities:

  • Rendering out the text field (when rendering)
  • Validating that the user entered the correct secret text (when the form is submitted)
package com.myclient.components;

import org.apache.tapestry5.BindingConstants;
import org.apache.tapestry5.ComponentResources;
import org.apache.tapestry5.FieldValidator;
import org.apache.tapestry5.MarkupWriter;
import org.apache.tapestry5.ValidationTracker;
import org.apache.tapestry5.annotations.BeginRender;
import org.apache.tapestry5.annotations.Environmental;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.SupportsInformalParameters;
import org.apache.tapestry5.corelib.base.AbstractField;
import org.apache.tapestry5.ioc.Messages;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.FieldValidatorSource;
import org.apache.tapestry5.services.Request;

/**
 * Field paired with a {@link KaptchaImage} to ensure that the user has provided
 * the correct value.
 * 
 */
@SupportsInformalParameters
public class KaptchaField extends AbstractField {

  /**
   * The image output for this field. The image will display a distorted text
   * string. The user must decode the distorted text and enter the same value.
   */
  @Parameter(required = true, defaultPrefix = BindingConstants.COMPONENT)
  private KaptchaImage image;

  @Inject
  private Request request;

  @Inject
  private Messages messages;

  @Inject
  private ComponentResources resources;

  @Environmental
  private ValidationTracker validationTracker;

  @Inject
  private FieldValidatorSource fieldValidatorSource;

  @Override
  public boolean isRequired() {
    return true;
  }

  @BeginRender
  boolean renderTextField(MarkupWriter writer) {

    writer.element("input",

    "type", "password",

    "id", getClientId(),

    "name", getControlName(),

    "value", "");

    resources.renderInformalParameters(writer);

    FieldValidator fieldValidator = fieldValidatorSource.createValidator(
        this, "required", null);

    fieldValidator.render(writer);

    writer.end();

    return false;
  }

  @Override
  protected void processSubmission(String elementName) {

    String userValue = request.getParameter(elementName);

    if (image.getCaptchaText().equals(userValue))
      return;

    validationTracker.recordError(this, messages.get("incorrect-captcha"));
  }

}

The renderTextField() method is largely straight forward: by the time this is invoked, the unique clientId and controlName will already have been set for the field. The only trick here is to create some client-side validation to enforce that the field is required.

Later the form will be submitted by the user and the processSubmission() method is invoked. It asks the KaptchaImage for the stored text and compares it to the user's input. If invalid, then an error message is recorded, associated with the field. The actual error text is stored in the component's message catalog.

Conclusion

Tapestry's approach is quite often about integration: integration of component code with other resources (such as templates or message catalogs), integration of components with other components, and integration of components with services. Here we get to see how a singleton service can be used by any number of components, how two components can be connected together, and how easy it is to provide logic both when rendering a page and on later related requests from the client.

Update

If you check the comments below, you'll see that Jon and I have been sparring good-naturedly about what constitutes "simple". Most of the code is related to integration: integrating the Kaptcha code into the Tapestry infrastructure; adding features such as just-in-time initialization to the DefaultProducer code, adding new features (access to the width and height of the image), allowing for configuration of the Kaptcha Producer in the "Tapestry way" (via contribution methods in module classes), and hooking into Tapestry's normal infrastructure for handling form submissions and reporting user input errors ... even client-side logic to enforce that the field is required.

All that integration is what allows the end-developer to get by with just the following in their page template:

  <t:kaptchaimage t:id="kaptcha"/>
  <br/>
  <t:kaptchafield image="kaptcha"/>

... and even that could be compressed down to a single convenience component wrapping the two underlying components:

  <t:kaptcha/>

That is simplicity: no decisions to make, no URLs to map, no other files to edit, no additional code to write.

However, this still follows the Law of Immutable Complexity: making one part of a system simpler will make other parts more complex. In this situation, that extra complexity is the integration code (the two components and the service that Jon objects to). That's a trade-off I'm always willing to make: write some medium complex code once (and test it, once) and then be able to use it wherever I want.

TestNG and Selenium

I love working on client projects, because those help me really understand how Tapestry gets used, and the problems people are running in to. On site training is another good way to see where the theory meets (or misses) the reality.

In any case, I'm working for a couple of clients right now for whom testing is, rightfully, quite important. My normal approach is to write unit tests to test specific error cases (or other unusual cases), and then write integration tests to run through main use cases. I consider this a balanced approach, that recognizes that a lot of what Tapestry does is integration.

One of the reasons I like TestNG is that it seamlessly spans from unit tests to integration tests. All of Tapestry's internal tests (about 1500 individual tests) are written using TestNG, and Tapestry includes a base test case class for working with Selenium: AbstractIntegrationTestSuite. This class does some useful things:

  • Launches your application using Jetty
  • Launches a SeleniumServer (which drives a web browser that can exercise your application)
  • Creates an instance of the Selenium client
  • Implements all the methods of Selenium, redirecting each to the Selenium instance
  • Adds additional error reporting around any Selenium client calls that fail

These are all useful things, but the class has gotten a little long in the tooth ... it has a couple of critical short-comings:

  • It runs your application using Jetty 5 (bundled with SeleniumServer)
  • It starts and stops the stack (Selenium, SeleniumServer, Jetty) around each class

For my current client, a couple of resources require JNDI, and so I'm using Jetty 7 to run the application (at least in development, and possibly in deployment as well). Fortunately, Jetty 5 uses the old org.mortbay.jetty packages, and Jetty 7 uses the new org.eclipse.jetty packages, so both versions of the server can co-exist within the same application.

The larger problem is that I didn't want a single titanic test case for my entire application; I wanted to break it up in other ways, by Tapestry page initially.

I could create additional subclasses of AbstractIntegrationTestSuite, but then the tests will spend a huge amount of time starting and stopping Firefox and friends. I really want that stuff to start just once.

What I've done is a bit of refactoring, by leveraging some features of TestNG that I hadn't previously used.

The part of AbstractIntegrationTestSuite responsible for starting and stopping the stack is broken out into its own class. This new class, SeleniumLauncher, is responsible for starting and stopping the stack around an entire TestNG test. In the TestNG terminology, a suite contains multiple tests, and a test contains test cases (found in individual classes, within scanned packages). The test case contains test and configuration methods.

Here's what I've come up with:

package com.myclient.itest;

import org.apache.tapestry5.test.ErrorReportingCommandProcessor;
import org.eclipse.jetty.server.Server;
import org.openqa.selenium.server.RemoteControlConfiguration;
import org.openqa.selenium.server.SeleniumServer;
import org.testng.ITestContext;
import org.testng.annotations.AfterTest;
import org.testng.annotations.BeforeTest;

import com.myclient.RunJetty;
import com.thoughtworks.selenium.CommandProcessor;
import com.thoughtworks.selenium.DefaultSelenium;
import com.thoughtworks.selenium.HttpCommandProcessor;
import com.thoughtworks.selenium.Selenium;

public class SeleniumLauncher {

  public static final String SELENIUM_KEY = "myclient.selenium";

  public static final String BASE_URL_KEY = "myclient.base-url";

  public static final int JETTY_PORT = 9999;

  public static final String BROWSER_COMMAND = "*firefox";

  private Selenium selenium;

  private Server jettyServer;

  private SeleniumServer seleniumServer;

  /** Starts the SeleniumServer, the application, and the Selenium instance. */
  @BeforeTest(alwaysRun = true)
  public void setup(ITestContext context) throws Exception {

    jettyServer = RunJetty.start(JETTY_PORT);

    seleniumServer = new SeleniumServer();

    seleniumServer.start();

    String baseURL = String.format("http://localhost:%d/", JETTY_PORT);

    CommandProcessor cp = new HttpCommandProcessor("localhost",
        RemoteControlConfiguration.DEFAULT_PORT, BROWSER_COMMAND,
        baseURL);

    selenium = new DefaultSelenium(new ErrorReportingCommandProcessor(cp));

    selenium.start();

    context.setAttribute(SELENIUM_KEY, selenium);
    context.setAttribute(BASE_URL_KEY, baseURL);
  }

  /** Shuts everything down. */
  @AfterTest(alwaysRun = true)
  public void cleanup() throws Exception {
    if (selenium != null) {
      selenium.stop();
      selenium = null;
    }

    if (seleniumServer != null) {
      seleniumServer.stop();
      seleniumServer = null;
    }

    if (jettyServer != null) {
      jettyServer.stop();
      jettyServer = null;
    }
  }
}

Notice that we're using the @BeforeTest and @AfterTest annotations; that means any number of tests cases can execute using the same stack. The stack is only started once.

Also, notice how we're using the ITestContext to communicate information to the tests in the form of attributes. TestNG has a built in form of dependency injection; any method that needs the ITestContext can get it just by declaring a parameter of that type.

AbstractIntegrationTestSuite2 is the new base class for writing integration tests:

package com.myclient.itest;

import java.lang.reflect.Method;

import org.apache.tapestry5.test.AbstractIntegrationTestSuite;
import org.apache.tapestry5.test.RandomDataSource;
import org.testng.Assert;
import org.testng.ITestContext;
import org.testng.annotations.AfterClass;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.BeforeMethod;

import com.mchange.util.AssertException;
import com.thoughtworks.selenium.Selenium;

public abstract class AbstractIntegrationTestSuite2 extends Assert implements
    Selenium {

  public static final String BROWSERBOT = "selenium.browserbot.getCurrentWindow()";

  public static final String SUBMIT = "//input[@type='submit']";

  /**
   * 15 seconds
   */
  public static final String PAGE_LOAD_TIMEOUT = "15000";

  private Selenium selenium;

  private String baseURL;

  protected String getBaseURL() {
    return baseURL;
  }

  @BeforeClass
  public void setup(ITestContext context) {
    selenium = (Selenium) context
        .getAttribute(SeleniumLauncher.SELENIUM_KEY);
    baseURL = (String) context.getAttribute(SeleniumLauncher.BASE_URL_KEY);
  }

  @AfterClass
  public void cleanup() {
    selenium = null;
    baseURL = null;
  }

  @BeforeMethod
  public void indicateTestMethodName(Method testMethod) {
    selenium.setContext(String.format("Running %s: %s", testMethod
        .getDeclaringClass().getSimpleName(), testMethod.getName()
        .replace("_", " ")));
  }

  /* Start of delegate methods */
  public void addCustomRequestHeader(String key, String value) {
    selenium.addCustomRequestHeader(key, value);
  }

  ...
}

Inside the @BeforeClass-annotated method, we receive the test context and extract the selenium instance and base URL put in there by SeleniumLauncher.

The last piece of the puzzle is the code that launches Jetty. Normally, I test my web applications using the Eclipse run-jetty-run plugin, but RJR doesn't support the "Jetty Plus" functionality, including JNDI. Thus I've created an application to run Jetty embedded:

package com.myclient;

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;

public class RunJetty {

  public static void main(String[] args) throws Exception {

    start().join();
  }

  public static Server start() throws Exception {
    return start(8080);
  }

  public static Server start(int port) throws Exception {
    Server server = new Server(port);

    WebAppContext webapp = new WebAppContext();
    webapp.setContextPath("/");
    webapp.setWar("src/main/webapp");

    // Note: Need jetty-plus and jetty-jndi on the classpath; otherwise
    // jetty-web.xml (where datasources are configured) will not be
    // read.

    server.setHandler(webapp);

    server.start();

    return server;
  }
}

This is all looking great. I expect to move this code into Tapestry 5.2 pretty soon. What I'm puzzling on is a couple of extra ideas:

  • Better flexibility on starting up Jetty so that you can hook your own custom Jetty server configuration in.
  • Ability to run multiple browser agents, so that a single test suite can execute against Internet Explorer, Firefox, Safari, etc. In many cases, the same test method might be invoked multiple times, to test against different browsers.

Anyway, this is just one of a number of very cool ideas I expect to roll into Tapestry 5.2 in the near future.

Sunday, November 22, 2009

Fun and Jet Lag at Devoxx 2009

Last week was a bit of a blur, a mix of severe jet lag, a bit of over-indulgence at the speaker's dinner, and the thrill of presenting on Tapestry and on Clojure in a rock-star environment. Devoxx is well known for the venue ... speaking in front of a three story screen to a crowd numbering in the hundreds is a bit different that chatting to a group in front of a whiteboard, I can say.

If you were at the show, please take a minute to rate my sessions:

Saturday, November 07, 2009

Next Steps for Tapestry

I've been consciously letting Tapestry 5.1 sit and stabilize for a while ... a time that's stretched a few months longer than I initially intended.

This is due to a number of factors: my return to independent consulting, my desire to write a definitive Tapestry 5 book, and preparations for many trips and speaking engagements.

All of these factors have worked on each other: I've been improving and extending my Tapestry Workshop training materials which can be quite time consuming. I've also (over the last several months) been on the road several times, talking about Tapestry or doing Tapestry training.

I do want to write a book on Tapestry but if I start writing 5.2 code, I know I'll be sucked right in ... lots of code (that darn Spring Web Flow integration for sure this time) and bug fixes.

In addition, I've had an embarassment of riches: two main clients, one regular part time, and the other requesting (but not always getting) all my remaining time. I also have additional clients and training engagements waiting in the wings. I simply have a lot of draws on my time.

As usual, working on real-world projects lets me experience the "rough edges" of Tapestry and fills me with ideas on how to address those in the next release ... often by splitting up Tapestry services into smaller, more easily overridden chunks and carefully moving internal services out into the public APIs.

Finally, I've been very pleased by the fact that as I've stepped back temporarily from my normal stream of commits, the other Tapestry developers have stepped in and filled the gap. There's been quite a bit of activity especially from Igor that I've barely had a chance to keep up on.

So the question is: do I wait and see if time opens up in Q1 to actually start on a T5 book ... or do I jump into 5.2 coding and leave books to others? It's much, much easier to write code than to write a book ... a book is a large amount of concentrated effort. It's very hard to accomplish anything on a book using an hour here or an evening there ... whereas Tapestry's code base lends itself to that kind of effort quite nicely.

Progress on Cascade

Meanwhile, in spare minutes (and during sessions at ApacheCon), I've been continuing to work on Cascade. It's been a great learning exercise for me, pushing my understanding of both Clojure and functional programming in general ... and especially, some pretty advanced meta-programming with macros.

I'm also using Cascade as a kind of test bed for ideas that will eventually appear in Tapestry.

Not everything turns out exactly as I've planned. For example, I've been very excited about invariants, portions of the rendered DOM that could be cached from one request to another, to speed up the rendering. Like Tapestry, Cascade views render a DOM structure which can be manipulated (in an intermediate stage) before being streamed as text. This is a useful and powerful concept in a number of ways.

My thinking has been that a typical view will contain sections of the template that are invariant: unchanging, and that there would be a benefit to building that sub-section of the DOM once and reusing it efficiently in later renderings of the view.

Clojure template forms are processed by macros to become normal Clojure code. Thus something like (template :p [ "Hello" ]) will be transformed into code, approximately (element-node :p nil (combine (text-node "Hello"))). My approach was to tag the new Clojure code forms (the list consisting of element-node, :p, etc.) with meta data to identify it as invariant. Eventually this would propagate up to a higher level and code to manage a cache would be wrapped around it: (or (read-view-cache 97) (update-view-cache 97 (element-node :p ...

Fun stuff ... until I put it into practice (after a fair amount of debugging) and discovered that in the views I've created so far (for testing purposes), the number of nodes that can be cached is low; any use of a symbol or a function call mixed into the template "taints" it as variant. I wasn't set up to do performance measurements, but my gut feeling is that the overhead of managing the caches would overshadow the savings from the small islands of reused DOM nodes.

Back to Cascade as a learning experience: just because this didn't work out doesn't mean I didn't learn a lot from heading down that direction, and certainly the amount of code it took was quite small. I have it stored in a branch in case I ever want to give it another shot.

I will have all the basic features of Cascade implemented pretty soon; I'm looking forward to seeing what the larger Clojure community makes of it. In the meantime, it has served as a great way for me to dig deep into Clojure ... I'll be putting together more sessions for NoFluffJustStuff and more articles for the companion magazine based on all this.

Rethinking Tapestry's approach to JavaScript

I've been doing a lot of work for a client using the ExtJS library and that, combined with many other things I've been looking at, has started to shift my attitude to the correct approach to client-side JavaScript. Not a sea change, just a minor adjustment.

Until now, I've had the approach that the page should popup "complete" and that the JavaScript should only manipulate (or add to) the content already present. In most cases, such as adding validations to user input fields, that works fine: you write out the HTML for the field, remember the id for the field, then add JavaScript that adds event handlers to the field, finding it by its id.

However, for more complex cases, such as Tapestry's Palette component, I've been coding like its 2001 for too long.

The Palette component renders out two <select> elements, plus a number of <divs>, a few buttons, and a chunk of JavaScript to connect it all together. This means generating a lot of related ids on the server (to match against the generated HTML markup) and passing those down to the client.

It's effective but it reflects my relative naivete with JavaScript back in 2001. It's now so much easier to create a DOM structure on the client, using any of the major JavaScript libraries. That, in turn, makes it much more reasonable to just write out an empty <div> element with an id and install into that empty space all the markup for the component, generated on the client side. In fact, I envision a version of the Palette for Tapestry 5.2 that starts as a <select> configured for multiple selection and is converted on the fly to the familiar Palette component entirely on the client side ... which means that it could actually operate in a functional, if limited way, even if JavaScript is disabled in the client.

ExtJS includes a number of other ideas that are worth thinking about; I've been very impressed by the concept of a separate controller hierarchy on the client side (ExtJS calls these "components" as differentiated from the DOM nodes they create and manage). That's something that's ad-hoc and inconsistent in Tapestry's client-side library. I think embracing a similar, more structured approach could make it easier for Tapestry to embrace even more dynamic Ajax behavior.

Thursday, November 05, 2009

Tapestry 5: Java Power, Scripting Ease (ApacheCon 2009)

I've uploaded my presentation from ApacheCon 2009. Of coure, the fun parts are the embedded screen casts, and you need to see me live to get that part!

Saturday, October 31, 2009

Maven: Throwing out the bath water, keeping the baby

... in other words, a first step towards using Maven for dependency management but NOT builds. That's the irony of Maven ... they've conflated two things (dependency management and builds) in such as way that they make the useful one (dependency management) painful because the build system is so awful.

As an interrum step between full Maven and (most likely) Gradle, I've been looking at a way to use Maven for dependencies only in a way that is compatible with Eclipse ... without using the often flakey and undependable M2Eclipse plugin.

In any case, rather than assuming that dependencies might change at any point in time at all, let's assume that when I change dependencies (by manually editing pom.xml) I know it and am willing to run a command to bring Eclipse (and my Ant-based build) in line.

First, my pom.xml:

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"
  xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.example</groupId>
  <artifactId>myapp</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>org.apache.tapestry</groupId>
      <artifactId>tapestry-hibernate</artifactId>
      <version>${tapestry-version}</version>
      <scope>compile</scope>
      <exclusions>
        <exclusion>
          <artifactId>log4j</artifactId>
          <groupId>log4j</groupId>
        </exclusion>
        <exclusion>
          <artifactId>slf4j-log4j12</artifactId>
          <groupId>org.slf4j</groupId>
        </exclusion>
      </exclusions>
    </dependency>
    <dependency>
      <groupId>org.apache.tapestry</groupId>
      <artifactId>tapestry-test</artifactId>
      <version>5.2.0-SNAPSHOT</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>servlet-api</artifactId>
      <version>2.4</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.lucene</groupId>
      <artifactId>lucene-core</artifactId>
      <version>2.4.1</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-search</artifactId>
      <version>3.1.1.GA</version>
    </dependency>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.4</version>
    </dependency>
    <dependency>
      <groupId>commons-beanutils</groupId>
      <artifactId>commons-beanutils</artifactId>
      <version>1.8.0</version>
    </dependency>
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>0.9.17</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>1.5.8</version>
      <type>jar</type>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>8.4-701.jdbc4</version>
    </dependency>
    <dependency>
      <groupId>xerces</groupId>
      <artifactId>xercesImpl</artifactId>
      <version>2.4.0</version>
      <type>jar</type>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.howardlewisship</groupId>
      <artifactId>tapx-datefield</artifactId>
      <version>${tapx-version}</version>
    </dependency>
    <dependency>
      <groupId>com.howardlewisship</groupId>
      <artifactId>tapx-prototype</artifactId>
      <version>${tapx-version}</version>
    </dependency>
    <dependency>
      <groupId>org.testng</groupId>
      <artifactId>testng</artifactId>
      <version>5.9</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <repositories>
    <repository>
      <id>tapestry360-snapshots</id>
      <url>http://tapestry.formos.com/maven-snapshot-repository/</url>
    </repository>
    <repository>
      <id>repository.jboss.org</id>
      <url>http://repository.jboss.org/maven2/</url>
    </repository>
  </repositories>
  <properties>
    <tapestry-version>5.1.0.5</tapestry-version>
    <lucene-version>2.4.1</lucene-version>
    <tapx-version>1.0.0-SNAPSHOT</tapx-version>
  </properties>
</project>

(This was adapated from one of my client's POMs).

Next, an Ant build file that compiles this, runs tests and builds a WAR:

<project name="example" xmlns:mvn="urn:maven-artifact-ant">

  <property name="classes.dir" value="target/classes" />
  <property name="test.classes.dir" value="target/test-classes" />
  <property name="web.lib.dir" value="target/web-libs" />
  <property name="webapp.dir" value="src/main/webapp" />
  <property name="webinf.dir" value="${webapp.dir}/WEB-INF" />

  <path id="compile.path">
    <fileset dir="lib/provided" includes="*.jar"/>
    <fileset dir="lib/runtime" includes="*.jar" />
  </path>

  <path id="test.path">
    <path refid="compile.path" />
    <pathelement path="${classes.dir}" />
    <fileset dir="lib/test" includes="*.jar" />
  </path>

  <target name="clean" description="Delete all derived files.">
    <delete dir="target" quiet="true" />
  </target>

  <!-- Assumes that Maven's Ant library is installed in ${ANT_HOME}/lib/ext. -->

  <target name="-setup-maven">
    <typedef resource="org/apache/maven/artifact/ant/antlib.xml" uri="urn:maven-artifact-ant" />
    <mvn:pom id="pom" file="pom.xml" />
  </target>

  <macrodef name="copy-libs">
    <attribute name="filesetrefid" />
    <attribute name="todir" />
    <sequential>
      <mkdir dir="@{todir}" />
      <copy todir="@{todir}">
        <fileset refid="@{filesetrefid}" />
        <mapper type="flatten" />
      </copy>
    </sequential>
  </macrodef>

  <macrodef name="rebuild-lib">
    <attribute name="base" />
    <attribute name="scope" />
    <attribute name="libs.id" default="@{base}.libs" />
    <attribute name="src.id" default="@{base}.src" />
    <sequential>
      <mvn:dependencies pomrefid="pom" filesetid="@{libs.id}" sourcesFilesetid="@{src.id}" scopes="@{scope}" />
      <copy-libs filesetrefid="@{libs.id}" todir="lib/@{base}" />
      <copy-libs filesetrefid="@{src.id}" todir="lib/@{base}-src" />
    </sequential>
  </macrodef>

  <target name="refresh-libraries" depends="-setup-maven" description="Downloads runtime and test libraries as per POM.">
    <delete dir="lib" quiet="true" />
    <rebuild-lib base="provided" scope="provided"/>
    <rebuild-lib base="runtime" scope="runtime,compile" />
    <rebuild-lib base="test" scope="test" />
    <echo>
      
*** Use the rebuild-classpath command to update the Eclipse .classpath file.</echo>
  </target>

  <target name="compile" description="Compile main source code.">
    <mkdir dir="${classes.dir}" />
    <javac srcdir="src/main/java" destdir="${classes.dir}" debug="true" debuglevel="lines,vars,source">
      <classpath refid="compile.path" />
    </javac>
  </target>

  <target name="compile-tests" depends="compile" description="Compile test sources.">
    <mkdir dir="${test.classes.dir}" />
    <javac srcdir="src/test/java" destdir="${test.classes.dir}" debug="true" debuglevel="lines,vars,source">
      <classpath refid="test.path" />
    </javac>
  </target>

  <target name="run-tests" depends="compile-tests" description="Run unit and integration tests.">
    <taskdef resource="testngtasks" classpathref="test.path" />
    <testng haltonfailure="true">
      <classpath>
        <path refid="test.path" />
        <pathelement path="${test.classes.dir}" />
      </classpath>

      <xmlfileset dir="src/test/conf" includes="testng.xml" />

    </testng>
  </target>


  <target name="war" depends="run-tests,-setup-maven" description="Assemble WAR file.">

    <!-- Copy and flatten the libraries ready for packaging. -->

    <mkdir dir="${web.lib.dir}" />
    <copy todir="${web.lib.dir}" flatten="true">
      <fileset dir="lib/runtime" />
    </copy>
    <jar destfile="${web.lib.dir}/${pom.artifactId}-${pom.version}.jar" index="true">
      <fileset dir="src/main/resources" />
      <fileset dir="${classes.dir}" />
    </jar>

    <war destfile="target/${pom.artifactId}-${pom.version}.war">
      <fileset dir="${webapp.dir}" />
      <lib dir="${web.lib.dir}" />
    </war>
  </target>
</project>

The key target here is refresh-libraries, which deletes the lib directory then repopulates it. It creates a sub folder for each scope (lib/provided, lib/runtime, lib/test) and another sub folder for source JARs (lib/provided-src, lib/runtime-src, etc.).

So how does this help Eclipse? Ruby to the rescue:

#!/usr/bin/ruby
# Rebuild the .classpath file based on the contents of lib/runtime, etc.

# Probably easier using XML Generator but don't have the docs handy

def process_scope(f, scope)
 # Now find the actual JARs and add an entry for each one.
 
 dir = "lib/#{scope}"

 return unless File.exists?(dir)
 
 Dir.entries(dir).select { |name| name =~ /\.jar$/ }.sort.each do |name|
   f.write %{  <classpathentry kind="lib" path="#{dir}/#{name}"}
   
   srcname = dir + "-src/" + name.gsub(/\.jar$/, "-sources.jar") 

   if File.exist?(srcname)
      f.write %{ sourcepath="#{srcname}"}
   end
   
   f.write %{/>\n}
 end
end

File.open(".classpath", "w") do |f|
  f.write %{<?xml version="1.0" encoding="UTF-8"?>
<classpath>
  <classpathentry kind="src" path="src/main/java"/>
  <classpathentry kind="lib" path="src/main/resources"/>
  <classpathentry kind="src" path="src/test/java"/>
  <classpathentry kind="lib" path="src/test/resources"/>
  <classpathentry kind="output" path="target/classes"/>
  <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
}

 process_scope(f, "provided")
 process_scope(f, "runtime")
 process_scope(f, "test")
 
 f.write %{
</classpath>
}
    
end

That's pretty good for half an hour's work. This used to be much more difficult (in Maven 2.0.9), but the new scopes attribute on the Maven dependencies task makes all the difference.

Using this you are left with a choice: either you don't check in .classpath and the contents of the lib folder, in which case you need to execute the target and script in order to be functional ... or you simply check everything in. I'm using GitHub for my project repository ... the extra space for a few MB of libraries is not an issue and ensures that I can set up the exact classpath needed by the other developers on the project with none of the usual Maven guess-work. I'm looking forward to never having to say "But it works for me?" or "What version of just about anything do you have installed?" or "Try a clean build, and close and reopen your project, and remove and add Maven dependency support, then sacrifice a small goat" every again.

Next up? Packaging most of this into an Ant library so that I can easily reuse it across projects ... or taking the time to learn Gradle and let it handle most of this distracting garbage.

Thursday, October 29, 2009

Sunday, October 04, 2009

Cascade Exception Reporting

I've been taking a little time from my billable projects to continue working on Cascade. One feature that's very important to me is to have great exception reporting, akin to Tapestry's. Here's a current snapshot of where I am:


This is very Tapestry-like (I've even borrowed the CSS styles). You can even see the start of the Request object's properties being displayed.

Something to notice here: Clojure stack frames are in Clojure syntax. To appreciate this, see what you get when you click the "Display hidden detail" button:


The exception report view is omitting a lot of clojure.lang internals, and it is working backwards from the mangled Java class name to the Clojure namespace and function name. This, plus only displaying the stack trace for the root exception, makes it much more reasonable to figure out where problems are actually occurring.

I expect to expand this further, adding a pop-up or hover window to display Clojure source associated with the stack frame.

Saturday, October 03, 2009

Tapestry 5.1 and IE 8 -- Customizing Tapestry

Tapestry is nice enough to bundle the Prototype and Scriptaculous libraries its client-side support is wired against, which is very convenient ... until you find out the the packaged version is not compatible with your shiny new browser, such as Internet Explorer 8.

Tapestry IoC to the rescue: you can override where Tapestry looks for the Prototype & Scriptaculous files (alas, it currently looks in the exact same place for them). Where these files are stored, and how they are exposed to the client is controlled by two contributions inside TapestryModule:

    public static void contributeFactoryDefaults(MappedConfiguration<String, String> configuration)
    {
        . . .

        configuration.add("tapestry.scriptaculous", "classpath:${tapestry.scriptaculous.path}");
        configuration.add("tapestry.scriptaculous.path", "org/apache/tapestry5/scriptaculous_1_8_2");

        . . .
    } 

    public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration,

      @Symbol(SymbolConstants.TAPESTRY_VERSION)
      String tapestryVersion,
      @Symbol("tapestry.scriptaculous.path")
      String scriptaculousPath)
    {
       . . .

       configuration.add("scriptaculous/" + tapestryVersion, scriptaculousPath);

       . . .
     }

The first contributions set where, on the classpath, the Prototype & Scriptaculous files are located, defining symbols that can be referenced in various servers. The second uses some of those symbols (and a few others) to map the classpath location to a URL (this is the job of the ClasspathAssetAliasManager service).

However, what's being contributed is Prototype 1.6.0.3 and for compatibility with Internet Explorer 8, we need the latest and greatest: 1.6.1. That's what tapx-prototype does. And at its core it's just a couple of lines of code:

public class PrototypeModule
{
    public void contributeFactoryDefaults(MappedConfiguration<String, String> configuration)
    {
        configuration.override("tapestry.scriptaculous.path", "com/howardlewisship/tapx/prototype");
    }

    public static void contributeClasspathAssetAliasManager(
            MappedConfiguration configuration)
    {
        configuration.add("tapx-prototype/1.6.1", "com/howardlewisship/tapx/prototype");
    }
}

Notice that we can just override part of the configuration of one service (FactoryDefaults) and extend the configuration of another service (ClasspathAssetAliasManager) without disturbing anything else. This is Tapestry IoC in a nutshell!

Glenn Vanderburg has been popularizing a terminology for extensible software: a "seam" is any point where existing software can be extended. He's used to the Ruby world where, literally, every method is a seam. Tapestry, too, is all seams ... every service, and (with more effort than Ruby) every method of every service is a seam, and lots of effort has gone into the design of Tapestry IoC to ensure that it can be extended without massive cut-and-paste or other disruptions.

I'll be releasing the tapx code soon as a stable release, once I do a little more testing with IE8.

Friday, September 25, 2009

Off topic: Quizissippi

For those of you in the Portland, OR area ... mark your calendars for Wednesday evenings at the Mississippi Pizza Pub for Quizissippi, hosted by the wonderful Red Molly. It's a trivia contest with cash prizes ... and since it's run by Molly it will be very fun and very competitive and not quite like any trivia contest you've previously experienced.

The first Quizissippi is at 7pm, on October 7th in the Atlantis Lounge. I'm already looking forward to Mark pouring some of his great drinks, and Molly dazzling us all with her cleverness. And maybe some quick cash ... if I'm smart enough!

Joys of cross-browser development

I'm working on a dependent drop-down list inside my Tapestry application (one I'm building for a client). Guess what? They fire the critical "change" even completely differently.

In FF, change is fired when:

  • You hit enter after tabbing into the select and changing its value
  • You tab out of the field after changing its value with the up and down arrows
  • You mouse click on the select, then click on an entry in the pop up list

This is sensible, even if it does not, perhaps, match the spec.

In IE 6:

  • After using the mouse to select a value from the popup
  • After changing the value with the up and down arrows

In other words, any visual change to the select causes an immediate change event. Of course, I need to work around IE's behavior since it will result in way too many Ajax requests. My event handler needs to set a timer and wait some time, perhaps 1/4 seconds, before doing the Ajax update (but only if another change event hasn't been triggered). Fortunately, I have Prototype's delay on my side.

Meanwhile, who implements the spec correctly? Here's what it says:

The onchange event occurs when a control loses the input focus and its value has been modified since gaining focus. This attribute applies to the following elements: INPUT, SELECT, and TEXTAREA

So, when using mouse selection, FF fires early (before the tab out of the field, or when you hit enter), and IE fires early all the time.

And for those who have asked ... yes, I'll "productize" this code and put it into Tapestry 5.2!

Thursday, September 24, 2009

Devoxx 2009: Tapestry and Clojure

devoxx logo Coming up in November ... I'll be at the Devoxx 2009 conference in Antwerp, Belgium. I'll be presenting two 60 minute talks: one as an introduction to Tapestry (Nov 20th, 10:30-11:30, Room 9) and another as an introduction to Clojure (Nov 18th, 12:00-13:00, Room 6). Given that my existing talks take closer to 90 minutes, this is going to take fast talking and a bit of editing!

Devoxx is a very cool conference, run by the user group community and very well organized. It's one of the best places to speak because of the quality of the A/V: it takes place in a movie theater, with giant screens and plush, stadium seating.

This is my first return to Devoxx since 2004, when it was still called Javopolis. With luck, this time, I won't succumb to jet lag and comfy seats and start snoring in someone's session!

Tuesday, September 22, 2009

No Fluff Just Stuff Seattle Roundup

It was a huge pleasure to be speaking at a No Fluff Just Stuff conference again, it's been much too long. This was a good show with a lot of folks coming down from Vancouver, BC to attend.

This was an odd show for me, as we didn't do any Tapestry talks at all. However, all three of my talks (an introduction to Cappuccino, and two talks on Clojure) were well attended, with good questions and some fun discussions between sessions. I'm looking forward to doing these same sessions, with a number of improvements, in the Spring when NFJS starts back up.

Interestingly, I was busy writing Clojure code almost continuously in the back row of other speaker's sessions ... but this didn't stop me from appreciating Scott Davis's great talks on Grails, and on "deconstructing Web 2.0". Also, I had a lot of interaction with Brian Goetz ("are all web application's broken"). As usual, as soon as you mix Java with concurrency, it's a bit sobering. Tapestry helps here, but is not a complete panacea against some of the "nightmare scenarios" that may become more commonplace as the number of CPU cores increases.

I'm getting more adept at advanced Clojure; I've been busy adapting the concept of parameter destructuring to pulling data out of the request path and query parameters.

(defaction increment-count
  {:path "count/increment"}
  [env] 
  [count :int] ; destructure the value after "/increment" as an integer
  (send-redirect env (link env show-counter [(inc count)])))

This defines a Cascade action, mapped to the "count/increment" path. A number is expected to follow (i.e., /count/increment/4) and the job of this action is to increment that value and redirect the user to the show-counter view.

Cascade actions are still functions, thus the normal parameter declaration: [env]. Cascade views and actions always take a single parameter, a map called "the environment" that provides access to Cascade-specific values as well as Servlet API objects.

The path destructuring follows: [count :int] which destructures the first "extra path" value as an integer. There's a number of built-in parsers referenced by keywords such as :int, or you can supply a function that takes a string and returns a value. If another pair of values is given, that applies to the next value in the path.

I'm finding this a pretty elegant way to express this secondary aspect of mapping URLs to view and actions; there's additional syntax for destructuring query parameters instead of path values. I may extend this further, to handle default values for missing terms in the path.

I try to capture some of this in my Clojure talks; the idea of growing the language up, adding the new features you need. From one perspective, this is just a domain specific language, but in the Lisp world, that concept is so deeply entrenched that there isn't even a word for it beyond "programming". This is one part of the overall Clojure picture that gets me very excited, and I'm continuing to struggle with how to express this to people for whom even the Lisp syntax is alien and off-putting.

Monday, September 21, 2009

Speaking at ApacheCon 2009

Just a reminder ... I'll be spreading the good word about Tapestry at ApacheCon this year. My session is Tapestry 5: Java Power, Scripting Ease! on Wed Nov 04 at 11am.

Wednesday, September 16, 2009

Tapestry Performance Benchmark (vs. Wicket, JSF, etc.)

Peter Thomas has created a detailed performance analysis of Wicket, Tapestry, Grails and Seam. It's an interesting read from non-Tapestry user's perspective, and complements Ben Gidley's findings.

He's measuring raw performance and Wicket narrowly bests Tapestry in most categories, with Seam pretty close and Grails much further out.

I'm disturbed by some of his problems developing the application (with respect to adding client-side credit card number validation) and there's no mention of Tapestry's other qualities, such as live class reloading, exception reporting, etc. Still, criticism of Tapestry's documentation hits close to home (and it, alas, too fair). Accurate and very complete, but not organized for a beginner ... something I'm hoping to address over the next few months.

Like Tapestry? Read German? There's a book for you!

book cover

Igor Drobiazko has just announced his new book, Die Entwicklung von Webanwendungen mit Leichtigkeit! (The development of web applications with ease!).

Alas, it is in German, though he hopes good sales in Germany may lead to a translation for the English speaking market. It's available as an e-book now, and in hardcover at the end of September.

Wednesday, September 09, 2009

Formos in the news

I may no longer work at Formos, but I'm still pleased to see a nice writeup about Formos and StreamBank. StreamBank is an application that helps land owners and The Freshwater Trust work to improve stream health and water quality across Oregon. The article doesn't state this, but StreamBank is written in Tapestry (it started as Tapestry 4 and was ported to Tapestry 5).

Friday, August 28, 2009

Keeping track of Clojure dependencies

I've been coding more of Cascade and I'm tending to do lots of small namespaces. I'm concerned about circular dependencies, so I've been using OmniGraffle to keep track of what uses what:

I end up keeping this open in the background and updating it manually as I add new namespaces or change dependencies. I'm pretty sure it's accurate.

It does raise the question ... am I using the correct level of granularity? I think I am, and the individual files are pretty short:

$ find src/main/clojure -name \*.clj | xargs wc -l
      51 src/main/clojure/cascade/config.clj
     115 src/main/clojure/cascade/dispatcher.clj
      92 src/main/clojure/cascade/dom.clj
     107 src/main/clojure/cascade/filter.clj
      51 src/main/clojure/cascade/internal/parse_functions.clj
      94 src/main/clojure/cascade/internal/parser.clj
     205 src/main/clojure/cascade/internal/utils.clj
     113 src/main/clojure/cascade/internal/viewbuilder.clj
      36 src/main/clojure/cascade/jetty.clj
      39 src/main/clojure/cascade/logging.clj
      29 src/main/clojure/cascade/map_utils.clj
      56 src/main/clojure/cascade/mock.clj
      73 src/main/clojure/cascade/path_map.clj
      41 src/main/clojure/cascade/pipeline.clj
      30 src/main/clojure/cascade/urls.clj
      81 src/main/clojure/cascade.clj
    1213 total

... and that includes the ASL header comment in each file. Short and sweet.

Maintaining this chart seems like something I should automate at some point, however: It should be possible to use the reader to parse a Clojure source file without evaluating it; the first form should be the (ns), from which can be expanded the used and required namespaces (with a bit of effort, because of Clojure's very concise syntax). One more project for the back burner ...

Thursday, August 27, 2009

Return to Independent Consulting

I'd like to announce to the Tapestry community that I've returned to independent consulting. As an independent consultant, I'll have more opportunities to pursue training, mentoring, and project work that did not fit with Formos' overall goals.

Formos continues to be committed to Tapestry, and to maintaining the Tapestry360 web site. I'd like to thank Matt Tunnel, President of Formos, for the opportunities he's provided: a "dream job" that let me focus on completing Tapestry 5.0 and 5.1, with a scope of features far beyond what I had originally envisioned when I started Tapestry 5 over four years ago.

Now is a new chapter; I'm starting to search for my next dream job, while actively seeking out new Tapestry training, mentoring and support projects, as well as working with my existing clients. In addition, I'm using my improved freedom to pursue other important technologies beyond Tapestry, such as Clojure, Cappuccino, and CouchDB. I expect to be able to offer the same kind of compelling training and project work in these technologies as I currently provide for Tapestry.

I'm also taking this time to pursue one of the opportunities I could not take on while at Formos: a Tapestry 5 book. I'm currently contacting a number of different publishers to find the best home for a new book specifically about Tapestry 5.

I'd also like to thank the Tapestry community for all the enthusiasm and dedication that you've given to Tapestry. I'm looking forward to helping you create even more insanely great applications!

Sunday, August 16, 2009

Article: Meta-Programming Java

In the last couple of years, if you mention the term meta-programming, people's ears perk up ... and they start looking around for Ruby. That's fair; Ruby makes a lot of meta-programming concepts very, very easy. However, that doesn't mean you can't do any meta-programming in Java; you just are a bit more limited and need a lot more infrastructure.

Tapestry 5, both the web framework and the underlying Inversion of Control container, is rife with meta-programming options. Let's talk about one of the most versatile: the thunk.

Thunks and Laziness

A thunk is a placeholder for a value to be computed as-needed. The Haskell programming language makes great use of these; thunks are the essense of lazy programming: each thunk represents a set of parameters to a function1 and the function itself.

The upshot of this is that when you see a function call (or other expression) in Haskell code, what really happens is that a thunk of the invocation of that function is created to capture the values to be passed in (some of which may themselves be thunks of other expressions). Its only when the value is needed, when the result of the expression is used in some other expression that is evaluated, that the thunk itself gets evaluated; the function is invoked, the return value is cached in the thunk and returned. This makes the order in which things happen in Haskell very difficult to predict, especially from the outside. Because of thunks, algorithms that look tail recursive aren't (the recursive call is just another thunk, evaulated serially). Further, algorithms that appear to be infinite, aren't: the thunks ensure that just values that are actually needed are ever computed.

It's an elegant and powerful approach, and it's even fast, because the fastest code is the code that is never executed in the first place.

Other languages have this feature; Clojure reflects its Lisp heritage in that almost everything operates in terms of accessing, iterating and transforming collections ... and all of those collection operations are lazy as well. Unlike Haskell, this is more a function of a carefully crafted standard library than a direct offshoot of the language, but the end result is quite similar.

But what happens when you want to accomplish some of these features (such as lazy evaluation) within the tight constraints of standard Java? That's when you need to get creative!

Thunks in Tapestry 5

Tapestry 5 uses thunks in many different places; the most common one is the use of proxies for Tapestry 5 IoC services. In Tapestry 5 every service has an interface2. Let's take a peek at a typical service in Tapestry 5, to illustrate the typed-thunk concept.

Listing 1: ComponentMessagesSource.java

public interface ComponentMessagesSource
{
    Messages getMessages(ComponentModel componentModel, Locale locale);

    InvalidationEventHub getInvalidationEventHub();
}

The purpose of the ComponentMessagesSource service is to provide a Messages object representing a particular component's message catalog. This is part of Tapestry's localization support: every page and component has easy access to its own message bundle, which includes messages inherited from base components and from a global message catalog.

A central tenet of Tapestry 5 is that service instantiation is lazy: services are only constructed as needed. What does "as needed" mean? It means, the first time any method of the service is invoked. This kind of lazy instantiation is accomplished by using thunks. So for a service such as ComponentMessagesSource, there will be a class somewhat like ComponentMessagesSourceThunk to handle the lazy instantiation:

Listing 2: ComponentMessagesSourceThunk.java

public interface ComponentMessagesSourceThunk implements ComponentMessagesSource
{
    private final ObjectCreator creator;

    public ComponentMessagesSourceThunk(ObjectCreator creator) { this.creator = creator; }

    private ComponentMessagesSourceThunk delegate() { return (ComponentMessagesSourceThunk) creator.createObject(); }

    public Messages getMessages(ComponentModel componentModel, Locale locale)
    {
        return delegate().getMessages(componentModel, locale);
    }

    public InvalidationEventHub getInvalidationEventHub()
    {
        return delegate().getInvalidationEventHub();
    }
}

You won't find the above class in the Tapestry source code: it is generated on-the-fly by Tapestry. That's great, because I know I'd hate to have to supply a service interface, a service implementation and a thunk class for each service; the interface and implementation is already plenty! One of the reasons that Tapestry all but requires that services have a service interface is to support the automatic creation of thunks or other proxies around the interface.

However, you can see the pattern: every method of the interface is, of course, implemented in the thunk. That's what it means to implement an interface. Each method obtains the delegate and then re-invokes the same method with the same parameters on the delegate. The trick is that the first time any of these methods are invoked, the delegate does not yet exist. The ObjectCreator will create the delegate object during that first invocation, and keep returning it subsequently. That's the essence of lazy instantiation.

The point here is that for any interface, you can create a typed-thunk that can stand in for the real object, hiding the real object's lifecycle: it gets created on demand by the ObjectCreator. Code that uses the thunk has no way of telling the thunk from the real objects ... the thunk implements all the methods of the interface and performs the right behaviors when those methods get invoked.

Creating Thunks Dynamically

Before we can talk about using thunks, we need to figure out how to create them dynamically, at runtime. Let's start by specifying the interface for a service that can provide thunks on demand, then figure out the implementation of that service.

Listing 3: ThunkCreator.java

public interface ThunkCreator
{
    /**
     * Creates a Thunk of the given proxy type.
     *
     * @param proxyType     type of object to create (must be an interface)
     * @param objectCreator provides an instance of the same type on demand (may be invoked multiple times)
     * @param description   to be returned from the thunk's toString() method
     * @param <T>           type of thunk
     * @return thunk of given type
     */
    <T> T createThunk(Class<T> proxyType, ObjectCreator objectCreator, String description);
}

Remember that this is just an automated way of producing instances of classes similar to ComponentMessagesSourceThunk. A simple implementation of this service is possible using JDK Proxies:

Listing 4: ThunkCreatorImpl.java

public class ThunkCreatorImpl implements ThunkCreator
{
    public <T> T createThunk(Class<T> proxyType, final ObjectCreator objectCreator, final String description)
    {
        InvocationHandler handler = new InvocationHandler()
        {
            public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
            {
                if (method.getName().equals("toString") && method.getParameterTypes().length == 0)
                    return description;

                return method.invoke(objectCreator.createObject(), args);
            }
        };

        Object proxy = Proxy.newProxyInstance(Thread.currentThread().getContextClassLoader(),
                                              new Class[] { proxyType },
                                              handler);

        return proxyType.cast(proxy);
    }
}

JDK Proxies were introduced way back in JDK 1.3 and caused a real flurry of activity because they are so incredibly useful. A call to Proxy.newProxyInstance() will create an object conforming to the provided interfaces (here specified as the proxyType parameter). Every method invocation is routed through a single InvocationHandler object. The InvocationHandler simply re-routes method invocations to the object returned from objectCreator.createObject().

Tapestry's implementation of ThunkCreator uses the Javassist bytecode manipulation library to generate a custom class at runtime. The generated class is much closer to the example CompnentMessagesSourceThunk; it doesn't use JDK proxies or reflection. This means that Java's Hotspot compiler can do a better job optimizing the code. In reality, you'll be hard pressed to spot a difference in performance unless you use these thunks inside a very tight loop.

Great so far; now lets think about how we could use this in another way. What if you have a service that returns an object that is expensive to construct and may not even get used? An example of this in Tapestry is the Messages object, obtained from the ComponentMessagesSource service. Building a Messages instance for a component involves a lot of hunting around the classpath looking for properties files, not just for the component but for its base-class and for application-wide message bundles. That means a lot of I/O and and a lot of blocking, waiting for the disk drive to catch up. In many cases, these Messages objects are injected into components, but aren't used immediately. In terms of getting markup into the user's browser faster, avoiding all of those file lookups and file reads until absolutely necessary is an appreciable win.

Our goal is to intercept the call to ComponentMessagesSource.getMessages() and capture the parameters to the method. Instead of invoking the method, we want to return a thunk that encapsulates the method call. This is where we can really start to talk about meta-programming, not just programming: we aren't going to change the ComponentMessagesSource service implementation to accomplish this, we are going to meta-program the service. This is a key point: A Tapestry service is the sum of its interface, its implementation, and all the other parts provided by Tapestry. We can use Tapestry to augment the behavior of a service without changing the implementation of the service itself.

This approach is in stark contrast to, say, Ruby. When meta-programming Ruby you often end up writing and rewriting the methods defined by the class in place. In Java, you will instead layer on new objects implementing the same interface to provide the added behavior.

Accomplishing all this is suprisingly easy ... given the infrastructure that Tapestry 5 IoC already provides.

Lazy Advice

The goal with lazy advice is that invoking a method on a service short-circuits the method invocation: a thunk is returned that is a replacement for the return value of the method. Invoking a method on a thunk will invoke the actual service method, then re-invoke the method on the actual value returned from the method.

Image 1: Lazy Advice Thunk/

This is shown in image 1. The service method is represented by the blue line. The advice intercepts the call (remembering the method parameters) and returns a thunk. Later, the caller invokes a method on the thunk (the green line). The thunk will invoke the service method using the saved parameters (this is the lazy part), then re-invoke the method on the returned value.

To the caller, there is no evidence that the thunk even exists; the service method just returns faster than it should, and the first method invocation on the return value takes a little longer than it should.

Now we know what the solution is going to look like .. but how do we make it actually happen? How do we get "in there" to advise service methods?

Advising Service Methods

Tapestry's Inversion of Control Container is organized around modules: classes that define services. This is in contrast to Spring, which relies on verbose XML files. Tapestry uses a naming convention to figure out what methods of a module class do what. Methods whose name starts with "build" define services (and are ultimately used to instantiate them). Other method name prefixes have different meanings.

Module method names prefixed with "advise" act as a hook for a limited amount of Aspect Oriented Programming. Tapestry allows an easy way to provide around advice on method invocations ... a more intrusive system such as AspectJ can easily intercept access to fields or even the construction of classes and has more facilities for limiting the scope of advice so that it only applies to invocations in specific classes or packages. Of course, it works by significantly rewriting the bytecode of your classes and Tapestry's IoC container aims for a lighter touch.

Being able to advise service methods was originally intended to support logging of method entry and exit, or other cross-cutting converns such as managing transactions or enforcing security access constraints. However, the same mechanism can go much further, controlling when method invocations occur, in much the same way that the lazy thunk described above operates.

Listing 5 shows the method advice for the ComponentMessagesSource service.

Listing 5: TapestryModule.java

    @Match("ComponentMessagesSource")
    public static void adviseLazy(LazyAdvisor advisor, MethodAdviceReceiver receiver)
    {
        advisor.addLazyMethodInvocationAdvice(receiver);
    }

This method is used to advise a specific service, identified by the service's unique id, here "ComponentMessagesSource". An advisor method may advise many different services; we could use glob names or regular expressions to match a wider range of services. An advisor method recieves a MethodAdviceReceiver as a parameter; additional parameters are injected services. The intent of module classes is to contain a minimal amount of code, so it makes sense to move the real work into a service, especially because it is so easy to inject services directly into the advisor method.

The LazyAdvisor service, built into Tapestry, does most of the work:

Listng 6: LazyAdvisorImpl.java

public class LazyAdvisorImpl implements LazyAdvisor
{
    private final ThunkCreator thunkCreator;

    public LazyAdvisorImpl(ThunkCreator thunkCreator)
    {
        this.thunkCreator = thunkCreator;
    }

    public void addLazyMethodInvocationAdvice(MethodAdviceReceiver methodAdviceReceiver)
    {
        for (Method m : methodAdviceReceiver.getInterface().getMethods())
        {
            if (filter(m))
                addAdvice(m, methodAdviceReceiver);
        }
    }

    private void addAdvice(Method method, MethodAdviceReceiver receiver)
    {
        final Class thunkType = method.getReturnType();

        final String description = String.format("<%s Thunk for %s>",
                                                 thunkType.getName(),
                                                 InternalUtils.asString(method));

        MethodAdvice advice = new MethodAdvice()
        {
            /**
             * When the method is invoked, we don't immediately proceed. Intead, we return a thunk instance
             * that defers its behavior to the lazily invoked invocation.
             */
            public void advise(final Invocation invocation)
            {
                ObjectCreator deferred = new ObjectCreator()
                {
                    public Object createObject()
                    {
                        invocation.proceed();

                        return invocation.getResult();
                    }
                };

                ObjectCreator cachingObjectCreator = new CachingObjectCreator(deferred);

                Object thunk = thunkCreator.createThunk(thunkType, cachingObjectCreator, description);

                invocation.overrideResult(thunk);
            }
        };

        receiver.adviseMethod(method, advice);
    }

    private boolean filter(Method method)
    {
        if (method.getAnnotation(NotLazy.class) != null) return false;

        if (!method.getReturnType().isInterface()) return false;

        for (Class extype : method.getExceptionTypes())
        {
            if (!RuntimeException.class.isAssignableFrom(extype)) return false;
        }

        return true;
    }
}

The core of the LazyAdvisor service is in the addAdvice() method. A MethodAdvice inner class is defined; the MethodAdvice interface has only a single method, advise(). The advise() method will be passed an Invocation that represents the method being invoked. The Invocation captures parameters passed in as well as the return value or any checked exceptions that are thrown. Invoking the proceed() method continues on to the original method of the service3.

At this point, the thunk encapsulates the original method invocation; we even have an object for that: the Invocation instance originally passed to the advise() method. Invoking any method on the thunk will cause the ObjectCreator.createObject() method to be triggered: this is where we finally invoke proceed() and return the value for the lazily invoked method.

Other uses for Thunks

In essence, this thunk approach gives you the ability to control the context in which a method is executed: is it executed right now, or only when needed? It is only a little jump from that to executing the method in a background thread. In fact, Tapestry includes a ParellelExecutor service that can be used for just that.

Conclusion

Type-safe thunks are a powerful and flexible technique for controlling when (or even if) a method is invoked without sacrificing type safety. Unlike more intrusive techniques that rely on manipulating the bytecode of existing classes, type-safe thunks can be easily and safely introduced into existing code bases. More than that, this exercise opens up many exciting possibilities: these techniques (coding to interfaces, multiple objects with the same interface, delegation) open up a path to a more fluid, more responsive, more elegant approach to coding complex behaviors and interactions ... while reducing the total line count and complexity of your code.

One of the things I am most happy about in Tapestry is the way in which we can build up complex behaviors from simple pieces. Everything stacks together, concisely and with minimum fuss:

  • We can create a thunk around an ObjectCreator, to defer the instantiation of an object
  • We can capture a method invocation and convert that into an ObjectCreator and a lazy thunk
  • We can advise a method without changing the actual implementation, to provide the desired laziness
  • Tapestry can call an advisor method of our module when constructing the ComponentMessagesSource service
  • We can inject services that do the advising right into advisor methods

Footnotes

1 Actually, all functions in Haskell take exactly one parameter which is both mind-blowing and not relevant to the discussion.

2 Services can be based on classes rather than interfaces, but then you lose a lot of these interface-based features, such as lazy proxies.

3Or, if the method has been advised multiple times, invoking proceed() may invoke the next piece of advice. For example, you may have added advice to a method for logging method entry and exit, and for managing database transactions as well as lazy evaluation.