How can I customize XDoclet to generate what I want?
Location: http://www.jguru.com/faq/view.jsp?EID=736016
Created: Jan 27, 2002 Modified: 2002-01-27 22:40:32.405
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

XDoclet is designed with extensibility in mind. You can modify the way it works in various ways:

• You can set a modified template file as the template used by a sub-task. All the output is generated based on template files which have a .j extension and are based on XDoclet's own template engine. You can make a copy of the relevant template file, modify it, and make the sub-task use your copy of the template by the templateFile attribute available for all sub-tasks.
  Example: <remoteInterface templateFile="c:\mytemplates\myremote.j"/>
• Many of the sub-tasks have some customization merge points in them. You can use these merge points to plug in your special piece of template into the standard templates.
  Example: Say you want to provide a toXml() method in all EJB data-object classes. By looking at dataobject's documentation you find out that it supports a customization merge point called dataobject-custom.j. So you create a dataobject-custom.j file, put it in the folder which is pointed to be mergeDir attribute of the subtask/task. dataobject will pick your merge files and merge it in. XDoclet assumes the content of that file is a template, so it parses it. This means you can write a templatelet (!) in it and use XDoclet's built-in template tags (such as <XDtPersistent:forAllPersistenceFields .../> to loop over all persistence fields and generate XML based on each field).
• Let's say you want to add some stub generation facility to <entitycmp/> sub-task so that a SOAP stub is generated for the EJB. You can define a MyEntityCmpSubTask class derived from xdoclet's xdoclet.ejb.EntityCmpSubTask and override relevant methods (generateForClass for example). Then you should let XDoclet know about this customized <entitycmp/> sub-task. you do so by using the subTaskClassName attribute of the subtask. Remember the customized class should be in XDoclet's classpath.
  Example: <entitycmp subTaskClassName="com.foobar.MyEntityCmpSubTask"/>

Where can I find the list of supported @tags and sub-tasks?
Location: http://www.jguru.com/faq/view.jsp?EID=736017
Created: Jan 27, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

In your copy of XDoclet, open docs/index.html. The left hand side pane has various links to different parts of the documentation. XDoclet is itself just a framework, the concrete tasks are based on this frameowork. Two concrete tasks exist: <webdoclet/> and <ejbdoclet/>, the former serves as a container for web development sub-tasks (such as web.xml generation, taglib.tld generation, struts/webwork and so on) and the later is a container for EJB-releated sub-tasks (such as ejb-jar.xml generation, remote/local interface generation and so on). By clicking on the wedoclet or ejbdoclet links in left hand side pane you can see a list of supported subtasks for each of these two tasks and all of their @tags. By clicking on each sub-task or @tag you see the detailed description for each.

How can I create new @tags, templates and sub-tasks?
Location: http://www.jguru.com/faq/view.jsp?EID=736435
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

You can easily create new @tags/templates/tasks/sub-tasks. We're enhancing it all the time so I'm not going to provide any details here. Refer to docs/architecture.html in the distribution for a detailed manual about it.

• You can use <template/> and <xmlTemplate/> subtasks. These sub-tasks are supported in all tasks automatically (webdoclet/ejbdoclet and even yourdoclet). The former is for any kind of output, the later has some facilities for XML output generation (automatic validation of generated content for example).
  Example: <template templateFile="c:\mytemplate.j" destDir="c:\output" destinationFile="report.html"/>
  Refer to the documentation for deatils of each of the above sub-tasks, you'll find a lot of options available.
• You can create your own task or sub-task by simply deriving from xdoclet.DocletTask and xdoclet.SubTask (or one of its sub-classes, TemplateSubTask, XmlSubTask or a more specialized one such as WebDotXmlSubTask). Use Ant's <taskDef/> facility to install the task. Use subTaskClassName attribute of all sub-tasks to install the subtask.

What are the merge points? What are they for?
Location: http://www.jguru.com/faq/view.jsp?EID=736437
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

Merge points (or merge files) are a mechanism XDoclet provides for merging in a user-written file with the template file. It has various uses:

• Not all class libraries out there use XDoclet @tags. You should be able to add Struts' servlet for example to the web application you're working on using XDoclet. So <deploymentDescriptor/> sub-task of <webdoclet/> (in fact the web_xml.j tempalte file, which is used by <deploymentDescriptor/>) provides a servlets.xml merge points. So you can create a file named servlets.xml and specifiy all not-XDoclet-annotated servlets in it.
• Putting @tags in code is good for development but sometimes you want to do deployment to various servers for example. Should you modify the @tags each time for each deployment? No, for deployment-oriented activities (for example specifying the table name an EJB maps to) it's better to use merge-points and use different copies of the merge point for different deployments.
• Merge points provides pluggability. You can use customization merge points to add a customized content to the generated stuff.

Is it possible to use XDoclet without Ant?
Location: http://www.jguru.com/faq/view.jsp?EID=736438
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

It's not possible to use XDoclet without Ant, for some good reasons. But anyway you should be able to invoke Ant from make for example.

Obviously it's ridiculous to add @tags to source code for one-time operations where you generate something from the @tags and never come back to use the @tag again. So @tags are good for cases where you run something continuously, for cases where the code changes and the generated stuff should be regenerated based on the new code/@tags. Ant is a great tool for automating this procedure, it's a great tool for "Continuous Integration".

I don't like the code convention XDoclet uses for generating code. How can I change it?
Location: http://www.jguru.com/faq/view.jsp?EID=736442
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

XDoclet does not have any mechanism to apply a specified code convention, built-in. It's really out of the scope of this tool. All templates use a single coding convention, which might not be what you like. You can pipe the generated code to another tool for code beautification. Such a code beautifier which is sued in XDoclet's own development is PrettyPrinter module of jRefactory. It has an Ant task which smartly checks file timestamps and even has CVS modification check in it, and beautifies the files if the have been modified since last run. Here is an example of its use:

<target name="beautify" depends="prepare">

   <taskdef name="pretty" classname="org.acm.seguin.ant.Pretty" classpath="${basedir}/../lib/prettyprinter.jar"/>

   <pretty settingsDir="${basedir}/../config" cvs="true" compileDir="${build.dir}/classes">
      <fileset dir="${src.dir}">
         <include name="**/*.java" />
      </fileset>
   </pretty>

</target>

I know XDoclet has various @tags for various EJB containers. Does that mean my application will run on all application servers?
Location: http://www.jguru.com/faq/view.jsp?EID=736444
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

No, XDoclet can't do any magic :-)

But at least it can make it a lot easier. There's built-in support for various application servers, so you can create deployment descriptors of each application server using XDoclet easily. For example to support jBoss there's a @jboss:blabal set of @tags, same is true for @weblogic:blabl, @orion:blabla, @websphere:blabla and so on. What you can do is to add these vendor-specific @tags to your source and generate deployment descriptors for each of the application servers you like. For example say you want to deploy CMP beans to both Orion and jboss. You define the database mapping by putting @tags of both @orion and @jboss for CMP beans. Here is how you define the mapping for a persistence field:

/**
 * @weblogic:dbms-column "name"
 * @orion:persistence persistence-name="name" sql-type="VARCHAR"
 */
 public abstract String getName();

Each application server supports different options and settings but using XDoclet you have a neat way of supporting each by simply maintaining them in the same source code.
 

All of the EJB samples XDoclet provides are for EJB 2.0. Is it possible to write EJB 1.1 applications using XDoclet?
Location: http://www.jguru.com/faq/view.jsp?EID=736447
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

Definitely. Set ejbSpec="1.1" in <ejbdoclet/> but follow the rules of EJB 2.0 in source code. This means instead of defining persistent fields as normal attributes (the way EJB 1.1 is), follow the abstract schema rules of EJB 2.0 like this:

/**
* @ejb:persistent-field
*/
public abstract String getName();
public abstract void setName(String name);

And remember you should define your CMP bean abstract and activate the <entitycmp/> sub-task of <ejbdoclet/>. <entitycmp/> generates a sub-class which is understandable by a EJB 1.1 container.

It's also worth to mention that XDoclet generates deployment descriptors which are spec version compliant (DTD points to correct version, elements and attributes have version specific details in mind, and so on).

<ejbdoclet/> has <entitycmp/>/<entitybmp/>/<session/> sub-tasks. What are they for? Why is a sub-class generated from my EJB?
Location: http://www.jguru.com/faq/view.jsp?EID=736448
Created: Jan 28, 2002
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

They provide some services for you:

• <entitycmp/> if ejbSpec="1.1" generates a EJB 1.1-based CMP bean from your EJB 2.0-based abstract CMP schema and provides a optimistic locking scheme for you by putting and auto-updating a version field. For 1.1 it also does the modification/dirty check so the ejbStore is called only when something has changed. For both spec version it handles data-object generation automatically for you, so you should activate it if you want to use <dataobject/>.
• <entitybmp/> does all the optimistic-locking/dirty-flag/etc plus it calls the DAO class automatically.

<entitycmp/>/<entitybmp/> and <session/> all try to also generate as much as possible labor intensive code you normally write. For example you should remember to put a no-argument ejbCreate method in your stateless session bean or define a no-op ejbActivate and so on. These tasks try to do that for you automatically, so you just concentrate on the business logic. It also results in source code which is more readable because there's no empty ejbActivate/etc or void stuff like that in it, all is hidden in the sub-class.

I'm getting lots of javadoc warning messages in console when I run XDoclet. What's the problem? Can I avoid it?
Location: http://www.jguru.com/faq/view.jsp?EID=757724
Created: Feb 13, 2002 Modified: 2002-02-14 06:49:29.971
Author: Ara Abrahamian (http://www.jguru.com/guru/viewbio.jsp?EID=718308)

You can safely ignore these warning messages.

Your code refers to a class that Javadoc can't find. Javadoc always complains about this, but it doesn't stop XDoclet from doing its job. It's a normal behavior from javadoc, because the bean you're running XDoclet on is refering to a class which is not yet generated by XDoclet but anyway javadoc tries to load it and it can't because it's not yet generated.

Unfortunately you can't get rid of these messages effectively. A later version of XDoclet will solve this issue by introducing its own doclet API.

PS: Note that the format of these warning messages vary in different versions of JDK. JDK 1.3 outputs "javadoc: warning - Cannot find class" while JDK 1.4 writes "cannot resolve symbol" in front of [ejbdoclet].