MACAW

Copyright (C) 2003 Philip Dorrell

MACAW standards for Methods And Classes All Webified. It is a Java application framework layered over Freemarker. It also includes a basic integration with Hibernate, which is contained within the macaw.database package, but this is merely to wrap method invocations within transactions: a similar wrapping can be defined for any other persistence framework.

Example Application

In lieu of more substantial documentation which is yet to be written, the best way to find out more about MACAW is to look at the application that it was initially written for, which is Womcat Bookmarks. Currently the Womcat Bookmarks application source code comes bundled with the installer.

Concepts

The main concept behind MACAW is that each web page is in some sense about an application object. Following this line of thinking, each HTML form submission maps to a method call on an application object.

There are three main layers in a MACAW application:

• Freemarker templates.
• Webified Objects. Webified methods invoked on webified objects return Freemarker templates. If a return value contains a webified object, this is mapped to the template variable object in the template.
• Application objects. These are ordinary Java objects that know nothing about the fact that they are part of a web application.

MACAW includes the following:

• Extensible mapping of various parameter value types to HTML form parameters.
• Each webified object belongs to a webified class.
• In the templates standard variables are used to store page data, including object for a reference to the webified object that the page is "about", and message for any message relating to the previous action.
• For pages invoked by simple links, links take the form of "${object.url}", which uses the default template for that class of webified object, or "${object.url}&t=template-name", which specifies a particular template.
• For forms, a special "form" tag is defined. This is used in a template as follows (assuming object is of webified class "Employee" mapped to Java class WEmployee):

  <@form object=object.manager method="sendMessage"/>
  <input type="text" name="p.text" cols="60"/>
  <@resultPage page="MessageSent"/>
  </@form>
  

  The ".manager" property would correspond to a method in class WEmployee:

     public WManager var_manager() {
       // get manager somehow
     }
  

  "var_" is a prefix indicating a method used to get a property value of a webified object.

  The form "method" attribute of "sendMessage" corresponds to invoking the following method:

    public SimpleHash web_sendMessage_text_U (String text) throws Exception {
      WMessage message = // send a message to the manager somehow
      return message.getResult ("Message sent");
    }
  

  The "p.text" parameter gets mapped to the "text" parameter of the method. The "_text" gets appended onto the Java method name because Java's run-time reflection doesn't know anything about parameter names (they get lost during compilation). A standard mapping is defined for java.lang.String parameters.

  "web_" is a general prefix indicating methods to be invoked from forms. The "_U" specifies that the method is an "update" method which can only be invoked from a form which is verified to have been created by the application itself. (This is to protect against the "Hostile URL" problem where links or forms from one web page attempt to access an internal web application.)

  "getResult" is a standard method that wraps a webified object into a Freemarker template in the standard way expected by the Freemarker templates. Thus the returned template is a map that maps "object" to the WMessage object and "message" to "Message sent".

  You can also use a @result tag to override the result object used to determine the page displayed after submitting the form. For example:

  <@form object=object method="addChild">
  <input type="text" name="p.child" cols="60"/>
  <@result object=object/>
  <@form>
  

  Here the webified method "addChild" returns a result that wraps the newly created child, but actually we want to redisplay the current object. The "<@result object=object/>" tag over-rides the object returned by the method.

• In cases where there may be a choice of template to display the result of an invocation, there can be multiple "<@resultPage" elements with "result" attributes defined to map to corresponding templates named in the "page" element. The webified method on the webified class only has to know the set of "result" values that it can include in the returned template object (with the result mapped to "result"). In effect both user interface and workflow are controlled within the upper template layer of the application. There are no explicit references to templates in the Java code.
• An application defines where on the classpath templates are to be found, and also the translation of webified class names to actual Java class names. For example webified class "Person" might map to "myapplication.WPerson". (Use of a class name prefix avoids collisions as would otherwise occur between "Person" and "WPerson".)
• You can serve static files from classpath resources (for example style sheets and images).

Download

Latest version: macaw.v1.1.jar

Release Notes

• 1.0 Initial Release
• 1.1 Add </@result> tag.
• 1.2 Add array parameters.

Roadmap

The conventions used to map template properties and form methods and parameters to Java methods are a bit clunky. One particular problem is that compiled Java method parameters do not have names, which is of course incompatible with HTML form parameters that are explicitly named. The MACAW framework is defined in terms of interface classes WebifiedApplication, WebifiedClass, WebifiedObject and WebifiedMethod. The conventions given above are contained within the default implementations of these interfaces provided in the framework. This leaves open the possibility of using Java attributes, when they become available, or using some existing Java extension that does attributes, as an alternative way of exposing methods with named parameters (and update/non-update flag) to the templates.

Licence

MACAW is licenced under the LGPL

Source Code for LGPL libraries

Hibernate 1.2.5

Powered by ...