Cool. Rick Hightower Chief Technology Officer Trivera Technologies http://www.triveratech.com 520 290 6855 (Phone) 520 977 8605 (Mobile)
-----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Aslak Helles�y Sent: Wednesday, August 27, 2003 6:32 AM To: [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED] Subject: [Xdoclet-user] New XDoclet2 and Generama 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 <component> sub-elements. Writing an IDE plugin (for 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! -- http://blogs.codehaus.org/people/rinkrank/ ------------------------------------------------------- This sf.net email is sponsored by:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf _______________________________________________ xdoclet-user mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-user ------------------------------------------------------- This sf.net email is sponsored by:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf _______________________________________________ xdoclet-user mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-user
