Working with Generated Code Annotations

Mint provides an API to determine if a particular Java type member is generated by an EMF-based code generator based on its Javadoc annotation. This functionality has a variety of uses; for instance, it allows Mint to decorate Java elements in various JDT views based on their code generation status.

EMF-based code generators annotate types, fields and methods with a @generated tag in their corresponding Javadoc. This tag indicates to the generator that it is ok to replace this declaration next time it runs. However, customization of such code is sometimes required -- the generator needs to be told to leave such customized elements unmodified. This can be accomplished by adding an arbitrary parameter to the tag, such as @generated NOT. This convention communicates the fact that the annotated declaration, which is ordinarily generated, has been customized and it is the developer's responsibility to maintain it.

Determining the Codegen Status of an IMember

The codegen status functionality is exposed through IMemberAnnotationManager. This interface provides methods for obtaining the current status of an IMember, as well as listening to its changes. An element's codegen status is represented by the CodeGenStatus enumeration and can be one of NONE, GENERATED, or GENERATED_NOT. An instance of IMemberAnnotationListener can be obtained by calling MintCore.getInstance().getMemberAnnotationManager().

The following code snippet shows how to determine if a method is generated:

   IMethod method = ...
   IMemberAnnotationManager mgr = MintCore.getInstance().getMemberAnnotationManager();
   CodeGenStatus status = mgr.getCodeGenStatus(method);
   if (status == CodeGenStatus.GENERATED) {
       ...
   }
   

Tracking Changes

In some use-cases, the client code needs to know not only the current status of an element, but also whenever a change occurs. This can be accomplished by registering an IMemberAnnotationListener with the IMemberAnnotationManager. The listener is then notified whenever an element's codegen status changes.

The following snippet illustrates this:

   IMemberAnnotationManager mgr = MintCore.getInstance().getMemberAnnotationManager();
   mgr.addMemberAnnotationListener(new IMemberAnnotationListener() {
       public void memberAnnotationChanged(MemberAnnotationChangedEvent e) {
           for (Map.Entry<IMember, CodeGenStatus> entry : e.getChanges().entrySet()) {
               IMember member = entry.getKey();
               CodeGenStatus status = entry.getValue();
               ...
           }
       }
   });
   
Note: As an optimization, only changes to elements whose status has been previously obtained by calling getCodeGenStatus(IMember) are reported to registered listeners.

Copyright (c) 2010 Ecliptical Software Inc. and others. All rights reserved.