Take a look at this interface.  If I find this populate method, I am likely to have to open implementations.  I don’t know if it populates one map from the other or both maps.

import java.util.Map;

public interface NastyPopulator {

void populate(Map<String, String> driver, Map<String, String> driverHolder);

}

The problem is the semantics of map are that you can read from maps or you can write to them.  I think this is a slightly better approach below.

I have used ImmutableMap.Builder.  The semantics of this are that it is used to build things.  I will call build() on the object later to get a map.  Next its an ImmutableMap.  So not only am I declaring that the two parameters are likely to be used to build something, that thing will ultimately be Immutable so in effect the signature declares that I am not expected to make modifications later.  Finally the method name is unambiguous buildMaps, which pretty much says what its going to do.

import com.google.common.collect.ImmutableMap;

public interface LessNastyPopulator {

void buildMaps(ImmutableMap.Builder<String, String>  driver, ImmutableMap.Builder<String, String> driverHolder);

}

Feels like a stronger declaration to me. If ImmutableMap is awkward you could define your own static builder and pass that in, at least your still declaring up front, that this method is builds the two maps. If the method is reading from one map and building others, how about passing an iterator and a builder?

                          

Steps taken to refactor

There was actually very little to do.

Step 1, add a maven dependency

            com.google.collections
            google-collections
            1.0-rc3
            jar

Step 2, replace the array with an ImmutableList

private static final LineResult[] EMPTY_LINERESULT_ARRAY = new LineResult[0];
private LineResult[] lineResults = EMPTY_LINERESULT_ARRAY;

could become:

private List<LineResult>  lineResults = ImmutableList.of();

In the end I used ImmutableList to clearly my intent. The usage is internal to the class so there is no advantage in using the List interface.

private ImmutableListst<LineResult>  lineResults = ImmutableList.of();

Step 3, The constructor and static factory methods are simplified
We are no longer using an array to back the list, so the protective copy can be moved from the constructor into the static method. This reduces the window of vulnerability you are exposed to before capturing the data held in the list. This is a direct result of the google class providing a static factory method. Nb. Its a shame that the standard collections don’t provide static factory methods.

Prior to the changes the protective copy was done in construction like this.

 this.lineResults = lineResults.toArray(EMPTY_LINERESULT_ARRAY);

This result is a much simpler constructor.

private ResultsFileSearch(File fileFound, ImmutableList<LineResult> lineResults) {
        this(fileFound);
        this.lineResults = lineResults;
}

My newInstance method makes use of the ImmutableList.copyOf static factory method resulting in a very clean conversion of List into Immutable list. Note that generics is inferring the type.

public static ResultsFileSearch newInstance(File fileFound
                 , List<LineResult> lineResults) {
        return new ResultsFileSearch(fileFound
                        ,ImmutableList.copyOf(lineResults));
}

Step 4, the getLineResults method no longer has to deal with the array or conversion.
The original array backed object had to deal with returning either an empty list or conversion to an unmodifiable list. There are two things I did not like about this when I wrote the original.

• The code has to check the array resulting in some conditional logic. This increases the test overhead slightly.
• The use of Collections.unmodifiableList(Arrays.asList(lineResults)); is very ugly and slow.

This was the original, note the subtle bug when returning an empty list.

 public List<LineResult> getLineResults() {

        if ((this.lineResults.length == 0)) {
            return Collections.emptyList();
        } else {
            return Collections.unmodifiableList(Arrays.asList(lineResults));
        }
        return this.lineResults;
}

I hope you agree its a much simpler version using the google code. As we are now using the Immutable implementation, we don’t have to worry about exposing the reference.

public List<LineResult> getLineResults() {
        return this.lineResults;
}

Conclusions

Using the google collections makes my implementation much cleaner. Several complexities are given over to the google collections classes. Moreover testing of my class is simpler. The changes are contained within the class. None of the method signatures change, which has two consequences. On the plus side the re-factor is contained within this class. On the negative side, any code modifying the list will raise an UnsupportedOperationException which was no different to my original version. The construction of my class might be slightly slower, the memory overhead slightly bigger now that we are not using the array. Counter to this, the getLineResults method is quicker as it now only returns a reference. In my program this is more important as architecturally it uses bounded queues to hold these objects for processing by threads. So although its using a little extra memory, its constrained. The performance gain is worth it.

I recommend using the com.google.common.collect package but adhere to the caveats i.e don’t expose the types in an API etc.