How does the template gain access to the metadata object?

'populateContextMap' method (see the above code snippet) registers the metadata and the plugin instance with velocity/jelly context against the keys "class" and "plugin" respectively. Infact, the metadata is also available under the key "metadata".

The velocity / jelly templates typially access the metadata object(s) via the $metadata variable and the associated plugin object via the $plugin variable. If there is a need to access some other object in the template, the populateContextMap () method in the abstract Plugin class can be overridden to do the same. But one needs to make sure that the base class method is called so that one does'nt lose out on the default behaviour.

Class ConcretePlugin extends Plugin{
  //..
  //..

  protected void populateContextMap (Map context){
    super.populateContextMap (context);
    populateContextMap ("utils", new Utility ());
  }

}

The template can now access the Utility class directly through $utils variable.

How does this help?

The fact that you need access to metadata/context is pretty obvious - You cannot generate code without a context to work on.

The biggest gain is that providing utility methods to the template is as simple as adding the same to the plugin class.

For eg:

Org.xdoclet.plugin.ejb.interfaces.LocalInterfacePlugin plugin is used for generating local interfaces for the entity beans.

It allows access to EJbUtil helper class by providing an accessor on the plugin class.

class LocalInterfacePlugin extends ..{
  //..
  //..
  public EjbUtils getEjbUtils() {
    return ejbUtils;
  }
}

The velocity template in turn uses it as follows:

File: LocalInterfacePlugin.vm
-----------------------------

//$metadata variable being used by the template. $metadata represents
//a com.thoughtworks.qdox.model.JavaClass instance
#set( $class = $metadata )
#foreach ($method in $plugin.ejbUtils.getInterfaceMethods ($class, "local"))
    $method.getDeclarationSignature(false);
#end

-----------------------------

Note that we discussed another way of achieving the same in the previous section.

Ok, what does the Plugin do if the code generation activity needs to result in one consolidated file (eg: ejb-jar.xml)?

We looked at the 'if' block of the start () method of the abstract Plugin class earlier. The 'else' block has the answer to the question.

public void start() {

  //removed code for clarity		
		

  if (isMultioutput()) {	    
    //We just discussed the code in the following 'if' block
  } else {
    Outcome out = getWriterMapper().getOutcome("", this);
    if (out.getWriter() != null) {
      Map m = new HashMap(contextObjects);
      Collection filtered = CollectionUtils.select(metadata, new Predicate() {
	public boolean evaluate(Object o) {
	    return shouldGenerate(o);
	}
    });
    
    // in case of say velocity template $metadata would be a collection of 
    // JavaClass in this case

    m.put("metadata", filtered);
    populateContextMap(m);
    templateEngine.generate(out.getWriter(), m, getEncoding(), getClass());

    if (validate && outputValidator != null) {
	outputValidator.validate(out.getURL());
    }
    out.getWriter().close();
  }
  
}

This piece of code that uses Commons Collection's CollectionUtils class caught my attention (may be because I have never used Commons Collections before).

Collection filtered = CollectionUtils.select (metadata, new Predicate () {
    public boolean evaluate (Object o) {
      return shouldGenerate(o);
    }
  });

I had looked at Groovy (codehaus seems to be a gold mine of frameworks (or languages in this case)!) sometime back and this seems to be the Java equivalent of Groovy closures at work. The predicate is evaluated for every item in the collection (metadata). If the predicate returns a value 'true' for that item, the resulting filtered collection would have that item else it is rejected. Note that, as in the earlier case, the custom plugin gets to decide if the source corresponding to the metadata object needs to be processed. In Python, the filter () construct would have done the job for me.

The EjbJarXmlPlugin.jelly uses it as follows

Note that this is not the complete template file. Certain parts have been ommited to show how a jelly template file typically looks like.

<j:jelly xmlns:j="jelly:core">
  <ejb-jar>
    <enterprise-beans>

    <!—Note that $metadata is a collection unlike in the earlier case. 
           Its being read into the class variable in a loop - ->

    <j:forEach var="class" items="${metadata}">
      <j:if test="${plugin.shouldGenerate(class)}">
        <entity>
          <ejb-name>${plugin.ejbUtils.getEjbName(class)}</ejb-name>                        
          <ejb-class>${class.fullyQualifiedName}</ejb-class>
        </entity>
      </j:if>
    </j:forEach>
    </enterprise-beans>
  </ejb-jar>
</j:jelly>

There were certain things that did'nt necessarily make sense to me. Generama MetaDataProvider interface does'nt look generic enough. It has methods like

String getOriginalFileName(Object metadata);
ConfigurableDocletTagFactory getDocletTagFactory ();

The issue here is that ConfigurableDocletTagFactory extends DocletTagFactory - a QDox interface. Similary org.generama.Plugin class that all plugins extend has an abstract method

public abstract Collection getMetaData();

I think the responsiblity for providing access to the metadata has been wrongly placed on the Plugin Class?. This seems a little contradictory to the claim that Generama does'nt care where the metadata comes from. It probably makes more sense on the MetaDataProvider interface?. Hopefully a little bit of refactoring/'moving around of methods' should fix these issues.

In its current state however, there are no issues since we are more likely to use xdoclet to generate code from java sources and QDox is apparently very efficient and fast when compared to xjavadoc - tool used by XDoclet1.x to gather metadata.

How to validate the generated output?

This is a new addition to Generama in the latest release - ability to conditionally validate the generated output. The plugin can register a org.generama.OutputValidator with the abstract plugin class and get it to validate the generated output. Generama ships an xml validator by default - org.generama.defaults.XMLOutputValidator. It can be used to validate generated XML files against a schema/dtd. For eg , while generating struts-config.xml from other struts related artifacts. Most of the plugins that generate XML files might have XMLOutputValidator registered by default. Note that validation is also switched on by default. If you don't want to validate the generated XML files, it can be done by setting attribute 'outputValidator' to false when invoking the plugin.

<component class="org.xdoclet.plugin.hibernate.HibernateMappingPlugin" outputValidator="false"/>