In Chapter 4, Web Application Development with Spring Web MVC you saw that if you redefine a method of the *_Roo_Controller.aj file in the *Controller.java class, then Roo automatically removes that method from the *_Roo_Controller.aj file. We also saw that when you modify a @RooEntity or @RooWebScaffold annotation, it results in modification of corresponding AspectJ ITDs. Roo maintains dependency between Java types (which could be a class, interface, or a @Roo* annotation) of the Roo project using metadata identification strings, making it possible for Roo to manage code contained in AspectJ ITD when changes are made to a Java type.

Let's now look closely at the following code snippet in the activate method of MyadvancedMetadataProvider class:

metadataDependencyRegistry.
    registerDependency(PhysicalTypeIdentifier.
    getMetadataIdentiferType(), getProvidesType());

The metadataDependencyRegistry is a protected attribute defined in Roo's AbstractItdMetadataProvider class and is of type MetadataDependencyRegistry. The MetadataDependencyRegistry instance keeps track of dependencies between metadata identification strings. The registerDependency method is used to specify dependency between metadata identification strings. PhysicalTypeIdentifier represents a Roo class that creates a metadata identification string for a Java type in Roo project.

In the previous code, the PhysicalTypeIdentifier.getMetadataIdentiferType() code returns MID:org.springframework.roo.classpath.PhysicalTypeIdentifier, and MyadvancedMetadata.getMetadataIdentiferType() returns MID:com.roo.addon.myadvanced.MyadvancedMetadata. As both the metadata identification strings don't contain the Java type to which they apply, they are class-level metadata identification strings. You can create dependencies between class level-or instance-level metadata identification strings.

The MID:org.springframework.roo.classpath.PhysicalTypeIdentifier represents the upstream dependency and MID:com.roo.addon.myadvanced.MyadvancedMetadata represents the downstream dependency. When changes are made to an upstream dependency, Roo takes care of notifying all the downstream dependencies, which results in recreating the downstream metadata. The MetadataProviders are responsible for handling the notification. So, in the case of the myadvanced add-on, when a Java type (represented by MID:org.springframework.roo.classpath.PhysicalTypeIdentifier) in the Roo project is changed, it notifies the MyadvancedMetadataProvider instance.

The metadata dependencies specified in the activate method should be unregistered in the deactivate method of the metadata provider. The metadata dependencies are unregistered using the deregisterDependency method of the MetadataDependencyRegistry instance, as shown here for MyadvancedMetadataProvider:

protected void deactivate(ComponentContext context) {
  metadataDependencyRegistry.
    deregisterDependency(PhysicalTypeIdentifier.
    getMetadataIdentiferType(), getProvidesType());
  
   ...
}

Metadata dependency registration ensures that downstream dependencies of a metadata are notified when changes occur in the upstream dependencies. To specify what triggers creation of metadata, metadata provider makes use of the addMetadataTrigger method of the AbstractItdMetadataProvider class, as shown here for MyadvancedMetadataProvider:

protected void activate(ComponentContext context) {
  metadataDependencyRegistry.
    registerDependency(PhysicalTypeIdentifier.
    getMetadataIdentiferType(), getProvidesType());

  addMetadataTrigger(
    new JavaType(RooMyadvanced.class.getName()));
 }

In the preceding code, the addMetadataTrigger method accepts RooMyadvanced Java type. It means that whenever a Java type is annotated with @RooMyadvanced annotation, MyadvancedMetadataProvider will create an instance of MyadvancedMetadata.

The metadata trigger is removed by the metadata provider in the deactivate method, as shown here for the MyadvancedMetadataProvider class:

protected void deactivate(ComponentContext context) {
  ...
  removeMetadataTrigger(
    new JavaType(RooMyadvanced.class.getName())); 
 }

Let's now look at how Spring Roo works behind the scenes to generate code when a Java type is annotated with the @RooMyadvanced annotation.

The following sequence diagram shows how the myadvanced add-on processes the myadvanced add --type sample.roo.flightapp.domain.Flight command, where the Flight class represents a JPA entity in your Roo project to which you want to add the @RooMyadvanced annotation.

The figure shows that when the myadvanced add command is executed, the add method of MyadvancedCommands instance is invoked and the type argument value is passed to the add method. You may notice that the add method accepts an argument of JavaType type, but we didn't register a custom converter with the Roo shell for it. This is because Roo is responsible for converting the type argument value to JavaType type. The JavaType contains the simple and package name information about the type argument value. In our case, JavaType argument passed to the add method contains simple and package name information about the Flight class that we specified as value of the type argument. The add method of MyadvancedCommands invokes the annotateType method of the MyadvancedOperationsImpl class and passes the JavaType instance containing information about the Flight class. The annotateType method annotates the Flight.java file with the @RooMyadvanced annotation.

Annotating Flight.java with the @RooMyadvanced annotation results in issuing a notification to the file monitor service of Roo that the Flight.java file has been modified. The following sequence diagram shows how file monitor service of Roo notifies change in Flight.java file to MetadataDependencyRegistry:

The preceding figure shows that the file monitor service notifies PhysicalTypeMetadaProvider that the Flight.java file has been modified. As discussed earlier, PhysicalTypeMetadaProvider provides metadata for a Java type in the Roo project. PhysicalTypeMetadaProvider is notified when Flight.java is modified because PhysicalTypeMetadaProvider is a registered listener for file change events. After receiving the file change notification, PhysicalTypeMetadaProvider asks MetadataDependencyRegistry instance to inform any registered downstream dependencies. We saw earlier that MyadvancedMetadataProvider's activate method registers MID:com.roo.addon.myadvanced.MyadvancedMetadata as the downstream dependency of MID:org.springframework.roo.classpath.PhysicalTypeIdentifier. The MID:org.springframework.roo.classpath.PhysicalTypeIdentifier represents a class-level metadata identification string created by PhysicalTypeMetadataProvider and represents a Java type in the Roo project. So, the change in Flight.java results in notifying the metadata provider that creates the MID:com.roo.addon.myadvanced.MyadvancedMetadata metadata identification string, which is MyadvancedMetadataProvider.

The following sequence diagram shows how MetadataDependencyRegistry notifies MyadvancedMetadataProvider to create MyadvancedMetadata:

In the preceding figure, MetadataProvider represents an interface that is implemented by all the metadata providers in Roo, and MetadataItem represents the metadata that is created by MetadataProvider implementations. In the case of the myadvanced add-on, MyadvancedMetadataProvider implements the MetadataProvider interface and MyadvancedMetadata implements the MetadataItem interface.

The previous sequence diagram shows that MetadataDependencyRegistry notifies MetadataService to inform the MetadataProvider (which is MyadvancedMetadataProvider in the case of the myadvanced add-on) of the downstream dependency.

A MetadataItem (which is MyadvancedMetadata in the case of the myadvanced add-on) is created when MetadataProvider (which is MyadvancedMetadataProvider in the case of the myadvanced add-on) of the downstream dependency is notified, as we'll see shortly. MetadataService makes use of the MetadataIdentificationUtils utility class to obtain the MetadataProvider class corresponding to the metadata identification string of the downstream dependency. Once the MetadataProvider for the downstream dependency is obtained, MetadataService notifies the MetadataProvider.

The MetadataProvider needs to know the Java type for which the MetadataItem is to be created. For instance, in the case of the myadvanced add-on example, MyadvancedMetadataProvider needs to know that MyadvancedMetadata needs to be created corresponding to the Flight.java class. MetadataProvider converts class-level MID (MID:com.roo.addon.myadvanced.MyadvancedMetadata) of downstream dependency into instance-level MID (MID:com.roo.addon.myadvanced.MyadvancedMetadata #SRC_MAIN_JAVA?sample.roo.flightapp.domain.Flight) to identify the Java type for which the MetadataItem is to be created. When the MetadataItem instance is created, it results in code generation.

Now let's look at some of the methods of MyadvancedMetadataProvider, which play an important role in creating the MyadvancedMetadata instance:

import ...roo.classpath.itd.ItdTypeDetailsProvidingMetadataItem;
...
public final class MyadvancedMetadataProvider 
   extends AbstractItdMetadataProvider {
 ...
 protected ItdTypeDetailsProvidingMetadataItem 
  getMetadata(String metadataIdentificationString, 
    JavaType aspectName, 
    PhysicalTypeMetadata governorPhysicalTypeMetadata, 
    String itdFilename) {
  
  return new MyadvancedMetadata(metadataIdentificationString,
     aspectName, governorPhysicalTypeMetadata);
 }
 
 public String getItdUniquenessFilenameSuffix() {
  return "Myadvanced";
 }

 protected String getGovernorPhysicalTypeIdentifier(
   String metadataIdentificationString) {
  
  JavaType javaType = MyadvancedMetadata.
    getJavaType(metadataIdentificationString);
  
  Path path = MyadvancedMetadata.
    getPath(metadataIdentificationString);
  
  return PhysicalTypeIdentifier.createIdentifier(javaType,
    path);
 }
 
 protected String createLocalIdentifier(JavaType javaType, 
  Path path) {

  return MyadvancedMetadata.createIdentifier(javaType, path);
 }

 public String getProvidesType() {
  return MyadvancedMetadata.getMetadataIdentiferType();
 }
}

The MyadvancedMetadataProvider class extends the AbstractItdMetadataProvider abstract class and makes use of the template method design pattern. The methods shown in the preceding code are invoked by the concrete methods defined in the AbstractItdMetadataProvider class. The following table describes the purpose of each of these methods:

The getMetadata method is responsible for creating the MyadvancedMetadata by passing information that MyadvancedMetadata is dependent upon. The following table describes the arguments passed to the getMetadata method:

Now, let's look at the MyadvancedMetadata class that is responsible for creating the AspectJ ITD file and adding methods and fields to it.

The following code shows the MyadvancedMetadata class:

public class MyadvancedMetadata 
  extends AbstractItdTypeDetailsProvidingMetadataItem {

 private static final String PROVIDES_TYPE_STRING = 
   MyadvancedMetadata.class.getName();

 private static final String PROVIDES_TYPE = 
   MetadataIdentificationUtils.create(PROVIDES_TYPE_STRING);

 public MyadvancedMetadata(String identifier, 
  JavaType aspectName, 
  PhysicalTypeMetadata governorPhysicalTypeMetadata) {  
  
  super(identifier, aspectName, governorPhysicalTypeMetadata);
  builder.addField(getSampleField());
  builder.addMethod(getSampleMethod());
  itdTypeDetails = builder.build();
 }
 
 private FieldMetadata getSampleField() {
   ...
 }
 
 private MethodMetadata getSampleMethod() {
  ...
 }

 ...  
 public static final String getMetadataIdentiferType() {
  return PROVIDES_TYPE;
 }
 ...
}

The preceding code shows that MyadvancedMetadata defines two constants and a couple of methods. The PROVIDES_TYPE_STRING constant refers to the fully-qualified name of the MyadvancedMetadata class and PROVIDES_TYPE refers to the metadata type provided by the MyadvancedMetadata class. The value of PROVIDES_TYPE is MID:com.roo.addon.myadvanced.MyadvancedMetadata.

MyadvancedMetadata extends the AbstractItdTypeDetailsProvidingMetadataItem abstract class, which provides the common functionality for add-ons that want to create an AspectJ ITD file corresponding to a Java type. The constructor of MyadvancedMetatada makes use of information passed by the MyadvancedMetadataProvider to create the AspectJ ITD file. To simplify creation of AspectJ ITD file, Roo's ItdTypeDetailsBuilder instance (represented by the builder variable in the constructor) is used. The addField and addMethod methods of ItdTypeDetailsBuilder are used to add information about fields and methods that form part of the AspectJ ITD. The getSampleField and getSampleMethod methods in the above code return FieldMetadata and MethodMetadata, which represent the field and method to be added to the AspectJ ITD.

The following code shows the getSampleField method of MyadvancedMetadata class:

private FieldMetadata getSampleField() {
  int modifier = 0;
  
  FieldMetadataBuilder fieldBuilder = 
   new FieldMetadataBuilder(getId(), 
    modifier, 
    new ArrayList<AnnotationMetadataBuilder>(), 
    new JavaSymbolName("sampleField"), 
    JavaType.STRING_OBJECT); 
  
  return fieldBuilder.build(); 
 }

Roo's FieldMetadataBuilder is used to create a FieldMetadata instance. The following are the details of the arguments passed to the FieldMetadataBuilder constructor:

Similarly, the getSampleMethod method of MyadvancedMetadata makes use of Roo's MethodMetadataBuilder to create an instance of MethodMetadata.

Now that you know how the myadvanced add-on works, you can use it in your Roo project the same way we used the mysimple add-on.