Overview

In Part 2 of this series, you saw how to save time and gain reuse at the code pattern level through the use of templates and code generation. But in most cases, this isn't enough. You need to be able to insert this generated code into existing code, or allow future developers to customize the generated code without having to rewrite everything whenever the code gets regenerated. Ideally, the creators of the code generator want to be able to support all future developers' needs, from changing method implementations and changing method signatures all the way to changing the inheritance structure of the generated class. This is a tricky problem, and currently there aren't any good, generalizable solutions. But there is a good Java™-only solution: JMerge.

JMerge is an open source tool delivered with the Eclipse Modeling Framework JMerge enables you to customize the generated models and editors without having your changes battered by regenerating the code. JETEmitter supports JMerge if you provide a description of how to merge the freshly generated code with the existing, customized code. This article walks you through an example to explore some of the different options available.

Back to top

First steps

Suppose you've joined a new project where you must create a JUnit test class for every class that you write, which must test each method that you write. Being a conscientious but efficient (or lazy) developer, you set out to write a plug-in that will take Java classes as input, and generate stubs for JUnit test cases. You blaze ahead and create the JETs and the plug-in and now want to allow users to customize the generated test cases, but still regenerate whenever the interface of the original class changes. To do this, you use JMerge.

The code to invoke JMerge from the plug-in is straightforward (see Listing 1). A new JMerger instance is created with the URI of the merge.xml, the source and target are set, and merger.merge() is called. Then, the merged contents can be extracted as merger.getTargetCompilationUnit().

	// ...
	JMerger merger = getJMerger();
	
	// set source
	merger.setSourceCompilationUnit(
		merger.createCompilationUnitForContents(generated));
	
	// set target
	merger.setTargetCompilationUnit(
		merger.createCompilationUnitForInputStream( 
			new FileInputStream(target.getLocation().toFile())));
	
	// merge source and target
	merger.merge();

	// extract merged contents
	InputStream mergedContents = new ByteArrayInputStream(
		merger.getTargetCompilationUnit().getContents().getBytes());
		
	// overwrite the target with the merged contents
	target.setContents(mergedContents, true, false, monitor);
	// ...

// ...
private JMerger getJMerger() {
	// build URI for merge document
	String uri = 
	   Platform.getPlugin(PLUGIN_ID).getDescriptor().getInstallURL().toString();
	uri += "templates/merge.xml";
		
	JMerger jmerger = new JMerger();
	JControlModel controlModel = new JControlModel( uri );
	jmerger.setControlModel( controlModel );
	return jmerger;
}

To start, use the minimal merge.xml in Listing 2. It declares the <merge> tag, and default namespace declaration. The main part is in the merge:pull element. Here, the body of every method in the source will replace the body of the corresponding method in the target. If the method doesn't exist in the target, it will be created. If a method is in the source and not in the target, it will be left alone.

<?xml version="1.0" encoding="UTF-8"?>
<merge:options xmlns:merge=
   "http://www.eclipse.org/org/eclipse/emf/codegen/jmerge/Options">

    <merge:pull 
      sourceGet="Method/getBody"
      targetPut="Method/setBody"/>

</merge:options>

Back to top

Discriminating generated methods

A problem with this simple approach becomes quickly clear: Whenever you change the source and regenerate, you lose all of your changes. You need to add some mechanism to tell JMerge that some methods have been customized and should not be overridden. To do this, use the <merge:dictionaryPattern> element. A merge:dictionaryPattern allows you to use regular expressions to differentiate between Java elements.

<merge:dictionaryPattern
   name="generatedMember" 
   select="Member/getComment" 
   match="\s*@\s*(gen)erated\s*\n"/>

<merge:pull 
   targetMarkup="^gen$"
   sourceGet="Method/getBody"
   targetPut="Method/setBody"/>

The dictionaryPattern defines a regular expression that will match a Member with "@generated" somewhere in the comment. The select attribute lists which aspect of the Member will be compared to the regular expression given in the match attribute. The dictionaryPattern is identified by the string gen, which is marked by the parentheses in the match attribute's value.

The merge:pull element has an additional attribute, targetMarkup. This matches the dictionaryPattern, which must be matched in the target code before the merge rule will be fired. Here, we are checking the target and not the source, so users can customize the code. When the user removes the "@generated" tag in the comment, the dictionaryPattern will not match the target, and the method body will not be merged.

/**
 * test case for getName
 * @generated
 */
public void testSimpleGetName() {
	// because of the @generated tag,
	// any code in this method will be overridden
}

/**
 * test case for getName
 */
public void testSimpleSetName() {
	// code in this method will not be regenerated
}

You might notice some elements that must not be customized and that must always override any attempt to customize them. To support this, define another dictionaryPattern that will look for some other tag in the source (and not the target), for instance @unmodifiable. Then define a pull rule that checks the sourceMarkup instead of targetMarkup, so the user is prevented from deleting the tag and blocking the merge.

<merge:dictionaryPattern
   name="generatedUnmodifiableMembers" 
   select="Member/getComment" 
   match="\s*@\s*(unmod)ifiable\s*\n"/>

<merge:pull 
   sourceMarkup="^unmod$"
   sourceGet="Member/getBody"
   targetPut="Member/setBody"/>

Back to top

Fine-grained customizations

After using this solution for a while, you'll notice that some methods have some common non-customizable code (such as tracing and logging code) within a customizable method. Instead of generating or blocking the entire method body, you may want to regenerate portions of the method, but leave other sections for the users to customize.

To do this, replace your earlier pull target with Listing 6.

<!-- if target is generated, transfer -->
<!-- change to sourceMarkup if the source is the standard -->
<merge:pull 
   targetMarkup="^gen$"
   sourceGet="Method/getBody"
   sourceTransfer="(\s*//\s*begin-user-code.*?//\s*end-user-code\s*)\n"
   targetPut="Method/setBody"/>

This overwrites everything before the string "// begin-user-code" and after "// end user-code" and leaves all of the customized code in between. In the regular expression above, the "?" marks the code that will remain in the target with everything else being replaced. You can do something similar with the JavaDoc comments, so that you copy the comments across but leave space for user customization.

<!-- copy comments except between the begin-user-doc
     and end-user-doc tags -->
<merge:pull 
  sourceMarkup="^gen$"
  sourceGet="Member/getComment"
  sourceTransfer="(\s*<!--\s*begin-user-doc.*?end-user-doc\s*-->\s*)\n"
  targetMarkup="^gen$"
  targetPut="Member/setComment"/>

To support comments, first change the begin and end tags to follow HTML comment syntax so they won't appear in the generated JavaDoc, and change the sourceGet and targetPut attributes to use "Member/getComment" and "Member/setComment". JMerge allows you to get and put many different aspects of Java code at a fine-grained level (see Appendix A for more information).

Back to top

Next steps

So far, we've covered transferring the bodies of methods, but JMerge can also handle fields, initializers, exceptions, return values, import statements, and other Java elements. The same basic ideas apply to these with perhaps only a few minor changes. You can see how you might use these by looking at plugins/org.eclipse.emf.codegen_1.1.0/test/merge.xml (I am using Eclipse 2.1, so the version of the ecore plug-in may be different if you are using a different version of Eclipse). This is a fairly simple example and doesn't use the sourceTransfer tag, but it shows one way to handle exceptions, flags, and other Java elements.

For a more sophisticated example, look at the way EMF uses JMerge: plugins/org.eclipse.emf.codegen.ecore_1.1.0/templates/emf-merge.xml. You can see that EMF only allows partial customization of JavaDoc, but with the tips above you can add your own support for method bodies (provided you modify the JETs to have the new markup).

Back to top

Appendix A: Valid targets

Within the dictionaryPatterns and pull rules, we have used "Member/getComment" and "Member/getBody" and their setters, but there are many more options available. JMerge supports matching and replacing on any class defined in org.eclipse.jdt.core.jdom.IDOM*. The options available are shown in Table 1.

Table 1. Valid targets

Back to top

Appendix B: merge:pull attributes

Table 2 shows the attributes of the merge:pull element.

Table 2. merge:pull attributes

Back to top

Download

Information about download methods

Resources

Learn

• Read the other articles in this "Eclipse Modeling Framework" series: Part 1, about creating and using EMF models; and Part 2, about generating code with Java Emitter Templates (JET).
  
  
• The Eclipse Modeling Framework (EMF) has all of the documentation, source code, and latest builds.
  
  
• The IBM Redbook " Eclipse Development using the Graphical Editing Framework and the Eclipse Modeling Framework" has a more elaborate example and covers more customization features.
  
  
• Expand your Eclipse skills by visiting IBM developerWorks' Eclipse project resources.
  
  
• Browse all of the Eclipse content on developerWorks.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Get products and technologies

• Download the source code for the JUnit plug-in.
  
  
• Download just the final merge.xml.
  
  
• Check out the latest Eclipse technology downloads at IBM alphaWorks.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  

Discuss

• If you have questions, try the EMF newsgroup. If you haven't used an Eclipse newsgroup before, read the rules and how to apply for a password.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Overview
• First steps
• Discriminating generated methods
• Fine-grained customizations
• Next steps
• Appendix A: Valid targets
• Appendix B: merge:pull attributes
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Open source on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers