Raible Designs

XDoclet vs. JSR 175

Rob Kischuk has a post where he describes what a Struts Action might look like using JSR 175 annotations.

@StrutsAction(
  @ActionMappings({
    @ActionMapping(
      path="index"
      @ActionForwards({
        @ActionForward(
          name="success"
          path="index.jsp"
        )
        @ActionForward(
          name="failure"
          path="error.jsp"
        )
      })
    )
  })
)
public class IndexAction extends Action {

As I read it, I though - "holy crap is that ugly!" Isn't the XDoclet version a bit cleaner?

 * @struts.action path="index"
 * @struts.action-forward name="success" path="index.jsp"
 * @struts.action-forward name="failure" path="error.jsp"

I'll admit, I don't know much about JSR 175, except that it is designed to replace XDoclet. However, I don't believe that it will generate code like XDoclet does - but rather it will allow your Java code to describe metadata using doclet tags. So what good does that do? Does this mean all my metadata and configuration stuff is hard-coded into my source? With XDoclet, I realize that a lot of this stuff is hard-coded into my source, but at least I can change things by changing an ant property and rebuilding - or changing the generated XML files. Why is JSR 175 better than XDoclet? I guess I just don't see the beauty of it. More typing and uglier javadocs aren't that appealing to me.

Posted in Java at May 19 2004, 11:12:29 AM MDT 7 Comments

Comments:

I'm not completely sold on this, but thought it was worth fleshing out the idea as a thought exercise. The metadata could be simplified to this with some interface tweaks:

@StrutsAction(
   @ActionMapping(path="index"
      @ActionForwards({
        @ActionForward(name="success" path="index.jsp")
        @ActionForward(name="failure" path="error.jsp")
      })
   )
)

At least one advantage is that Annotations have a lower barrier to entry than XDoclet. I think many developers find it intimidating that they have to download XDoclet, get it configured in their build script, make sure the generated code is being merged correctly, etc. (Granted, you only have to do this once.) With annotations, frameworks can be built with support for metadata right out of the box.

Posted by Rob Kischuk on May 19, 2004 at 06:15 PM MDT #

There's another side of the view: team work. In a team, only one person has to setup the XDoclet stuff and the other guys as well as the maintainers later have a short and concise syntax. Here, there is not the "setup fee", but everybody has the burden of this... java-ish syntax, and we know that making everything look like Java is not the smartest move to do. We've just to hope that it won't become the next Glorious Mess (hint, JSP).

Posted by Damien Bonvillain on May 19, 2004 at 09:56 PM MDT #

If you find XDoclet intimidating as a developer, perhaps you need to find another job?

Posted by Unknown on May 20, 2004 at 12:48 AM MDT #

Mr. Anonymous (if that's your real name) -- any given technology will have a learning curve. "Power" does not necessarily translate to a steep learning curve. If anything, the best technologies are the ones that are powerful yet easy to understand and use, are flexible, and is quickly available to the widest population of potential users. Something else to note is not all software writers are professional programmers. VB was famous for non-programmers being able to write code to aid in their "normal" work. Java is a little more difficult than VB (and worth it, if you ask me), but it's bonus is that it's free. A lot of people write in Java for fun or for "normal" work. Don't count them out. Rob -- I'm with Matt in that I still don't understand why I (an application developer) would ever want to use JSR 175. Do you have a simple explanation for the uninitiated? Like Matt, I think code-generation is the way to go. What would make me want to use JSR 175? I should read up more on it, but it just seems like extra JavaDoc comments that are just don't add any value to the application being written. The XDoclet version you now suggest does look better than the original, but the XDoclet one is still much more readable and straightforward. I can tell exactly what it wants to do in an instant, but the metadata version isn't obvious. I found a link to Ted Neward's blog (he's on the JSR committee) that was interesting: http://www.neward.net/ted/weblog/index.jsp?date=20031109, and he also found Matt's blog entry and responds: http://www.neward.net/ted/weblog/index.jsp?date=20040519#1085030657817 ( I commented there as well -- maybe we need trackbacks for comments, too???)

Posted by gerryg on May 20, 2004 at 09:45 PM MDT #

I would imagine that the average developer will very rarely define an annotation themselves, but find it very likely that the average developer may begin to see them in conjunction with frameworks. Consider my Hibernate example.

The JSR 175 syntax is different than the XDoclet version, some would say a bit uglier, but not that it also allows you to express more complex constructs than XDoclet.

So with XDoclet, you use a non-standard syntax to add metadata to your object, generate the mapping from the metadata, package the metadata with your application, and add the class to your Hibernate configuration.

In a theoretical JSR 175 version of Hibernate, you annotate the class you want to persist. No generation or packaging needed. Your metadata follows a standard. The format of your mapping is validated at compile time rather than runtime. You don't need to register your class with Hibernate - the framework can discover persistable classes by reflection.

It is a potential application of JSR 175. I don't know whether it is a good application of it, but it came to mind, so I wanted to explore it more deeply. In many cases, people are using XDoclet because the metadata is best maintained and understood when it is tied closely to the source code. In this case, why not standardize the format of the metadata? In other cases, code generation is the desired end result - it certainly has its place.

Posted by Rob Kischuk on May 21, 2004 at 05:56 PM MDT #

I don't think anyone is saying JSR175 will replace XDoclet. This is a common misconception. You're only looking at it from a pure syntax point of view. XDoclet is code generation from javadocs. JSR175 is a metadata facility. They are two different beasts. JSR175 allows for the metadata to be included into the class's bytecode. It becomes a first class citizen. You can look at a class, and look at its metadata (or a method's or a field's). This you can do at runtime, and all you need is the class. What you do with the metadata is then up to you. One thing you could do is generate code. Another thing you could do is have your class advertise itself to a container and request features from it. XDoclet solves a different problem. Of course, in the future, XDoclet might use JSR175 instead of javadocs. XDoclet is built to generate code from markup. In fact, I wouldn't be surprised if xdoclet supported both methods. JSR175 is a great addition, something Java will really take advantage of. DOn't think of it as a replacement for xdoclet. It's a metadata facility that will allow classes to expose more information. What you do with the metadata is up to the application. As far as Struts... they may use JSR175 for some of their configuration (to minimize XML hell). Some things aren't suited for metadata, such as forward definitions. You don't want to specify the forward definition right on the class because that too tightly coupled. But you might want to specify the URL that maps to the Action. And anything that minimizes XML is good in my eyes. :)

Posted by Seth Ladd on May 21, 2004 at 07:02 PM MDT #

khk

Posted by 161.185.1.100 on September 30, 2005 at 08:28 PM MDT #

10+ YEARS

TWITTER

RECENT ENTRIES

Tag Cloud

XDoclet vs. JSR 175