Measure amount of WTFs per package or project

I created a library that measures amount of WTFs per package or project. This library is a by-product that derived from what I was doing few days ago:

I was dabbling with Java and decided to take a break. I came across a well know image that depicts code review session behind closed doors. The image called “The only valid measurement of code quality: WTF/minute”. I decided to make an extension to the latter concept.

This library brings you the ability to mark code smells in your source code (Classes, methods, fields etc.) with ‘WTF’ annotation. The WTF annotation accepts an arbitary message, if none provided, the default message ‘Dude.. WTF?!’ is used instead. When source compiles, the compiler generates a warning using the message from the detected annotation(s) and information about annotated element. The following is a sample output from compiling a class containing WTF annotations:

Warning: : In CLASS [wtf.per.project.model.DummyPojoImpl] :CLASS level => WTF?! Are you for real?! This naming convention is bad!
Warning: : In CLASS [wtf.per.project.model.DummyPojoImpl] : FIELD ‘SOME_CONSTANT’ => WTF?! What is this non-descriptive name?
Warning: : In CLASS [wtf.per.project.model.DummyPojoImpl] : CONSTRUCTOR ‘DummyPojoImpl(java.lang.String)’ => WTF?! Dude.. WTF?!

The library also provides a custom JUnit test runner class. The runner consumes package name, annotation class and search filter through @Grep annotation (used in conjunction with @RunWith). The runner scans .class files under the given package, its sub-packages and JARs for the given annotation (for example WTF.class) occurrences. If String regex pattern provided in @Grep, classes are filtered out from being scanned based on the filter. The runner uses a test class internally to assert whether the code is still infested with WTFs (or any other annotation class set in @Grep).

The analysis of .class files within given package, its sub-packages and any JAR files found is done using reflection. At first I was using third party library called ‘Reflections’ for this task (which is a very good tool btw!), but I ended up not using it anymore. I did not want to have third party dependencies and implemented my own meta data analysis in order to keep the library size small and lean. In the near future, I will extract the metadata analysis logic into a separate library. It should be quite flexible since there different .class file scanners in place. For example, scanner for constructors only or for method parameters, fields only etc.

So, if runner’s test assertion fails (given annotation like @WTF found present in the code), the test class generates metrics about how many WTFs are there and where. These metrics appended to the assertion failure message. For example, the following is the example of the custom JUnit runner:

@RunWith(WTFsPerProject.class) 
@Grep(packageName = "wtf.per.project.model", 
classNameFilter = ".*", annotationClass = WTF.class) 
public final class WTFsPerProjectRunner { }

I have few POJOs marked with WTF annoation, the following is the produced output after running the above runner:

Another example of the custom JUnit runner:

@RunWith(WTFsPerProject.class) 
//Grep only inner classes 
@Grep(packageName = "wtf.per.project.model", 
classNameFilter = ".*[$].*", annotationClass = WTF.class) 
public final class WTFsPerProjectRunner { }

Disclaimer

I created this library for fun. Nothing more. If someone actually decides to use it – great.

If you want you can fork it on Github

Please report if you experience any problems :)

Is TDD Only for … Junior Developers??

Just before the Easter holidays, I had a discussion with two senior developers from my project about TDD. These guys are experienced software engineers that have been around for some time: they have 11 and 20 years of experience in software development under their belts.

I don’t claim to be an advocate for TDD. Currently, I do not practice it (yet), but I do recognize and appreciate its importance. TDD really “forces” you to have clear understanding about the business requirements to be implemented. You cant implement what you do not understand, right? Because you have to write the test first, your code becomes more solid, less bug prune and you have better test coverage.

Sure, writing the test first its an interesting concept: You start writing a test, and you discoverer that you need a class, and possibly a function. You create the class, function and keep writing the test. Basically, you write few lines of test, and few lines of code, few more lines of test and few more lines of code etc. etc.

Ok, I think I diverted a bit, back to the topic :) The discussion took an interesting turn, and I still keep thinking about it. My question to them was – what do you think about TDD? The responses I received totally surprised me.

One of the claims supported by them, was that TDD does not serve much purpose, and a developer will end up re-factoring the unit tests eventually anyway as a result of re-factoring the concrete classes as the development goes on. So if latter is the case, my colleagues argued that there is no point writing unit tests first. Its better to finish writing concrete class, before attempting to write any unit tests.

Also, one of the developers claimed that many books and articles written on TDD discuss examples that are quite simple to implement, and in reality it is quite difficult to use TDD for complex business scenarios.

Another claim was that TDD should be used to teach junior developers the importance of unit testing, the experienced developers don’t really need to use it. The developers should follow KISS principles instead.

I respected their opinions about it, but it seemed fundamentally wrong to me that such experienced developers claim that TDD is basically overrated. The feeling that I got from them was that a lot of developers and software engineers in IT industry really got it wrong.

It got me wondering how, after more than ten years of experience in the industry, one does not appreciate one of the best software engineering practices around …

Offcourse, having said all that, I must point out that TDD is not suitable for every case. TDD can be effective only when it is clear what need to be implemented and there is a deep understanding of requirements.

Java, Good Ways – A Book of Unwritten Rules, Tips and Gotchas

A colleague of mine, who is currently my tech lead, wrote a book.

The book Java, Good Ways is a collection of unwritten rules, tips and gotchas collected over a long period of time. The book comes to minimize the gap between university studies and what Java developers actually need to know.

Have a look, read through, let me know what you think or simply leave a comment on Java, Good Ways :)

Integrating Spring MVC with Hibernate Annotation-Based Validation

In this article, I would like to demonstrate how to integrate Spring MVC, Spring bean validation framework and hibernate validator using annotations. The Hibernate Validator project is implementation of JSR 303 – Bean Validation standard, which defines a metadata model and API for JavaBean validation. For the the purpose of this example, I used Spring Framework v3.0.5 and Hibernate Validator v4.1.0.

What I like about Spring + Hibernate validation, is that this combination eliminates the need to use validator classes in controllers for bean validation. In other words, less code, less classes, everything looks much cleaner.

I am not going to talk about how to build web application from scratch using Spring MVC. I assume that you already have something working in place. I am just going to show the important bits needed, in order to plug hibernate validation in to your code:

1. Define two following beans in your application context XML in your WEB-INF directory:

<bean id="validator"
class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>

The basic configuration above will trigger JSR-303 to initialize using its default bootstrap mechanism. A JSR-303 provider, such as Hibernate Validator, is expected to be present in the classpath and will be detected automatically.

<bean id="messageSource"
     class="org.springframework.context.support.ResourceBundleMessageSource">
	<property name="basename" value="/WEB-INF/message-resources.bundle" />
</bean>

The bean above knows how to access resource bundles using specified basenames.

2. Create resource bundle (in this example it is “message-resources.bundle”) under WEB-INF. The resource bundle is where you should define your validation messages that the end user sees if his form submission fails validation. Please note that the bundle does not have to be at the root of WEB-INF, it can be placed also in a sub-directory of WEB-INF. The format for validation messages in your bundle should be as follows:

Annotation.bean-variable-name.bean-propery=validation error message.

For example:

NotBlank.someFormName.name=Name must not be blank,
Size.someFormName.name=Name must be less than or equal to {1} characters.
NotBlank.someFormName.street=Street name should not be blank. Please enter a value
NotEmpty.someFormName.selectedItem=Item selection is required

The example above describes four different validation messages for different validation rules. In case of a particular validation rule disobeyed, its respective validation message will be found based on the validation annotation, bean name and bean property name.

3. In your controller, in the method that validates bean from the POST request, annotate your bean with annotation @Valid. For example:

@RequestMapping(value = "/update.html", method = RequestMethod.POST)
 public String update (    @ModelAttribute("someFormName")
 @Valid SomeForm someFormName,
 BindingResult result,
 Model model)
 {

 if(result.hasErrors()) {
 // Return view name
 }

 // Do stuff

 // Return view name
 }

The @Valid annotation is part of the standard JSR 303 – Bean Validation API, and is not a Spring-specific construct. The Hibernate Validator instance invoked when a @Valid method argument is encountered.

Very important: your bean variable name in your controller method (in this case its “someFormName“) must match the bean variable name in your validation message resource bundle.

4. Annotate your bean member variables with annotations that tell Hibernate Validator what should be validated and what are the validation rules:

public final class SomeForm {

 @NotBlank
 @Size(min=0,max=20)
 private String name;

 @NotBlank
 private String street;

 @NotEmpty
 private String selectedItem;

 // Getters

 // Setters
}

As you can see from the above bean, the three fields that should be validated are annotated with @NotBlank, @NotEmpty and @Size. The validation rules are simple: the name property must not be blank nor longer than 20 characters, street property must not be blank, while selectedItem must not be empty.

By the way, you can have more complicated validation rules in place using annotations. It is possible to use expressions which decide whether validation rules should fire. Consider the following, which validate an email field:

@Email(applyIf="email is not blank")
@NotBlank
private String email;

You don’t want to display invalid email format error message when the filed is blank. Therefore that above expression in @Email annotation will have the rule fired only when the property is not blank. Expression can be especially very convenient when validating password fields:

@NotBlank
private String password;

@NotBlank(applyIf = "password is not blank")
@Expression(value = "confirmedPassword= password", applyIf = "password is not blank")
private String confirmedPassword;

Validation rules for confirmedPassword property will fire only when password field will not be blank.

That’s it :) If any rule(s) are disobeyed, the BindingResult result object will be populated with appropriate error messages, loaded from your message bundle. The error messages then can be displayed in your JSP using Spring tag:

<spring:hasBindErrors name="someFormName">
	<c:forEach items="${errors.allErrors}" var="error">
		<spring:message message="${error}"/>
	</c:forEach>
</spring:hasBindErrors>

And that is it! Feel free to post a comment if you run into problems and I iwll try to help you the best I can :)

Cheat Sheet for Selecting Map/List/Set in Java

I have prepared a cheat sheet that can help to select appropriate Map, Set or List implementation when required. Java API has many implementations of interfaces mentioned, and it is not always clear which implementation should be used in a particular scenario. The cheat sheet comes in the form of a flow chart, which makes it easy to follow and understand.

The idea was inspired by Sergiy Kovalchuk. Sergiy made a flow chart using the most commonly used collections. I tried to take it one step further and make it much more thorough.  Please do let me know if anything needs to be corrected. I hope this can help developers out there to choose the right collection for the right job.

Cheat sheet for selecting appropriate set/list/map in Java

Click on the image to load it in a new window

Inspired by Sergiy Kovalchuk

How To Define a Spring Bean With Generics Parameter

At the time when this article was written, the Spring framework does not allow to define beans in application context xml file using parameterized classes. The reason for that is that generics parameters are compiler information, and not run-time. Compiler information is something that Spring does not care about. For example, the following (or something similar) will NOT work:

<bean id="someClass" class="asia.javabeans.SomeClass<asia.javabeans.Blah>"  />

Sometimes, this restriction can create a problem if you have a parameterized class that has to be loaded by Spring. As a workaround, create an empty child class that extends your parameterized class, and then use that class’s canonical name as your bean definition. Consider the following parameterized parent and the extending child classes:

public class SomeParent<Blah> {

}

public class Child extends SomeParent<Blah> {
   // Just an empty class
}

and your Spring definition can now look like this:

<bean id="childClass" class="asia.javabeans.Child" />

The down side here is that you get stuck with an empty class, but at least you can have your bean definition in your application context xml file.

Inheritance and Generics with Abstract Data Types

In this article, I want to demonstrate a simple inheritance example that uses generics.  The abstract parent class is generic in the type, and it defines an abstract method that accepts as a method parameter the generic data type.

The generic data type used by the extending child in the implementation of the abstract method. This example is going to discuss the benefit of this approach.

Consider the following parent class:

public abstract class Parent<T> {
    protected abstract void process(T data);
}

Consider the following two child classes that extend the parent:

public class Child extends Parent<SomeClass> {
    @Override
    public void process(SomeClass data) {
        // Do stuff
    }
}
public class AnotherChild extends Parent<OtherClass> {
    @Override
    public void process(OtherClass data) {
        // Do stuff
    }
}

You can clearly see how this approach creates flexibility when multiple child classes require different data type parameters when implementing the abstract method. Because of the generic type setting in the abstract method, any data type can be passed to the child. This approach can be particularly useful when implementing a strategy design pattern.

Making Instance Variables Thread Safe

One of the ways to achieve thread safety when creating instance variables is to make a use of ThreadLocal class.  When instance variable is wrapped in ThreadLocal, each thread accessing the variable has its own independent copy of the variable.

An even better approach is to wrap the instance variable in SoftReference, which can eliminate the risk if getting OutOfMemoryError if there is a need to keep a an object in memory for a long period of time, for example when implementing caching mechanism. The garbage collector will only collect softly referenced objects when it decides that memory is low enough to warrant it

Consider the following snippet:

public class ThreadSafeExample {

 private static final ThreadLocal<SoftReference<List<SomeObject>>> trhLocal =
                                new ThreadLocal<SoftReference<List<SomeObject>>>();
 .
 .
    public static List<SomeObject> getSafeList() {

      // Get the value of the current thread's copy of this thread-local variable
      SoftReference<List<SomeObject>> reference = trhLocal.get();

      if (reference != null)  {
         // Get this reference object's referent
         List<SomeObject> safeList = reference.get();

            if (safeList != null)  {
                 return safeList;
            }
       }

       // Ok, so we did not have previously anything,
       // lets create thread-local variable
       List<SomeObject> safeList = new LinkedList<SomeObject>();
       reference = new SoftReference<List<SomeObject>>(safeList);
       trhLocal.set(reference);

     return safeList;
   }
}

What happens in the above example is, when getSafeList() is called, the thread’s list is assigned the first time it invokes getSafeList(), which causes invocation of  trhLocal.get().  If get() does not return anything, a new copy of the instance variable is created and set to the ThreadLocal instance. Each thread holds an implicit reference to its copy of a thread-local variable as long as the thread is alive and the ThreadLocal instance is accessible. This approach does not require  synchronization, which can create thread contention, and provides much faster access to the variable than via synchronization.

Off course one should consider whether ThreadLocal is really needed. Normally, a good candidates for object re-use via thread local are objects that are frequently accessed by a given thread and are non-trivial to construct. Another scenario for making use of ThreadLocal, would be when it is not really practical to extend Thread class (for example creating servlets) and thread safety is needed.

Convert XML into POJO using HierarchicalStreamReader

In this example I would like to show how unmarshall XML into a POJO using HierarchicalStreamReader. I will introduce how to use  XStream and a custom XML-to-POJO converter, describe a case study and develop an application to show the solution.

Purchase History Example
Consider the following XML. It represents represents a purchase history of a customer, that has purchased different items during a week:

<PURCHASE>
	<ITEM>
		<SUBITEM>
			<CODE>PDCT-001</CODE>
			<NAME>Product-1</NAME>
			<DAY5>1.75</DAY5>
			<TOTAL>1.75</TOTAL>
		</SUBITEM>
		<SUBITEM>
			<CODE>PDCT-002</CODE>
			<NAME>Product-2</NAME>
			<DAY7>1.00</DAY7>
			<DAY6>1.75</DAY6>
			<TOTAL>2.75</TOTAL>
		</SUBITEM>
		<SUBITEM>
			<CODE>PDCT-003</CODE>
			<NAME>Product-3</NAME>
			<DAY7>4.50</DAY7>
			<DAY6>2.00</DAY6>
			<DAY5>3.00</DAY5>
			<DAY4>2.25</DAY4>
			<TOTAL>11.75</TOTAL>
		</SUBITEM>
		<SUBITEM>
			<CODE>PDCT-004</CODE>
			<NAME>Product-4</NAME>
			<DAY7>3.50</DAY7>
			<DAY6>3.75</DAY6>
			<DAY5>2.75</DAY5>
			<DAY1>3.75</DAY1>
			<TOTAL>13.75</TOTAL>
		</SUBITEM>
		<REFERENCE>9571-EDGDFG-DGSNJE-1837</REFERENCE>
		<GRANDTOTAL>30</GRANDTOTAL>
	</ITEM>
</PURCHASE>

To unmarshall the XML, I created three POJOs to represent the hierarchy of XML elements. The domain objects Purchase, Item and SubItem are involved.  The Purchase  has an Item, that has a collection of SubItem objects. My customer XML converter will transform customer’s purchase history from XML into a domain model using the POJOs.

I am not going to describe the full structure of the POJOs here, as I want to concentrate on talking about the XML converter . The source code as Eclipse project is attached to the current article, so you can download it.

I use XStream, which is a simple open-source Java library for serialize objects to and from XML. The following is the unit test case code snippet that show how I register my custom converter that is used for XML unmarshalling:

XStream xstream = new XStream(new DomDriver());
xstream.alias("PURCHASE", Purchase.class);
xstream.registerConverter(new PurchaseConverter());
Purchase purchase = (Purchase) xstream.fromXML(xmlContent);

I created an alias for Purchase that matches XML root element and registered my custom converter. The converter is a specific converter that knows how to handle this particular XML example, so it is not a generic solution. The converter code as follows:

package asia.javabeans.streamreader.util;

import asia.javabeans.streamreader.domain.Purchase;
import asia.javabeans.streamreader.domain.SubItem;

import com.thoughtworks.xstream.converters.Converter;
import com.thoughtworks.xstream.converters.MarshallingContext;
import com.thoughtworks.xstream.converters.UnmarshallingContext;
import com.thoughtworks.xstream.io.HierarchicalStreamReader;
import com.thoughtworks.xstream.io.HierarchicalStreamWriter;

/**
 * Current class represents converter for a Purchase XML.
 *
 * @author alexander.zagniotov
 *
 */
final public class PurchaseConverter implements Converter {

	private static final int NUM_OF_DAYS = 7;

	public void marshal(Object value, HierarchicalStreamWriter writer,
			MarshallingContext context) {
	}

	public Object unmarshal(HierarchicalStreamReader reader,
			UnmarshallingContext context) {

		Purchase purchase = new Purchase();

                //while there are unread XML element children and the reader has not reached the closing PURCHASE element
		while (!(reader.getNodeName().equals(XmlElements.PURCHASE) && !reader
				.hasMoreChildren())) {

			if (reader.hasMoreChildren()) {
				reader.moveDown(); // Move down to ITEM element

				// Process child SUBITEM elements of the parent ITEM
				if (reader.getNodeName().equals(XmlElements.ITEM)) {
					iterateThroughItemSubitems(reader, XmlElements.ITEM,
							XmlElements.SUBITEM, purchase);
				}
			}
                        //store value of REFERENCE element in a POJO
			if (reader.getNodeName().equals(XmlElements.REFERENCE)) {
				purchase.setReference(reader.getValue());
			}

			reader.moveUp(); // Move back up to PURCHASE element
		}

		return purchase;
	}

	private Purchase iterateThroughItemSubitems(
			HierarchicalStreamReader reader, String parentNameName,
			String childNodeName, Purchase purchase) {
		boolean hasSubitemNodes = true;

		while (reader.getNodeName().equals(parentNameName) && hasSubitemNodes) {
			reader.moveDown(); // Move down to SUBITEM element

			// We have SUBITEM element that we can read
			if (reader.getNodeName().equals(childNodeName)) {
				purchase = iterateThroughSubitemChildren(reader, childNodeName,
						purchase);
			} else { // No more children SUBITEM elements to read
				break;
			}

			reader.moveUp(); // Move back up to parent ITEM element
			continue;
		}

		return purchase;
	}

	private Purchase iterateThroughSubitemChildren(
			HierarchicalStreamReader reader, String nodeName, Purchase purchase) {
		boolean hasChildrenNodes = true;

		SubItem subItem = new SubItem();

		while (reader.getNodeName().equals(nodeName) && hasChildrenNodes) {
			// Move down to the children of current SUBITEM element
			reader.moveDown();

			if (reader.getNodeName().equals(XmlElements.CODE)) {
				String subItemCode = reader.getValue();
				subItem.setCode(subItemCode);
				reader.moveUp(); // Move back up to parent SUBITEM
				continue;
			}

			if (reader.getNodeName().equals(XmlElements.NAME)) {
				String subItemName = reader.getValue();
				subItem.setName(subItemName);
				reader.moveUp(); // Move back up to parent SUBITEM
				continue;
			}

			if (reader.getNodeName().startsWith(XmlElements.DAY)) {

				for (int i = 1; i <= NUM_OF_DAYS; i++) {
					String xmlDay = XmlElements.DAY + i;

					if (reader.getNodeName().equals(xmlDay)) {

						double hours = Double.parseDouble(reader.getValue());
						subItem.addToDailyHours(xmlDay, hours);
						purchase.addToGrandTotal(hours);
						break;
					}
				}

				reader.moveUp(); // Move back up to parent SUBITEM
				continue;
			}

			if (reader.getNodeName().equals(XmlElements.TOTAL)) {
				hasChildrenNodes = false; // This is the last child of parent SUBITEM

				String itemTotalStr = reader.getValue();
				subItem.setItemTotal(Double.parseDouble(itemTotalStr));
				purchase.getItem().addSubItem(subItem);
				reader.moveUp(); // Move back up to parent SUBITEM
				continue;
			}
		}
		return purchase;
	}

	@SuppressWarnings("unchecked")
	public boolean canConvert(Class clazz) {
		return clazz.equals(Purchase.class);
	}

}

As you can see, the key to operate a stream reader is to move it down to a child element for reading and back up to a parent element. Each time I move the reader down, it moves to an element that has not being read yet.

Conclusion

I presented a simple example where I show how to unmarshall XML into Java POJOs using HierarchicalStreamReader and XStream. The source code is attached.

I hope this tutorial was helpful to some of you,
Regards