Dion likes named
parameters:

I have always liked named parameters, as I have seen many bugs due to methods
such as: doFoo(String acct1, String acct2). Here we have no way to know if
someone is passing in the right info (other than via Unit tests).

Named parameters are indeed attractive, but they come at a price.

First of all, method parameters become part of the signature of your method,
which means you can’t modify them without breaking your users.  It might
sound like a minor annoyance but my experience tells me that the least you
expose in a public API, thee asier your life will be.

But the best lesson about named parameters comes from C++, again.

Named parameters almost made it into C++.  The proposal had been
reviewed several times by the Committee and there was a universal agreement on
their good qualities:  easy to explain, easy to implement, not representing
any major backward compatibilities issue, etc…

Bjarne was just a little bit concerned about the extra verbosity in the
source, which was going to make it harder to search source files, but he agreed
that his objection was not strong enough to decline this new feature (we can
also notice once again how pragmatic he is.  It’s also interesting to point
out that this kind of concern is moot now that IDE’s provide us with semantic
searches).

And then, a few days before the proposal was formally accepted, one of the
group experts sent an email to everyone saying "We don’t need named parameters,
we already have them".  And then he proceeded to demonstrate his point by
turning the working example (in Java syntax for readability):

Window w = new Window(x:0, y:0, color:blue)

into

Window w = new Window().x(0).y(0).color(blue);

Patrick just posted some documentation on
JAM, the type abstraction API used in EJBGen and SGen.

The idea behind JAM is to offer a uniform access to the way the Java type
system (and more particularly, annotations) are collected.  Right now, JDK
1.4 is supported, 1.5 will be available very soon (source or .class form) and in
the future, you can expect more metadata providers to become available.

JAM is shipped as part of the Open Source
Apache XMLBeans project but we are
considering making it a standalone product (which for now is available directly
from Patrick’s Web site).

There is a lot of design work currently happening around JAM so now is the
time to provide feedback!

I have to say I am surprised by some of the comments I have received about
Canvas, and in particular from people who say that the Velocity Template
Language (VTL) is a better choice than Groovy because it’s not a "real"
language, so you are not tempted to mix presentation and business logic.

First of all, the assumption that the generated template is for
"presentation" (probably meaning:  a Web page) is a generalization. 
Velocity is used for much more than just generating Web pages, so this argument
is weak in my opinion.

But if you think the VTL is just a declarative language, you are fooling
yourself.  VTL has

• Control structures (if, while, etc…).
• Variables.
• Macros.
• And worst (or best) of all, it has access to the underlying Java
  objects.

In other words, I am pretty sure that you can use VTL to write arbitrarily
complex pieces of code inside your template, and
Sam was quick to point out a

perfect example of that.

With that in mind, if we are going to have to deal with a language inside the
template, I would rather use one that I like, is powerful and ideally, close to
the Java syntax.

There is also another reason why VTL is less than optimal for this, and it
has to do with the philosophy behind Velocity templates.

Velocity templates make no distinction between "verbatim text" and VTL. 
The only way to identify the pieces of VTL code in your template is by spotting
the various syntactic annotations (#, $, etc…).  The problem with this
approach is that it makes it pretty much impossible to guarantee the indentation
of the generated files, since you can never tell when a space is significant
(part or your "verbatim text") or should be ignored (used to indent a VTL
expression).

The JSP syntax (or any delimiter-based syntax) makes it obvious what spaces
should be preserved and which ones can be ignored for the generation of the
final file:

// Canvas template
public class GeneratedClass {
  <%
    for (i in methods) { i.generate() }
  %>
}

From my experience, it is absolutely impossible to get a decent indentation
for this very simple example with Velocity…

Now that I have your attention 🙂

Velocity is a fine product that delivers its promise, but it has a few
shortcomings:

• Velocity is pretty much a dead project.  There has hardly been any
  activity in over a year and nobody seems to be interested in taking over. 
  The good news is that from my experience, Velocity is relatively bug free,
  but it doesn’t bode well for its ability to evolve with the increasing
  demand of modern Java computing.
   
• It comes with some annoying dependencies, such as log4j or commons. 
  I am not criticizing the quality of these two packages but Velocity has a
  rude way of instantiating its loggers that recently gave me quite a
  headache.  On a related note, if you intend to publish a framework,
  please think twice before adding dependencies on packages that your users
  might be using in their own code base.  To add insult to injury, log4j
  happens to have a perfectly decent equivalent in the JDK itself. 
  Granted, java.util.logger isn’t as powerful as log4j, but in this particular
  case, I see no reason why Velocity is trying to impose its own logger on
  pour souls like me who only need a simple generator framework.
   
• Finally, Velocity offers very little control on the indentation and
  shape of generated files and I haven’t found any satisfying way to solve
  that problem.

With that in mind, I started thinking about a replacement.  The Velocity
API is simple and easy to understand, but I had no desire to implement yet
another expression language.  The solution quickly imposed itself to me: 
Groovy.

Not only is Groovy a cool language that borrows features from two of my
favorite languages, Java and Ruby, it’s also extremely easy to embed in a Java
application.

With that in mind, it took me just a few hours to put together this quick
prototype of a product reusing the Velocity API but using Groovy as its
expression language.  The good news is that the dependency is now limited
to one jar file:  groovy.jar.

I called this product Canvas and you can read more about it on its
home page.

Also, I’d like to take this opportunity to hereby claim the title of the
smallest framework ever:  Canvas only has three classes.  You can’t
get more lightweight than that!

SGen has caused

quite a stir, so I thought a few clarifications were in order.

JAM

There is quite a bit of interest about JAM, and rightfully so, so I’ll start
with this.

JAM is shipped with

XMLBeans, so it’s an Apache product.  I didn’t include it in SGen (although
I did include the JAM javadocs), but if you want the whole JAM distribution,
just download XMLBeans.  What you won’t find in that distribution is the JSR 175
code, though, which I just recently wrote.  I will ship this as part of SGen for
now, though, but eventually, it will make it in XMLBeans as well.

The only reason why the SGen distribution is a bit messy right now is that I
need to figure out a way to package it with two different jar files (1.4 and
1.5), and I just haven’t had the time to do that so far.  Please bear with me.

SGen

Over the past months, I have received increasing requests to make EJBGen
extensible.  Since EJBGen is not open source, the only way I could do this was
provide an extension API in the same spirit as Eclipse or COM.  As I started
factoring this code out of EJBGen, it occurred to me that the framework was
actually turning into something fairly generic.  EJBGen was already using JAM
back then and it became quite obvious that SGen could become not only a
generator framework, but that it would be annotation-neutral on top of that.

From this point on, the other ideas fell in place very naturally.  The
concept of separate jars for modules became central to the design of SGen. 
Ideally, I want people to download a minimal SGen runtime and then
shop around for various jar files (in source form or not) for the various
modules they need.  This way, they create their own generator "a la carte" and
one single invocation of the generic SGenRunner is all that’s needed in their build to generate all the
files they need. 

XDoclet

Here is my perception of the XDoclet landscape right now.  Please note that
as opposed to the other sections, what follows is admittedly very subjective and
I have no doubts that a lot of people will disagree with me.

There is an impressive number of XDoclet plug-ins used in production, and I
think it’s fair to say that 99% of them are based on XDoclet 1 (since XDoclet 2
is not even alpha, as far as I know).  Of course, anybody who has written a
module for XDoclet 1 is very interested in porting their code to XDoclet 2,
which offers a very compelling Velocity-based template model, as opposed to the
version 1 and its XML language.

XDoclet 2 has been brewing for quite a while, now, but hasn’t seen much activity
in the CVS depot or the mailing-lists.  This standstill has had a disastrous
effect on the landscape:  module authors are hesitant starting working on a
pre-alpha version while reluctant to add more code in their v1 plug-in
which is going to be obsoleted

Now that I have your attention 🙂

I am happy to announce the initial release of
SGen, a framework that makes it easy to create tools that parse annotations
and generate files.  Some of the goals for SGen are:

• Modules can be developed separately and shipped in individual jar files. 
  All they need to do is contain at least one SGen module (which is achieved
  by implementing a certain interface).  For example, you can download
  ejbgen.jar, drop it in your "modules" directory, point SGenRunner to it and
  voila, you have added a new generator to your arsenal.
   
• SGen is annotation-neutral.  It supports both Javadoc and JSR 175
  style annotations.  The way the annotations are collected is made
  transparent to your module through an open-source abstraction layer called
  JAM.
   
• SGen doesn’t mandate any template technology.  You are free to use
  Velocity or println if that’s what you want.
   
• SGen is XML-free.  That’s right, baby, you won’t have to write a
  single line of XML to use it.

Since the question is most likely going to come up, I don’t see SGen as a
direct competitor to XDoclet, although they achieve similar goals.  The
idea is that if you wrote an XDoclet module, you should be able to factor out
all the "business logic" of your generators and make an SGen module out of it. 
Then your module can be downloaded by your users and mixed with the other SGen
modules they use.

For more details, examples, architecture overview and JavaDoc, please take a
look at the SGen home page.

SGen is certainly in alpha stage at this point and as you can see at the
bottom of the documentation, more features are coming up, but since the current
version works fine for the very demanding EJBGen (which is now an SGen module),
I think it is in a good-enough shape for early adopters.

All questions about SGen should go to the
SGen mailing-list.

As I confessed earlier,
I am a big fan of properties, whether they are implemented in C# or Ruby. 
Not a day goes by without me missing them thoroughly in Java land, as I
tirelessly write an endless stream of "int m_foo; public int getFoo() { …};  
public void setFoo(int n) { …}" (actually, my IDE does that for me but it’s
still a waste of space and it gets in the way of readability).

How come I am not surprised that James found such a neat way to
solve this conundrum in Groovy?

James call them POGO’s (Plain Old Groovy Objects), and declaring them is as
simple as declaring your fields public.  The Groovy compiler takes care of
generating the boiler plate accessors without them getting in the way of your
published interface.  I think it’s important to be able to control the
access to your fields, but I also believe it’s very important for this access
code not to obfuscate your code more than necessary.

Once again, Groovy hits the perfect sweet spot between Ruby and C#.

Well done, James.