ToString() Generator Plug-in

You don't have to wait for Eclipse 3.5 to conveniently generate toString() method for any class. Here's a plug-in version, tested with Eclipse 3.2, 3.3 and 3.4.
Enjoy!

ToString() generator status update

Since my last post I've been working mainly on user documentation and jUnit tests. I managed to create an extension point for my generator. It lets you change not only the look of generated code, but also the way the templates are handled (so you can for example add your own tokens). I also tried to add toString() generation to code completion proposals, but there are some problems I can't solve right now. This and the fact that JDT guys are rather skeptic about this feature made me postpone the work on it.

So the project is now finished and waiting to be reviewed by JDT team. I can't wait for the results. If everything goes fine, it will be added to Eclipse 3.5. Meanwhile, as I have nothing better to work on (and official end of GSoC is August 18th), I'll try to make the generator a separate plugin so that it can be used with earlier versions of Eclipse.

all bout toString

GSoC midterm evaluation is now behind us so I think it's a good occasion to sum up my progress. I want to describe what is already working and what I'm going to add. I hope this post will be also a good start for creating user documentation.

1. Code styles

   
   Code style determines how the generated method works and what classes it uses. There are several code styles available to chose from the combo box in generator's dialog.
   
   
   

   • String concatenation

     
     This style uses simple sum expressions so it's very efficient and relatively easy to read and modify. Here's an example outcome in the simplest case:
     

     return "FooClass [aFloat=" + aFloat + ", aString=" + aString + ", anInt=" + anInt 
       + ", anObject=" + anObject + "]";

     
     With "Skip null values" option turned on, the code becomes a little harder to read:
     

     return "FooClass [aFloat=" + aFloat + ", "
       + (aString != null ? "aString=" + aString + ", " : "") 
       + "anInt=" + anInt + ", " 
       + (anObject != null ? "anObject=" + anObject : "") + "]";

     
     
   
   

   • StringBuilder/StringBuffer

     
     This style uses StringBuilder if project is compatible with JDK1.5 or later and StringBuffer otherwise.
     

     StringBuilder builder = new StringBuilder();
     builder.append("FooClass [aFloat=");
     builder.append(aFloat);
     builder.append(", aString=");
     builder.append(aString);
     builder.append(", anInt=");
     builder.append(anInt);
     builder.append(", anObject=");
     builder.append(anObject);
     return builder.toString();

     
     The "Skip null values" option doesn't obfuscate the code as much as previously:
     

     StringBuilder builder = new StringBuilder();
     builder.append("FooClass [aFloat=");
     builder.append(aFloat);
     builder.append(", ");
     if (aString != null) {
      builder.append("aString=");
      builder.append(aString);
      builder.append(", ");
     }
     builder.append("anInt=");
     builder.append(anInt);
     builder.append(", ");
     if (anObject != null) {
      builder.append("anObject=");
      builder.append(anObject);
     }
     return builder.toString();

     
     
   
   

   • String.format();

     
     This style is very pleasant with relatively short list of elements, but with longer ones it becomes hard to see which fields are associated with which variables. Unfortunately, the "Skip null values" option is ignored by this style.
     

     return String.format("FooClass [aFloat=%s, aString=%s, anInt=%s, anObject=%s]",
       aFloat, aString, anInt, anObject);

     
     For JDK1.4 and earlier, the code is slightly different:
     UPDATE: As I learned today, there's no String.format() in JDK 1.4, so MessageFormat.format() will be used instead:
     

     return MessageFormat.format("FooClass [aFloat={1}, aString={2}, anInt={3}, anObject={4}]", 
       new Object[] { Float.valueOf(aFloat), aString, Integer.valueOf(anInt), anObject });

     
     
   
   

   • Apache Commons-Lang ToStringBuilder

     
     When this style is chosen, format template is ignored because ToStringBuilder takes care the output string's format itself. Maybe it's a little less flexible, but the power of this solution is that you can easily change the style of all toStrings within the project without changing any actual object's toString method.
     

     ToStringBuilder builder = new ToStringBuilder(this);
     builder.append("aFloat", aFloat);
     builder.append("aString", aString);
     builder.append("anInt", anInt);
     builder.append("anObject", anObject);
     return builder.toString();

     
     Skipping nulls works this way:
     

     ToStringBuilder builder = new ToStringBuilder(this);
     builder.append("aFloat", aFloat);
     if (aString != null)
      builder.append("aString", aString);
     builder.append("anInt", anInt);
     if (anObject != null)
      builder.append("anObject", anObject);
     return builder.toString();

     
     
   
   

   • Spring Framework's ToStringCreator

     
     This style behaves the same as Apache ToStringCreator except it uses different class to create output string.
     
   
   
   
   

2. Format templates

   
   This is a simple mechanism that allows you to change format of generated method's output string: beginning, ending, separator, and so on. There are four tokens to use:
   
   
   
   
   

   ${class.name}	inserts the class name as a String
   ${member.name}	inserts a member's name
   ${member.value}	inserts a member's value
   ${otherMethods}	this token must stand between the separator and the ending string

   
   This is the template used for all examples in the previous part of this post:
   

   ${class.name} [${member.name}=${member.value}, ${otherMembers}]

   
   And of course, output string for this template looks like this:
   

   FooClass[aFloat=1.0, aString=hello, anInt=10, anObject=null]

   
   

I plan to define more tokens:


• inserting super.toString() and hashCode() (now they can be printed the same way as other methods which is not convenient)


• ${class.getName} to use this.getClass.getName() instead of plain string


• two different tokens for printing method names with or without parenthesis at the end


• I'm thinking about more type specific options, e. g. putting strings between quotation-marks, printing integers as hexadecimal, printing length of arrays and so on. But don't know how they should work...






3. Arrays handling

   
   When "Ignore arrays' default toString()" option is switched on, generated toString() method lists items contained in arrays, for example
   

   intArray = [1, 2, 3, 5, 8, 13]

   instead of

   intArray = [I@9304b1

   
   This is realized differently according to chosen JDK compatibility. For JDK1.5 and later java.util.Arrays.toString() is used. For earlier versions, which do not have this method, a helper arrayToString() method is generated:
   

   private String arrayToString(Object array, int length) {
    StringBuffer stringBuffer = new StringBuffer();
    stringBuffer.append("[");
    for (int i = 0; i < length; i++) {
     if (i > 0)
      stringBuffer.append(", ");
     if (array instanceof Object[])
      stringBuffer.append(((Object[]) array)[i]);
     if (array instanceof float[])
      stringBuffer.append(((float[]) array)[i]);
     if (array instanceof int[])
      stringBuffer.append(((int[]) array)[i]);
    }
    stringBuffer.append("]");
    return stringBuffer.toString();
   }

   
   It takes object as a parameter and then uses instanceof so that one method can work for all kinds of arrays. It checks only these array types that are actually passed to it in the main toString() method, so in case new types are added, arrayToString is regenerated every time toString generator is run.
   



4. Limiting number of items

   
   This option changes behavior of generated toString in case of Collections, Maps and Arrays(if "Ignore default arrays' toString()" option is on). Again, generated code differs for each JDK version.
   
   In JDK1.6 collection or map is turned into an array (collection.toArray() or map.entrySet().toArray()), then Arrays.copyOf() is used to make it shorter and Arrays.toString() is called to print it out. Of course, usually it's also necessary to check for nulls. All in all, the code becomes fairly complicated, with something like this in the worst case:
   

   builder.append(hashMap != null ? Arrays.toString(Arrays.copyOf(hashMap.entrySet().toArray(),
     Math.min(maxItem, hashMap.size()))) : null);

   
   At least there's no need to generate additional methods.
   
   Since Arrays.copyOf was introduced in JDK1.6, in earlier versions helper toString() methods must be used to limit number of elements. In case of arrays the method is similar to the one showed in the previous part, only with one more statement at the beginning: length = Math.min(lenght, maxItem);. For collections and maps there's another method:
   

   private String toString(Collection collection) {
    StringBuilder stringBuilder = new StringBuilder();
    final int maxItem = 10;
    stringBuilder.append("[");
    int i = 0;
    for (Iterator iterator = collection.iterator();
      iterator.hasNext() && i < maxItem; i++) {
     if (i > 0)
      stringBuilder.append(", ");
     stringBuilder.append(iterator.next());
    }
    stringBuilder.append("]");
    return stringBuilder.toString();
   
   }

   
   This method is not overwritten every time the generator runs so that it can be changed by user.
   
   Another solution would be to convert a collection into an array and then use arrayToString, but this way is more efficient and looks better if there are no arrays.
   



5. Plans for the future

   
   In addition to things I mentioned earlier, I'm going to create an extension point for new code styles and add toString generation to code assist. This time I won't be able to copy solutions from hashCode/equals generator though, so the work may not go as smooth as earlier. Still, I don't loose my optimism :)

generator ready to use

The toString() generator reached the state where it can be useful. For now there's only one coding style - string concatenation, but I plan add more of them. There's support for templates and all the options visible in the dialog have effect on generated method. I'd love to hear opinions from people interested in the subject: are the options useful? are the generated methods well implemented? should something be added? should the templates mechanism be enriched?

Again, to see my work you can apply the latest patch from bug 26070 to the org.eclipse.jdt.ui plugin. I'm sorry if it's inconvenient but I use some internal Eclipse packages and creating a separate plugin would be too difficult for me. If you like, you can download a ready project, import it to Eclipse workspace and run as "Eclipse Application". Here's the project working under Eclipse 3.4 and here version for Eclipse 3.5.

toString() generator will be in a separate dialog

Last week I did some work to make my code clean enough to post on Bugzilla. When I submitted it, Martin suggested that it's not a good idea to have toString() generator in the same dialog with hashCode()/equals(). I was surprised at first, as he was the first person to tell me so. But his arguments were strong: the dialog is too big and there's no good name for the action. His main argument was that hashCode/equals doesn't usually use the same fields as toString. I had doubts about it but I don't have enough experience to argue.
I've made a quick poll about it on the eclipse IRC channel - 100% of participants said that toString generation should not be combined with hashCode/equals (100% of 1 person - I guess IRC is not a good place for polls :P)
I tried to fit elements on the dialog to make it look better, but without satisfactory results (see here and here). So I decided to make a separate action and I won't get back to the previous idea unless there's *a lot* of people asking for it. I submitted a patch with the new action today and I'm waiting for feedback. If you're too lazy to check the patch, here's a screenshot of prepared dialog:

Plan for the next week: investigate possible ways of template handling. I know there's a rich template support in Eclipse but I'm afraid it may not be exactly what I need as these templates relate to the code directly. I saw a nice dialog with templates in Mylyn plugin (Preferences->Mylyn->Team) and I'm going to see how it's done. Do you have any suggestions of where else I should look?

First steps...

It's the end of the semester here and I must work hard on my grades therefore I can't spend much time on my GSOC project (this situation will last until the last week of june). I managed to do some work this weekend though and here are the results:

1. I created a simple toString() generator to see if it will work. And it does :) For now it's only a string concatenationi with hardcoded format. I don't know how to put line breaks in generated code and I have no idea where to look for it. Any clues?

2. I decided to start with something simple - redesign hashcode/equals generation dialog to include toString() features. Here's the effect:


"Up" and "Down" buttons already work - I copied this functionality from "generate constructor using fields" dialog. The rest of the controls don't have any effect yet..
I plan to add a list of class methods to the view (in a separate node of the tree). With all methods on the list, the option to use getters instead of fields accessors is no longer needed (unless we want this option for hashCode and equals, but that's another story).

That's all for now, I know it's not much. But I think I can complete the project without many problems if I focus all of my attention on it next month.

BTW, Mike, should I put my code somewhere for everybody to see? Right now I modify my local copy of org.eclipse.jdt.ui plugin - is that ok?

toString() with templates? Hmm...

As my blog has just joined Planet Eclipse, I'd like to say 'hi' to all the Eclipse fans :) For the next few months you'll probably be hearing from me about automatic toString() generation feature for Eclipse as this is my project for this year's Google Summer of Code.

I'd like to start by sharing some dilemmas I have regarding the form of templates support in the generator. At first I wanted to use templates to set the format of the generated string, for example this template would create toString() returning a class name, followed by a comma separated list of values in one line:

${class_name}: ${field_value}, ${other_fields}

If every field should be placed in a separate line and have its name printed, the template would look like this:

${class_name} (
        ${field_name} = ${field_value}
        ${other_fields}
    [Super: ${super_string}]
)

The ${super_string} element puts in the call to super.toString(). There could be other elements to call other common methods. The method generated with this template would look like this:

public String toString() {
 return "FooClass (\n"
  + "        field1 = " + field1
  + "        field2 = " + field2
  + "    [Super: " + super.toString() + "]\n"
  + ")";

I thought this was fine until Mike Haller suggested that not only the format of generated string is important, but also the style of the implementation itself. Some might want to use string concatenation, others StringBuilder or ToStringCreator from the Spring Framework and so on. I'm still not completely convinced about this - string concatenation is IMO the easiest to read and probably the fastest implementation (java compiler turns '+' into StringBuilder.append()) - then why would someone need something else? But let's assume that multiple style support is necessary. One solution is to hardcode the most common implementations and let the user choose one in the generator's dialog box. But then there will always be unhappy users who need a style that was not implemented.

The other solution is to use templates to determine the toString() method body itself. This approach is used by JUtils ToString Generator, but it's not very flexible. You cannot change the method behaviour for specific categories of fields, for example to skip null values (comparing primitives to null is an error). Considering this I realized that if there were some additional mechanisms making it more flexible, it would be more than just a toString() generator. It could easily replace almost all source generators currently available in Eclipse - a general purpose code generator useful always when you need to perform similar operations on multiple fields (or methods) of a class!

My idea to accomplish this is to use two level template-tree. Every node would have attributes determining when it should be used. To show what I mean, I will use an example of hashCode() method. Here, the top level template (marked to use only with fields) would look like this:

public int hashCode() {
    final int prime = 31;
    int result = 1;
    ${hashcode.sub1}
    ${hashcode.sub2}
    return result;
}

The subtemplates should be called twice in order to determine if there should be any separator between them (here the separator is just "\n\t"). There will be several children:

• result = prime * result + ((${field_name} == null) ? 0 : ${field_name}.hashCode()); (Marked for use with objects)


• result = prime * result + ${field_name}; (Marked for use with ints)


• result = prime * result + Float.floattoIntBits(${field_name}); (Marked for use with floats)


• result = prime * result + (${field_name} ? 1231 : 1237); (Marked for use with booleans)


• And so on...

Can you see the potential of this mechanism? :) One more extension is template grouping, which allows to iterate over class fields more than once. Again, let me use an example - generate constructor using fields. Here's the top level template:

public ${class_name}(${arg.sub1}, ${arg.sub2}) {
    ${body.sub1}
    ${body.sub2}
}

We have two groups here: the arg group for method arguments with this template:

${field_type} ${field_name}

and the body group with this template:

this.${field_name} = ${field_name};

This is just a general idea and definitely needs more design, but it looks very promising to me. As this idea is a bit different from what I presented in my GSOC application, I'm not sure if I should implement it. So I have a question to GSOC mentors who voted on my project: would you still vote for me if I presented the idea above? Another question is to people who know more about JDT and generation of the code from templates: is this going to work? I mean - maybe there are some major problems I'm not aware of... Of course, the question to everyone is how do you like the idea and how would you extend it? :)

If the project turns out to be too hard for a beginning developer like me or mentors won't agree to these changes, I would just implement the modest toString() generator and go for the general generator later. Now I'd like to hear as many opinions as possible :) I'm not sure if comments to this post is a good place for such discussion, but let's start with it. If it should moved somewhere else, please let me know.

Preparing for coding

The start of GSOC coding phase is getting closer and closer, so I started examining and debuging the Eclipse source. I'm beginning to understand how all the code generators work, although not without problems. The most difficult for me is the dialogs part - I would say that a little refactoring should be done here. Anyway, it's just GUI so I think it won't be so hard to handle it. As for the code generation itself, the operations seemed rather clear to me. Also, I'm going to read this article about abstract syntax tree to get more details.

After reading Remy's great article How to contribute to Eclipse projects I decided to give it a try and found this bug: 203132. It was pretty easy and referred to functionality I was just examining. But still I forgot to clean up some unused strings and had to send the patch three times. Well, at least I'll be more careful next time. Too bad it's too late to make changes in Eclipse 3.4. It would be much more fun if I didn't have to wait so long to see my code in HEAD CVS.

Welcome!

In this blog I will be reporting my progress on the "toString() generation" project for Eclipse, which is part of this year Google Summer of Code.

Through this blog my mentors, Markus Kuppe and Mike Haller, will know what I'm doing and I hope to get some feedback from the Eclipse community.