AspectJ is a powerful and mature aspect oriented programming (AOP) framework that underpins many large-scale systems. Spring Framework has offered extensive support for AspectJ since 2004, with Spring 2.0 adopting AspectJ's pointcut definition language even for expressing Spring AOP pointcuts. Many of the official Spring projects offer support for AspectJ or are themselves heavily dependent on it, with several examples including Spring Security (formerly Acegi Security System for Spring), Spring Insight, SpringSource tc Server, SpringSource dm Server, Spring Enterprise and Spring Roo.

While AspectJ is most commonly known for its aspect oriented programming (AOP) features such as applying advice at defined pointcuts, Roo projects use AspectJ's powerful inter-type declaration (ITD) features. This is where the real magic of Roo comes from, as it allows us to code generate members (artifacts like methods, fields etc) in a different compilation unit (i.e. source file) from the normal .java code you'd write as a developer. Because the generated code is in a separate file, we can maintain that file's lifecycle and contents completely independently of whatever you are doing to the .java files. Your .java files do not need to do anything unnatural like reference the generated ITD file and the whole process is completely transparent.

Let's have a look at how ITDs work. In a new directory, type the following commands and note the console output:

roo> project --topLevelPackage com.aspectj.rocks
roo> jpa setup --database HYPERSONIC_IN_MEMORY --provider HIBERNATE
roo> entity jpa --class ~.Hello
Created SRC_MAIN_JAVA/com/aspectj/rocks
Created SRC_MAIN_JAVA/com/aspectj/rocks/Hello.java
Created SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_JpaActiveRecord.aj
Created SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_JpaEntity.aj
Created SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_ToString.aj
Created SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_Configurable.aj
roo> field string --fieldName comment
Managed SRC_MAIN_JAVA/com/aspectj/rocks/Hello.java
Managed SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_JavaBean.aj
Managed SRC_MAIN_JAVA/com/aspectj/rocks/Hello_Roo_ToString.aj

Notice how there is a standard Hello.java file, as well as a series of Hello_Roo_*.aj files. Any file ending in *_Roo_*.aj is an AspectJ ITD and will be managed by Roo. You should not edit these files directly, as Roo will automatically maintain them (this includes even deleting files that aren't required, as we'll see shortly).

The Hello.java is just a normal Java file. It looks like this:

package com.aspectj.rocks;

import org.springframework.roo.addon.javabean.RooJavaBean;
import org.springframework.roo.addon.tostring.RooToString;
import org.springframework.roo.addon.entity.RooJpaActiveRecord;

@RooJavaBean
@RooToString
@RooJpaActiveRecord
public class Hello {

    private String comment;
}

As shown, there's very little in the .java file. There are some annotations, plus of course the field we added. Note that Roo annotations are always source-level retention, meaning they're not compiled into your .class file. Also, as per our usability goals you'll note that Roo annotations also always start with @Roo* to help you find them with code assist.

By this stage you're probably wondering what the ITD files look like. Let's have a look at one of them, Hello_Roo_ToString.aj:

package com.aspectj.rocks;

import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

privileged aspect Hello_Roo_ToString {

    public String Hello.toString() {
          return ReflectionToStringBuilder.toString(this, ToStringStyle.SHORT_PREFIX_STYLE);
    }
    
}

Notice how the ITD is very similar to Java code. The main differences are that it is declared with "privileged aspect", plus each member identifies the target type (in this case it is "Hello.toString", which means add the "toString" method to the "Hello" type). The compiler will automatically recognize these ITD files and cause the correct members to be compiled into Hello.class. We can see that quite easily by using Java's javap command. All we need to do is run the compiler and view the resulting class. From the same directory as you created the project in, enter the following commands and observe the final output:

$ mvn compile
$ javap -classpath target/classes/.:target/test-classes/. com.aspectj.rocks.Hello
Compiled from "Hello.java"
public class com.aspectj.rocks.Hello extends java.lang.Object implements org.springframework.beans.factory.aspectj.ConfigurableObject{
    transient javax.persistence.EntityManager entityManager;
    public com.aspectj.rocks.Hello();
    public static java.lang.String ajc$get$comment(com.aspectj.rocks.Hello);
    public static void ajc$set$comment(com.aspectj.rocks.Hello, java.lang.String);
    public static java.lang.Long ajc$get$id(com.aspectj.rocks.Hello);
    public static void ajc$set$id(com.aspectj.rocks.Hello, java.lang.Long);
    public static java.lang.Integer ajc$get$version(com.aspectj.rocks.Hello);
    public static void ajc$set$version(com.aspectj.rocks.Hello, java.lang.Integer);
    static {};
    public static long countHelloes();
    public static final javax.persistence.EntityManager entityManager();
    public static java.util.List findAllHelloes();
    public static com.aspectj.rocks.Hello findHello(java.lang.Long);
    public static java.util.List findHelloEntries(int, int);
    public void flush();
    public java.lang.String getComment();
    public java.lang.Long getId();
    public java.lang.Integer getVersion();
    public com.aspectj.rocks.Hello merge();
    public void persist();
    public void remove();
    public void setComment(java.lang.String);
    public void setId(java.lang.Long);
    public void setVersion(java.lang.Integer);
    public java.lang.String toString();
}

While the javap output might look a little daunting at first, it represents all the members that Roo has added (via AspectJ ITDs) to the original Hello.java file. Notice there isn't just the toString method we saw in the earlier ITD, but we've also made the Hello class implement Spring's ConfigurableObject interface, provided access to a JPA EntityManager, included a range of convenient persistence methods plus even getters and setters. All of these useful features are automatically maintained in a round-trip compatible manner via the ITDs.

A careful reader might be wondering about the long field names seen for introduced fields. You can see that these field names start with "ajc$" in the output above. The reason for this is to avoid name collisions with fields you might have in the .java file. The good news is that you won't ever need to deal with this unless you're trying to do something clever with reflection. It's just something to be aware of for introduced fields in particular. Note that the names of methods and constructors are never modified.

Naturally as a normal Roo user you won't need to worry about the internals of ITD source code and the resulting .class files. Roo automatically manages all ITDs for you and you never need deal with them directly. It's just nice to know how it all works under the hood (Roo doesn't believe in magic!). The benefit of this ITD approach is how easily and gracefully Roo can handle code generation for you.

To see this in action, go and edit the Hello.java in your favourite text editor with Roo running. Do something simple like add a new field. You'll notice the Hello_Roo_ToString.aj and Hello_Roo_JavaBean.aj files are instantly and automatically updated by Roo to include your new field. Now go and write your own toString method in the .java file. Notice Roo deletes the Hello_Roo_ToString.aj file, as it detects your toString method should take priority over a generated toString method. But let's say you want a generated toString as well, so change the Hello.java's @RooToString annotation to read @RooToString(toStringMethod="generatedToString"). Now you'll notice the Hello_Roo_ToString.aj file is immediately re-created, but this time it introduces a generatedToString method instead of the original toString. If you comment out both fields in Hello.java you'll also see that Roo deletes both ITDs. You can also see the same effect by quitting the Roo shell, making any changes you like, then restarting the Roo shell. Upon restart Roo will automatically perform a scan and discover if it needs to make any changes.

Despite the admittedly impressive nature of ITDs, AspectJ is also pretty good at aspect oriented programming features like pointcuts and advice! To this end Roo applications also use AspectJ for all other AOP requirements. It is AspectJ that provides the AOP so that classes are dependency injected with singletons when instantiated and transactional services are called as part of method invocations. All Roo applications are preconfigured to use the Spring Aspects project, which ships as part of Spring Framework and represents a comprehensive "aspect library" for AspectJ.

Spring Roo applications all use Spring. By "Spring" we not only mean Spring Framework, but also the other Spring projects like Spring Security and Spring Web Flow. Of course, only Spring Framework is installed into a user project by default and there are fine-grained commands provided to install each additional Spring project beyond Spring Framework.

All Roo applications use Spring Aspects, which was mentioned in the AspectJ section and ensures Spring Framework's @Configurable dependency injection and transactional advice is applied. Furthermore, Roo applications use Spring's annotation-driven component scanning by default and also rely on Spring Framework for instantiation and dependency injection of features such as JPA providers and access to database connection pools. Many of the optional features that can be used in Roo applications (like JMS and SMTP messaging) are also built upon the corresponding Spring Framework dependency injection support and portable service abstractions.

Those Roo applications that include a web controller will also receive Spring Framework 3's MVC features such as its conversion API, web content negotiation view resolution and REST support. It is possible (and indeed encouraged) to write your own web Spring MVC controllers in Roo applications, and you are also free to use alternate page rendering technologies if you wish (i.e. not just JSP).

Generally speaking Roo will not modify any Spring-related configuration or setting file (e.g. properties) unless specifically requested via a shell command. Roo also ensures that whenever it creates, modifies or deletes a file it explicitly tells you about this via a shell message. What this means is you can safely edit your Spring application context files at any time and without telling Roo. This is very useful if the default configuration offered by Roo is unsuitable for your particular application's needs.

Because Spring projects are so extensively documented, and Roo just uses Spring features in the normal manner, we'll refrain from duplicating Spring's documentation in this section. Instead please refer to the excellent Spring documentation for guidance, which can be found in the downloadable distribution files and also on the Spring web site.

Roo supports a number of Maven packaging types out of the box, such as jar, war, pom, and bundle. These are provided via Roo's PackagingProvider interface. If you wish to customise the POMs or other artifacts that Roo generates for a given packaging type when creating a project or module, either for one of the above packaging types or a completely different one, you can implement your own PackagingProvider that creates exactly the files you want with the contents you want. The procedure for doing this is as follows:

Since version 1.2.0, Roo supports multi-module Maven projects, i.e. those containing multiple projects in a nested directory structure, each with their own POM. The non-leaf POMs have "pom" packaging and the leaf POMs usually have an artifact creation packaging (jar, war, etc). If you're not familiar with multi-module projects and want to see how they're structured, there's an embedded multimodule.roo script that generates a simple multi-module project; used as follows:

The rest of this section assumes that you are familiar with multi-module projects, in particular the difference between POM inheritance (one POM has another as its parent) and project nesting (one project is in a sub-directory of another, i.e. is a module of that parent project).