XDoclet: Attribute-Oriented Programming - Merge Points
Author: Aslak Hellesoy

##### XDoclet

- Overview
- News and Status
- Download/Installation
- Using XDoclet
- Best Practices
- FAQ
- License

##### Ant Task Reference

- <doclet .. />
- <ejbdoclet .. />
- <hibernatedoclet .. />
- <jdodoclet .. />
- <jmxdoclet .. />
- <mockdoclet .. />
- <portletdoclet .. />
- <springdoclet .. />
- <tapestrydoclet .. />
- <webdoclet .. />
- <wseedoclet .. />

##### Tag Reference

- apache (@soap @struts @axis @tapestry)
- bea (@weblogic)
- borland (@bes)
- caucho (@resin)
- ejb (@ejb @dao)
- exolab (@castor)
- hp (@hpas)
- hibernate (@hibernate)
- ibm (@websphere)
- java (@javabean)
- jboss (@jboss)
- jdo (@jdo)
- jmx (@jmx)
- jsf (@jsf)
- macromedia (@jrun)
- mockobjects (@mock)
- mvcsoft (@mvcsoft)
- mx4j (@mx4j)
- objectweb (@jonas)
- oracle (@oc4j)
- orion (@orion)
- portlet (@portlet)
- pramati (@pramati)
- spring (@spring)
- sun (@sunone)
- sybase (@easerver)
- tjdo (@tjdo)
- web (@web @jsp)
- webwork (@webwork)
- wsee (@wsee)
- xdoclet (@xdoclet @doc @msg)

##### Feature Documentation

- Using Value Objects
- EJB Environment Handling

##### Advanced

- Maven Plug-in
- Merge Points
- IDE Integration
- Migration from EJBDoclet
- Ant 1.5 Troubleshooting

##### Community

- Feedback
- Resources
- Tools

##### Development

- Developer Guide
- Javadoc (API)
- Template Language (*.xdt)
- XJavaDoc Site

##### Search XDoclet

##### Project Documentation

- About XDoclet
- Project Info
- Project Reports
- Development Process

## Introduction

A merge point is an "entry point" to XDoclet generated files. The developer can add custom data easily.

There are two different ways to use merge points.

### 1. Adding specific parts inside deployment descriptors

Having to hard code deployment descriptor specifics (ejb-jar.xml and vendor specific ones) in a source file simplifies the deployment work but has the limitation that the programmer must also take the deployer role.

Let's examine an example. You have, in your ejb-jar.xml, an env-entry element to a JDBC URL that you use inside a session bean (`test.ejb.SessionBean`) to access a database. You have included a tag

    @ejb.env-entry name="jdbcUrl" type="String" value="jdbc:hsqldb:hsql://thishost:1476"

and use the value returned by a JNDI lookup to get the SQL connection.

The problem is that you will need to change your code when the url changes. Several merge points exist in ejb-body.xdt. This file is the template for ejb-jar.xml, you can see the merge point we need: `<XDtMerge:merge file="ejb-env-entries-{0}.xml">`.
Every line between this tag and its closing tag will be replaced in the generated ejb-jar.xml file by the content of ejb-env-entries-SessionBean.xml, found under the directory given by the mergeDir attribute you specify for the task or the subtask and a directory structure given by the package of the class.

For example c:\mergedir\test\ejb\. Here is the content:

    <env-entry>
    	<env-entry-name>jdbcUrl</env-entry-name>
    	<env-entry-type>java.lang.String</env-entry-type>
    	<env-entry-value>jdbc:hsqldb:hsql://thishost:1476</env-entry-value>
    </env-entry>

You can now change this file independently of the source file.

Look into the .xdt files directly to find all defined merge points.

### 2. Adding specific generation of code

Entry points exist in template files used to generate the classes. For example in entitycmp.xdt (template for Entity Bean classes) you have `<XDtMerge:merge file="entitycmp-custom.xdt"></XDtMerge:merge>`. If you program something in this file (that will be searched for in the mergeDir of the task or subtask) the generated content will be included in the generated file.

Examine the existing .xdt files to learn the template language.