Powered by Twitter Tools

Powered by Twitter Tools

Powered by Twitter Tools

Here are my recommended order of repositories:

// use Grails home first as it is local and quick and resolves all the standard Grails libraries quickly
grailsHome()
 
// use maven home next if, and only if, you use maven so that your local dependencies are found quickly
mavenLocal()
 
// use your companies' Nexus repository that also proxies maven central and other repos
// if you do not use maven, then do not use this or include it much later in the process
// this only has value this high in the order if several of your dependencies use maven
// or if the repository is in house on the same network
mavenRepo "http://maven.company.org/..."
 
// use grails plugins next as it will resolve all the other plugins you use
// if you use more plugins than you do libraries, then reference grails plugins first
// before any maven repository
grailsPlugins()
grailsCentral()
 
// use maven central as a last step...again, only include this if you use maven libraries
// also, do NOT use this if your in house Maven/Nexus repo proxies maven central
mavenCentral()
 
// include any other maven repository not included in mavenCentral or your Nexus configuration
// these are always one-offs typically so they should be last
mavenRepo "http://company.org/maven/..."

The most important part is to only include the repositories you know you need. For example, if you have a company Nexus repository that proxies maven central, then only include one or the other, not both. These rules are not meant in any way to be a firm stake, but something to give you context so you put thought into the ordering and how your environment, code, dependencies, and plugins work together. After all, development time is precious.

public class Base {
    public Number getValue() { return null; }
}
 
public class Int extends Base {
    public Integer getValue() { return Integer.valueOf(1); }
}

Java allows you to override the return type of subclasses as long as the overridden type is compatible. Behind the scenes, the compiler creates two methods in the actual Int class:

public getValue()Ljava/lang/Integer;
public volatile bridge getValue()Ljava/lang/Number;

The first method is the overridden return type and the actual method that is invoked. The second method is a bridge method created by the compiler. The bridge method purely invokes the first method but returns the value cast as a Number. This has to occur since dependent classes that depend on the Base class can receive the expected Number return type whereas classes depending on Int directly can have the return type as an Integer.

Generics has the same problem with using the typed variable as the return value:

public class Base<T extends Number> {
    public T getValue() { return null; }
}
 
public class Int extends Base<Integer> {
    public Integer getValue() { return Integer.valueOf(1); }
}

This again results in two methods for the getValue method.

The reason I mention this is that if you were to invoke java.beans.Introspector.getBeanInfo(Int.class) and then lookup the property for the value property, the property type and read method would be the bridge methods on some systems. It is actually random since there is no defined ordered of methods in the class file format, so whichever appears first is the one that is selected. On some machines that may be the Integer-based method, while on others it will be the bridge method. In my opinion this is a huge gaping issue as several libraries depend on the underlying java.beans framework including Commons Beanutils. They all exhibit similar issues as they all rely on the JDK.

This is actually worse than just the return types. For example, if you have or use a library built around iterating the properties and then checking the read method for annotations, you may get the wrong method. If the bridge method is returned it will not have any annotations on it. Instead you would need to get the proper method to read the annotations. This can cause unexpected issues that would be fairly hard to diagnose and debug.

Hopefully this will be resolved in JDK 7. Until then, I have to fix my local code to hack the introspection library to walk each property, check if the read method is a bridge method and if so, lookup the actual method. Here is a quick example on how to do that:

// lookup bean info for given class
BeanInfo info = Introspector.getBeanInfo(clazz);
if (info != null) {
    // get list of descriptors and iterate to validate each property
    PropertyDescriptor[] descriptors = info.getPropertyDescriptors();
    for (int i = 0; i < descriptors.length; i++) {
        PropertyDescriptor descriptor = descriptors [i];
 
        // check if read method is bridge and lookup real method
        Method readMethod = descriptor .getReadMethod();
        if (readMethod != null && readMethod.isBridge()) {
            Method method = clazz.getMethod(
                readMethod.getName(), readMethod.getParameterTypes()
            );
 
            // if method found, update read method
            // which also updates property type
            if (method != null) {
                descriptor.setReadMethod(method);
 
                // TODO: lookup write method with same type in case the write
                // method is the bridge method
            }
        }
    }
 
    // return array of found descriptors
    return descriptors;
}

You would most likely want to perform similar logic on the write methods as write methods may also have bridge methods when dealing with generics. In this case, I would suggest looking up a setXyz method where the singular parameter type is the same as the return type from the newly found read method. If the method is found, replace the existing write method with that method.

If you are wondering why getMethod returns only the non-bridged type whereas calling getMethods returns both methods in the array, the answer lies in the source code for that method in the java.lang.Class class. The getMethod call eventually invokes private static Method searchMethods. That search method has a condition on it that it loops through all methods that match the name but the array does not terminate early upon first match. Instead, it keeps searching and if another matching method is found, then it uses the one with the more precise return type (ie: covariant returns). Since covariant returns must always be subclasses of the base, the method just finds the return type with the lowest subclass, which should be the non-bridge method.

For more information, see the following JDK bugs on the topic:

• http://bugs.sun.com/view_bug.do?bug_id=6788525
• http://bugs.sun.com/view_bug.do?bug_id=6888164
• http://bugs.sun.com/view_bug.do?bug_id=6707230

The most simple way of creating modules is using sub-templates in Grails. A sub-template in Grails is a GSP that starts with a leading underscore. This tells Grails that the template is a sub-template that does not live on its own but rather expects some other page or sub-template to invoke it. Let’s say we want to include a login form on a variety of pages. The login form is self-encompassing and can live on its own in terms of data models. First, create a _loginForm.gsp file and include it in a new view directory called login. You can actually place the sub
template in any view directory, but for this exercise, we will assume it is in the login directory.

<g:form controller="login" action="login">
    <g:textField name="username" />
    <g:passwordField name="password" />
</g:form>

Now to include that login form on any page, simply do <g:render template="/login/loginForm" /> We have now separated out the common login form from the main page. This method works great when the content is common and has no data associated with it. What if the sub-template required some form of model or data, though?

Let’s look at a widget that displayed a ‘Similar Items’ list on several pages, but the list of items was tied to the page displaying the widget. For example, an electronics section may show other electronics, but a book section may show other books. In this scenario, the sub-template does not know what the list of data should be, so it has to be provided. This can again use sub-templates, but this time we can pass data into it. Sub-templates can take a model as a map of variables to values such that the passed in variable names are available to be used within the sub-template. Create a new sub-template in the modules view directory named _similarItems.gsp.

<h3>Similar Items : ${title}</h3>
<ul>
<g:each var="item" in="${items}">
    <li>${item}</li>
</g:each>
</ul>

This sub-template expects a ‘title’ and list of ‘items’. We can now have various pages call this sub-template and provide the required model:

<g:render template="/modules/similarItems" 
          model="[title:'Books', items:[ 'Groovy in Action', 'Grails in Action' ]]" />

Any other page can easily include that same data but changing the model as need be. You may even have the controller look up the related items from the database based on the active content being shown by the controller and then pass that data as the model of the controller so the view template can pass it to the sub-template model.

public class TestController {
    ItemsService itemsService
 
    def index() {
        def section = params.section ?: 'home'
        def items = itemsService.getItems(section)
        def related = itemsService.getRelated(section)
        [ section : section, items : items, related : related ]
    }
}

<h1>${section}</h1>
<ul>
<g:each var="item" in="${items}">
    <li>${item}</li>
</g:each>
</ul>
 
<g:render template="/modules/similarItems"
          model="[title : section, items : related ]" />

Another method to do the same thing is using the tmpl namespace in Grails.

<tmpl:similarItems title="${section}" items="${related}" />

This example is slighly easier to read as the model is provided as attributes to the tag instead of an inline map/array to the tag. The use of one or the either is entirely a choice as long as the decision is consistent to avoid confusion. For more information on the render tag, see http://grails.org/doc/2.0.x/ref/Tags/render.html.

These are the most common use cases. What if we do not need to pass any data to the sub-template, but the sub-template needs to acquire data as part of its visual rendering. For example, you may want to show a shopping cart on every page. The shopping cart will always have the same data regardless which page calls it, but it needs to retrieve its data from the ShoppingCartService. There are a few different ways to do this, again with pros and cons in each scenario.

Let’s start again with the easy way using sub-templates. Grails contains a g:set tag that allows you to set scoped variables (typically page scoped) based on some expression. The expression can then lookup services to retrieve the necessary data. Let’s create a _shoppingCart.gsp in the modules directory.

<g:set var="shoppingCart" value="${model.shoppingCart}" />
<h3>Shopping Cart</h3>
<ul>
    <g:each var="item" value="${shoppingCart.items}">
        <li>${item.name}</li>
    </e:each>
</ul>

This is fairly simple and a page can easily include without having to pass or look up any model data. However, this requires every page controller using this sub-template to define the model.shoppingCart bean as part of its model. I will show how to do that easily next. A feature request for a future version of Grails is to allow the g:set tag to include a bean attribute on the set tag to allow easier access to beans such as services. This would allow sub-templates to be independent of tag libraries and controllers.

<g:set var="shoppingCartService" bean="shoppingCartService" />

Unfortunately, that is not yet possible howerver.

As a simple example, this was pretty straightforward. However, what if you need to do a bunch of business logic or manipulation of the data. In these use cases, you would not want to purely use a sub-template as you want to avoid mixing business logic from presentation (ie: the whole principle of MVC). I’ll skip the more standard approach first and jump to a non-traditional example for the sake of demonstrating alternative options as well as explaining how to include a common model across several pages (such as the shopping cart example above).

The non-traditional way to solve this is to have the controllers do the business logic and then include the resulting data in the model. Then, the sub-template will have access to the associated data. However, if you did this in every controller, you would end up with duplicated code. So, how do you allow any controller to perform the business logic and include it in the resulting model? The answer lies in inheritance and listeners in Grails. For example, create an abstract Groovy class BaseController and then ensure each specific controller extends this base controller. The base controller can now include an interceptor that will intercept any action in any sub-class allowing modifications to the resulting model. This modification could be the result of business logic performed.

abstract class BaseController {
    ShoppingCartService shoppingCartService
 
    static afterInterceptor = { model ->
        model.shoppingCart = shoppingCartService.getShoppingCart()
    }
}

class ProductController extends BaseController {
    def productService
 
    def index(Integer productId) {
        def product = productService.getProduct(productId)
        [ 'product' : product ]
    }
}

Notice that the product controller has no notion of the business logic and associatd data for the shopping cart, yet the model that is given to the page will include the ‘shoppingCart’ bean. This clearly separates the concerns but still allows the base controller to inject the data into the model. Because the data is in the model, GSPs can now pass the data to the sub-templates:

Cart:
<g:render template="/moules/cart" model="[ cart : shoppingCart ]" />

You still use the power of sub-templates and separation of concerns. However, the downfall is that every controller using that sub-template needs to extend the base controller. If the base controller is not implemented, then the model data will be unavailable.

The more traditional way to solving this is through tag libraries. Tag libraries are powerful, very modular, and written in standard Groovy. Tag libraries are similar to tag libraries in JSP or JSF, but without all the annoying headaches of configuration. You simply create a new tag library class and it all gets autowired by Grails. Tag libraries are great for performing common logic and outputting common HTML.

class UserTagLibrary {
    static namespace = 'user'
 
    UserService userService
 
    /**
     * This displays a welcome message to the logged in user.
     *
     * @attr message Message to display to the user, defaults to 'Welcome'
     */
    def profile = { attrs, body ->
        def user = userService.getUser(session.user)
        def message = attrs.message ?: 'Welcome';
        out << "${message} ${user.firstName} ${user.lastName}"
    }
}

Tag libraries all end with the common suffix TagLibrary by convention. The first thing to note is the static namespace constant. This tells Grails what prefix to use in GSPs. By default, tag libraries default to the global Grails namespace g. Providing the namespace constant overrides that value. You will also note that tag libraries can automatically inject other services and beans. Finally, you define closures as the available tags. The closures take one argument as the list of key/value pair attributes and one argument as the optional body of the tag. You then define the logic within the closure and use the predefined out variable to send content to the page. In this example, we could write <user:profile message="Hello" /> on any page and have it generate “Welcome Nicholas Hagen” for example.

The problem, however, is that we are going back to the good ol’ days of pure Servlet programming where we are generating HTML and concatenating strings together. The Groovy Strings simplifies the concatenation, but we are still outputting HTML and having to worry about escaping characters, etc. There is a reason why JSP was created to remove the annoyance of writing HTML inline with your logic. So, what can we do to avoid this and get the power of GSP’s for HTML output and the power of tag libraries for performing business logic and generating models?

In typical Grails fashion, the answer is quite simple yet again. Tag libraries, along with controllers, can actually invoke other tag libraries. This means that the tag library can act as the business logic processor and invoke the render tag to pass the resulting data model to a GSP to actually render the contents. This is exactly what we were doing earlier, only this time the tag library is invoking render rather than the page.

class ProductTagLibrary {
    static namespace = 'p'
 
    ProductService productService
 
    /**
     * Generate a list of similar items based on a given product id.
     *
     * @attr productId REQUIRED The id of the product being displayed
     */
    def simlarItems = { attrs, body ->
        // validate the data
        def productId = attrs.productId;
        if (!productId) { throw new IllegalArgumentException('productId'); }
 
        // lookup the associated product
        def product = productService.getProduct(productId)
        if (!product) {
            out << "No product available"
            return
        }
 
        // get the name of the product section
        def section = product.section.name
 
        // lookup similar items and process
        def products = []
        def similar = productService.getSimilarItems(product)
        similar.each { it ->
            // do stuff and logic
            products << it
        }
 
        // render the similar items template passing the model
        g.render([ template:'/modules/similarItems', model:[ title: section, items:products ] ]);
    }
}

This example basically looks up a given product, finds similar products to it, performs some level of business logic against those products and then calls the sub-template to actually render the data. Instead of having pages invoke the similar items sub-template, the pages simply invoke <p:similarItems productId="${params.productId}" />. This creates a clear separation in the system. The page only knows about tags it can invoke and does not have to carry about where those tags live, what they do, etc. The tag library only has to perform business logic and setup the data model without worrying about HTML to invoke. The sub-template only has to worry about the HTML to output and not how to setup data.

One final thing I will note is there is an active GSP tags plugin that allows you to define tag libraries purely as a GSP where the only thing the tag library is doing is outputting HTML. This can come in very handy as well. However, if you have complex business logic to perform, separating the logic into a tag library and the content into a GSP is still the better option typically.

There are probably several other useful approaches other than these and feel free to drop a comment on your experiences. Ultimately, it comes down to a use case decision and strategy decsion. Here are some simple rules that I tend to follow when making decisions:

1. Use sub-templates for common code with no business logic (purely HTML output driven by an optional model)
2. Use basic tag libraries for utility functions or very short one line HTML snippets
3. Use tag libraries along with sub-templates for complex business logic and complex HTML snippets

Hopefully this posts helpd you understand the various ways of handling modular programming within Grails.

Powered by Twitter Tools

My conversation today revolved around the notion of generics with wildcards. Generics supports the notion of wildcards in a few different usecases:

List<Number> l = ...; // simple parameterized type
List<? extends Number> l = ...; // wildcard with upper bounds
List<? super Integer> l = ...; // wildcard with lower bounds
List<?> l = ...; // wildcard with no bounds (bounds to Object)

The simple parameterized type is self-explanatory and most popular. The latter non-boundary-based wildcard is also pretty self explanatory and commonly used. The wildcard with a lower bounds (? super T) is rarely used but has specific use cases, none of which I will dig into in this article. However, I do encourage you to investigate what it means and why you might want to use it (hint: the most common use case is comparables such as java.util.Collections.sort). The upper bounds wildcard, especially as it pertains to collections, is what we are interested in today.

Take the following example:

List<Animal> animals;
List<? extends Animal> animals;

Those two declarations are very similar to each other, but there is a very keen difference. The first case is saying the list will contain a possible mixture of any objects that are or extend from Animal. In other words, you could have a list containing dogs and cats, since both are animals. The second case is saying the list will contain a set of objects whose base extends from animal. That’s almost the same thing, but the difference is that the latter list has the possibility to only contain dogs or only contain cats. The first case is always open to containing a mixture. It all boils down to developer intent. The wildcard is used by a developer to basically say “I know I have a specific type of list, but I’m just not sure what that type might be at this moment”. It allows the developer to ensure that the list will only contain a given type. The first case would allow the developer to put anything in that list. If the intent is to ensure the list can only contain dogs, that would fail as you could put cats into it.

Let’s consider a use case. Consider a factory class that returns a list of a given animal. You may not know what type of animal you will get back, so you can’t type it as a specific animal. However, you still want to ensure that the caller retrieving the list treats it as a specific type and not allowing them to add other animals to it.

public class AnimalFactory {
    public static List<? extends Animal> getAnimals(String type) {
        // return either List<Dog> or List<Cat> for example
    }
 
    public static void main(String[] args) {
        List<? extends Animal> animals = getAnimals("dogs");
        animals.add(new Cat()); // this fails
    }
}

This example fails because we attempt to put a cat into a wildcarded animal list. However, if the declaration was simply List, then we could add a cat just fine. The wildcard type says that the list is typed as something specific, but it’s exact value is not yet known. Because of that reason, Java disallows you to add a cat to the list because that list may in fact be a list of dogs and that would be invalid.

List<Dog> dogs = ...;
dogs.add(new Cat()); // invalid

Let’s look at some more commonly misused examples.

List<? extends Animal> animals = new ArrayList<Dog>(); // works
List<Animal> animals = new ArrayList<Dog>(); // fails

The first example works, because ArrayList satisfies the wildcard. A list of dogs is a specific type of a list of animals. The second case, however, fails because a list of dogs is not the same thing as a list of animals. The reason is that you could add a cat to the latter list (since a cat is an aminal) and that would deem the list of dogs invalid (a cat is not a dog). The first example you cannot add a cat or a dog, since Java does not know the exact type to allow.

So, how do you add to a list when it is typed as ? extends T. The simple answer is you don’t and I believe that is one of the rationales and use cases for declaring a list in that manner. If we consider our factory example again, the use case for retrieving the list is most likely to be able to iterate and act upon it, not add or modify it. In that scenario, the following code works just fine since you know the list contains animals, you are just not sure what type. In other words, you can treat the items in the list as some form of animal generally, but you cannot change the list without knowing what the exact type is (in order to maintain the semantics of a specific type being in the list).

List<? extends Animal> animals = AnimalFactory.getAnimals(type);
for (Animal animal : animals) {
    animal.speak();
}

But what if you really, really, really need to update the list. The answer is just type cast it and away you go. After all, types in Java are erased anyways (see my type erasure blog for more information). You may get a Java warning though in doing so, but it’s just warning you that you are taking code into your your own hands and assuming responsibility (ie: possibly casting what at runtime is a list of cats into a list of dogs).

List<? extends Animal> animals = AnimalFactory.getAnimals("cats");
List<Dog> dogs = (List<Dog>) animals;
dogs.add(new Dog());
for (Dog dog : dogs) { // ack...class cast exception because the list was actually List<Cat>
   dog.bark();
}

If you were using arrays, you could not do: Dog[] dogs = (Dog[]) new Cats[] { new Cat(); }. However, that is essentially what you are saying above. Since types are erased in Java and the list is just a list at runtime, Java cannot really enforce the check as an error and instead gives you a warning stating that you may be converting a list of cats into a list of dogs which would not be possible under the normal rules of the universe.

Let’s look at one final example:

public void process(List<Animal> animals) {
    // do stuff
}
 
public void test() {
    List<? extends Animal> animals = new ArrayList<Dog>();
    process(animals); // fails
}

This example once again fails. By now you hopefully understand why. Even though you can define the dogs as ? extends Animal and then declare it as ArrayList, you still cannot pass that list into a method that expects a certain type.of animals. Even when the list is typed as List, you are still saying you have a list of some type of animal. It may be a list of cats or it may be a list of dogs in this example. The process method, however, is accepting a list that supports both cats and dogs or any other animal. It is almost the same thing but the key difference is that the declaration is saying I have a specific type of animals whereas the method is saying I support all animals. If that does not convince you, put the pieces from earlier together. Within the process method, we saw earlier we could do: animals.add(new Cat())/code>
since cat is an animal. However, we were not able to do the same when the type was ? extends Animal because we were not guaranteed to have a known type that would be satisfactory to the actual list at runtime. If that is true, then Java cannot allow you to pass in the animals variable to the method because you could add a cat or a dog or whatever to it.