Aslak emailed information on XDoclet2, and at its core is Generama, a picocontainer that is the framework at the core of XDoclet2. XDoclet2 itself is just a few plugins that use Generama. XDoclet2 allows you to use wither Jelly, or Velocity as the templating languages. This should enable many more templates, as people don’t have to learn the proprietary XDoclet templating API!
[follow the link below to read Aslaks email]
Aslak emailed information on XDoclet2, and at its core is Generama, a picocontainer that is the framework at the core of XDoclet2. XDoclet2 itself is just a few plugins that use Generama. XDoclet2 allows you to use wither Jelly, or Velocity as the templating languages. This should enable many more templates, as people don’t have to learn the proprietary XDoclet templating API!
Here is the body of Aslaks email:
Hi folks,
(Sorry for cross spamming, but I believe Generama/XDoclet2 might be of
interest to all lists. Please try to reply only to
[email protected], as the XDoclet project is the current home
for these projects).
The final XDoclet2 (hereafter XDoclet) framework based on a new library
called Generama, Velocity, Jelly and PicoContainer is about to be
released in beta. This is the next generation of XDoclet.
During some recent refactorings of XDoclet, the Generama framework was
factored out into a separate generic framework. A brief explanation of
the Generama framework is necessary before continuing the explanation of
XDoclet.
G E N E R A M A F R A M E W O K
Generama is a small IoC (Inversion of Control) architected plugin
framework for Velocity and Jelly (currently a 27 k jar). It is possible
to register one or more plugins (based on either Velocity or Jelly) that
will generate a particular kind of output, using an associated
velocity/jelly script with access to arbitrary metadata (placed in
velocty/jelly context variables). The templates will expect metadata to
be of a certain type, and therefore a given plugin will only work with
metadata of the expected type. This is done by registering an
appropriate MetadataProvider within Generama.
Generama is based on PicoContainer (http://www.picocontainer.org/). In
fact, Generama _is_ a PicoContainer, with all the core components that
are composed to deliver Generama’s functionality, registered by default. The Generama PicoContainer is only nearly ready to roll on its own
though, and that is intentional by design. The remaining part is left to
implement for clients of the Generama framework: That is to register
three types of components:
- A org.generama.MetadataProvider that provides metadata to the
velocity/jelly scripts
- A org.generama.WriterMapper that will decide where output should be
written (usually to file).
- At least one org.generama.Plugin that will generate output.
This is done by the following steps:
- Make a new instance of a concrete Generama subclass.
- Register one or more plugins with it.
- Call the Generama object’s execute() method.
This will cause all the plugins to be executed. When they execute, they
will invoke their internal template engine (Velocity or Jelly) to
generate output.
Now you should have tons of generated files of whatever kind;-)
Generama also comes with an Ant task. It’s a generic task that lets you
add plugins via
e.g. Eclipse or IDEA) should be very easy too. Volunteers for this are
most welcome.
Generama currently lives in XDoclet’s generama CVS module. (Generama will be used in Middlegen, and could be a perfect base
framework for a future version of AndroMDA too).
G E N E R A M A P L U G I N S
A Generama plugin typically consists of two files: First, a class that
implements Plugin (or extends VelocityPlugin or JellyPlugin). Second, an
associated velocity or jelly script. These scripts have access to the
metadata object(s) via the ${metadata}variable and the associated plugin
object via the ${plugin}variable. This makes it extremely easy to
provide special logic to the scripts by implementing helper methods in
the plugin classes themselves. Just implement a String getFoo() or
String getBar(Zap) method in the plugin, and its template will be able
to do magic things like ${plugin.foo} and ${plugin.getBar($zap)}. (For
XDoclet 1.2 savvies, these helper methods replace the TagHandlers).
Plugin developers only have to focus on two files: the template and the
plugin class. Just remember to keep the template in the same package and
the same name as the plugin class, and give it a .vm or .jelly
extension. Further, testing helper methods in Plugins with JUnit should
be very easy too.
It is not entirely true that a plugin only consists of a plugin class
and a script. The plugin developer hould also write tests for the
plugin. Doing this TDD (Test Driven Development) is strongly recommended
to drive the development process of a Generama plugin. Generama provides
an abtract test framework based on JUnit to make this easy. These
classes tests that a plugin generates what it is expected to generate.
The test framework uses XMLUnit and CodeUnit to compare generated XML
files resp. generated Java files against a static one. (CodeUnit is
JUnit extension part of XJavaDoc. It compares Java files on the syntax
level in a similar way to XMLUnit).
In short, a plugin test consists of a test class, a file with expected
output, and some sample input (for XDoclet plugins – see below – this
will typically be one or more java sources with @tags).
When writing a Generama plugin, start by extending the appropriate test
class. They are abstract and you’ll be surprised how easy it is to get
started. It should be very obvious just by implementing the required
abstract methods. Just remember to write the tests first. In Generama’s
test framework, the basic tests are already written, so all you have to
do is to implement two methods: One saying how to get the metadata (test
input), and another one saying how to get the expected output. So when
you work on a plugin, you typically work in small iterations (each
ending with a green JUnit bar) where you:
1) Add more content to the expected output.
2) Add more logic to the plugin class and/or script.
3) Add more data to the sample input data.
There are already examples on Generama plugins and how to test them in
the xdoclet-plugins project (see below).
X D O C L E T F R A M E W O R K
XDoclet is only a small and simple extension of Generama with some
additional preregistered components (currently a 16 k jar). The XDoclet
class extends Generama and registers (among other things) a
QDoxMetadataProvider, that will return instances of
com.thoughtworks.qdox.model.JavaClass. (QDox is being used instead of
XJavaDoc, primarily because of its superiour speed and more intuitive
API). The XDoclet class is also abstract. The only thing needed to make
it concrete is to make a subclass that implements the
getFileProviderClass(). The XDocletTask for Ant uses one that returns a
FileProvider that hooks into Ant filesets. XDoclet IDE plugins might
want to provide an implementation that makes it possible to configure
the returned files via the IDE.
To those who tried to dive into XDoclet2 before and said “what the …
Where am I supposed to start?” should have a more pleasant experience
this time. There are heaps of tests in the Generama, XDoclet and XDoclet
Plugins projects to illustrate what the code does.
X D O C L E T P L U G I N S
XDoclet’s plugins are nothing else then plain Generama plugins. The only
special thing about them is that their velocity/jelly templates should
expect the ${metadata} to be QDox’s JavaClass. (Because XDoclet
automatically registers a QDoxMetadataProvider!).
When you look in the xdoclet2 CVS module, yo’ll notice that there are no
plugins at all(!). They now live at the xdoclet-plugins SF project.
There are already a couple of plugins up there, mainly to get the
development community going. If you want to be an XDoclet plugin
developer, check out xdoclet-plugins and play a little with the code in
there. Start writing your own plugin and experience how easy it is! When
you have something working and really want to continue maintaining
whatever plugin you have started on, submit some patches. After a while
you’ll earn your rights to commit to the CVS.
There is one important reason for keeping the xdoclet-plugins project
apart from the XDoclet and Generama projects. XDoclet / Generama might
move to Jakarta. Due to Jakarta’s strict meritrocacy rules, only a small
number of developers will be granted commit rights in Jakarta. In order
to attract a large developer community for XDoclet plugins, it is
necessary to be able to grant commit rights more easily than at Jakarta.
W H A T N O W
- Generama and XDoclet will be released as alpha in the following week.
- Developers who have committed code to XDoclet 1.2 the past three
months will automatically get commit rights in the xdoclet-plugins
project on SF.
- Anyone who’s interested in porting old XDoclet modules to the new
plugin framework should install Maven 1.0-beta-10 or later. Committers
will commit code to xdoclet-plugins. Other people will upload patches to
xdoclet-plugins’ JIRA.
- Jakarta status will be applied for.
- Those who want to contribute, but don’t know exactly with what, tell
the mailing list, and they will be assigned tasks in JIRA.
There are lots of things that aren’t covered in this short mail. Like
doclet tag validation or how to migrate XDoclet modules to new plugins.
Or how to build or run. Just fire the questions, and they will be answered.
The code lives in xdoclet2 and generama CVS modules in the xdoclet SF
project, and the xdoclet-plugins CVS module in the xdoclet-plugins SF
project.
Now the discussion!
