Java Development News:

XDoclet In Action

By Dion Almaer

01 Apr 2004 | TheServerSide.com

Introduction

There are some books that you really look forward to. The reason that I was looking forward to XDoclet in Action was because the topic really needed a good book. It needed a book that covered the myriad of areas that you want to know about when working with such a tool.

Depending on your background, you would want to learn about code generation in general, a process for using code generation, when it makes sense/when it doesn’t. This is even before you get to topics on XDoclet the tool itself. Here you not only want to learn how to use XDoclet, but how to tweak it, extend it, and the tools that surround XDoclet itself.

XDoclet is one of those tools that you may just use a little bit on a project; you may rely on for a huge amount of the project, or somewhere in between.

Although XDoclet started its life as EJBDoclet, it has grown like wild-fire. Code generation is far from a new topic in computer science, but the need of multiple deployment descriptors and interfaces in J2EE brought a realization that a tool like this could really help a developers life. As soon as you see cookie-cutter code/configuration/documentation then you think about how you can refactor your design. Depending on the problem at hand you either refactor the code to not need all of these items, or you end up generating the artifacts.

Craig Walls and Norman Richards took on the challenge of giving you a book that delves into all angles of XDoclet (as you will see by the contents below). I think they did a very good job at covering the bases, and there is plenty to learn whether you are a seasoned XDoclet users, or a newbie.

You probably won’t read this book back to back. In the middle area there are a lot of chapters which are “XDoclet and <insert technology>”. If you don’t really care about that technology, then you can happily skip on by. In this way, I think the book is a good reference to have on the book shelf. If you have a project which uses the new portlet API, you can lookup the appropriate chapter and will be able to quickly use XDoclet for the task (if you want to).

You will also find a fair amount of paper spent in the appendices. Here you will find items such as “XDoclet task/subtask quick reference” and “XDoclet tag quick reference”. This makes the book look pretty meaty. Don’t get scared, as you probably won’t go through every possible tag at night, unless you are suffering from insomnia that night! I understand the need to be complete, and these references give that, but I personally much prefer the chapters that talk about experience with using code generation, issues to watch out about, and more. This is where a book becomes more than just documentation.

The book doesn’t cover XDoclet 2, other than in “The future of XDoclet”. Development seems to be stalled on XDoclet 2 anyway, so I don’t think this is a big deal…. And I am sure a 2nd edition will come out quickly if the new version picks up speed again.

Let’s look at the structure of the book:

PART ONE: The Basics
  1   A gentle introduction to code generation
  2   Getting started with XDoclet

PART TWO: Using XDoclet with Enterprise Java
  3   XDoclet and Enterprise JavaBeans
  4   XDoclet and the web-layer
  5   XDoclet and web frameworks
  6   XDoclet and application servers

PART THREE: Other XDoclet applications
  7   XDoclet and data persistence
  8   XDoclet and web services
  9   XDoclet and mock objects
  10  XDoclet and portlets

PART FOUR: Extending XDoclet
  11  Custom code generation with XDoclet
  12  XDoclet extensions and tools

APPENDICES:
  13  Installing XDoclet
  14  XDoclet task/subtask quick reference
  15  XDoclet tag quick reference
  16  XDt template language tags
  17  The future of XDoclet

You can see from this list that there are distinct parts to the book, which each offer something totally different.

Part One: The basics

The book starts of taking a step back and discussing code generation, and why you would want to solve problems in a code gen way. This is a good way to start off, as it gives you grounding. There are some definitely words of wisdom (common sense) here:

  1. Don’t generate what you don’t understand
  2. Test the generated code
  3. Don’t be afraid to change your design to accommodate generation
  4. Generate layer by later, piece by piece
  5. Keep generated files out of the code repository (you may laugh, but I have seen this in numerous gigs)
  6. Look for repetition

I would have actually really enjoyed more content in this section…. more best practices, anti-patterns, and experiences. Although,, to be fair, some of this comes throughout in the book.

After the crash-course on code generation, you are quickly shown XDoclet itself. Here you get a taster, with the main course to come.

Part Two: Using XDoclet with enterprise Java

This section is the bread and butter of what XDoclet is about. Here we are walked through the various parts and pieces of enterprise Java, and how XDoclet can take on some of the burden and generate some of the fluff for us.

We start of at the beginning of XDoclet, EJBs. Here you learn about the myriad of artifacts that XDoclet can generate for you. Not just the interfaces and deployment descriptors, but DAOs, helper classes, and more.

Next in line is the web tier. First you get the “standard” stuff (web.xml), but then we are moved into Struts and WebWork, and how those frameworks have XDoclet support.

Finally we are taken into the world of the individual application servers (JBoss, WebLogic).

Part Three: Other XDoclet applications

At this point you will have a good understanding of what XDoclet can do for you. You will probably also realize that this code gen pattern is very repeatable. Others have come to the same conclusion, and here you see the breadth of work that contributors have dealt with.

You name it, and there is XDoclet support of some kind. If you are using any of the following, this section will help you:

  1. Persistence: JDO, Hibernate, Castor
  2. Web Services: Apache Axis and Apache SOAP
  3. JMX: Standard MBean interfaces, JBossMX, and MX4J
  4. Mock objects: Generating mock implementations of your interfaces with XDoclet
  5. JSR 169 Portlets

Part Four: Extending XDoclet

At this point you may think “aren’t most of the technologies covered for me?” This may be the case for some projects, but you will often run into something where you would love to tie into the code generation platform. At first you may find yourself tweaking some templates to give you more functionality. Or you may be using an application server which isn’t supported yet, and will want to create some templates for that.

You may also realize that your project could really use some custom code generation. Maybe you have a pattern that your business logic follows, and code generation could really help you there. This is what Part Four is all about.

Here the authors give us some interesting dialogue such as:

  1. When should you bother with custom code generation?
  2. What are the risks / rewards of custom generation?

Then you will be shown the details of the XDoclet templating languages, and various design decisions. The templating approach may seem a little archaic now (all of these weird proprietary XML tags), and in my opinion it is. One of the goals of XDoclet 2 gets away from this world, and ties into templating languages that we know and love (e.g. Velocity).

After you learn the insides of XDoclet, you will also be shown a whole set of tools that surround it such as AndroMDA, Middlegen, IDE support, and more.

Conclusion

If you are using XDoclet now or are interested in learning more about it, then you should get this book. It covers the bases nicely, and you will pick it up from time to time as a reference long after you read it.

It will be interesting to see what happens to XDoclet as the world of JSR 175 metadata approaches (there is still a place for code generation no matter what others say!), and who knows the future of XDoclet 2.