Posts Tagged java

Mockarro changes name to Komarro, Komarro&Mockito

As Mockarro was not the prettiest name it has been changed to Komarro. I also cut out the Injection Point class from the SPI so that API stays as minimal as possible. According to the old saying: it’s much easier to add features to an API when they are demanded, than to remove them when it turns out they should not be there. During the last review I also realized that a possibility o defining a custom injection strategy has to be more flexible than it was.

I also created another example of ‘Komarro with Mockito’ usage.

Currently Komarro offers a possibility of defining indirect inputs to a tested method. Sometimes however, it is necessary to verify the indirect output parameters or to verify that an interaction with a collaborator took place.
As Komarro is built upon Mockito they play together quite smoothly.

Let’s consider a local Pizza delivery service. In the example below you can see both the elements of Komarro and Mockito APIs. The interaction verification will be done on the methods of the OrderRepository. That is why it is annotated by the Mockito @Mock annotation. And then initialized using the MockitoAnnotations.initMocks(this) method.
Also it is important to notice that the mocks created by Mockito can be passed to Komarro’s instanceForTesting initialization method. Here, the MockitoMockDescriptionCreator.annotatedMocks convenience method is used to automatically detect the mocks marked with the @Mock annotation.

	@Mock
	private OrderRepository orderRepository;

	private OrderService orderService;

	@Before
	public void init() {
		initMocks(this);

		orderService = instanceForTesting(OrderService.class,
				annotatedMocks(this));
	}

Then we are set and ready to write the actual test method:

	@Test
	public void testPlaceOrderSavesOrder() {
		// given
		given(Pizza.class).isRequested().thenReturn(new Pizza("Margharita"));
		given(Order.class).isRequested().thenReturn(newOrderWithId(17L));

		// when
		long orderId = orderService.placeOrder("margharita", new Address(
				"Embarcadero Rd 123", "Isla Vista", "93117"));

		// then
		verify(orderRepository).save(any(Order.class));
		assertThat(orderId).isEqualTo(17L);
	}

Note that the method uses the Komarro’s idiom to define the behavior of the collaborators and Mockito’s verify method to verify the interaction has taken place.
Komarro can be complemented with Mockito’s functionality every time it is necessary. All the verifications have to be done by Mockito, as Komarro does not provide any way to do this yet. But also, if it is happens that Komarro style definition does not provide a good definition of the indirect inputs, Mockito should be used.

The method under test could look like this:

	@Inject
	private OrderRepository orderRepository;

	@Inject
	private PizzaService pizzaService;

	public long placeOrder(String pizzaName, Address address) {
		Pizza pizza = pizzaService.getByName();

		if (pizza != null) {
			Order order = new Order();
			order.setAddress(address);
			order.setPizza(pizza);

			Order newOrder = orderRepository.save(order);

			return newOrder.getId();
		} else {
			throw new IllegalArgumentException("The pizza " + pizzaName
					+ " does not exist in the menu card");
		}
	}

The source code of the examples posted here (and some more tests) can be found at github: https://github.com/marekdec/komarro-example-pizza-shop. The important phases of the development have been tagged.

Advertisements

, , ,

5 Comments

Mockarro TDD example

Since the day I came up with  Mockarro I find it very hard to evaluate clearly its usefulness. I guess it’s always pretty hard to make a clear judgement on an idea when the border between its advantages and disadvantages is fuzzy. It’s probably even harder if the idea is yours.

Anyhow, I recently decided to bring Mockarro closer to its first release and to expose it to the outer world.

It is important to remember that Mockarro provides a way of defining the indirect inputs to the tested method. It trades the specification of ‘how’ the indirect inputs are obtained for ‘what’ the indirect inputs are.

Let’s start with a simple TDD example. We are going to create a part simple application that searches the database of planets that are possibly inhabitable. The whole application is supposed to be created in a top-down manner. We will focus first on finding a planet whose radius is most similar to the Earth’s mean radius.

	@Test
	public void retrievePlanetWithRadiusMostSimilarToEarthsTest() {
		// given
		Planet earth = planet("earth", 6371);
		given(Planet.class).isRequested().thenReturn(earth);

		given(new TypeLiteral<List<Planet>>() {}).isRequested().thenReturn(
				asList(earth, planet("Mars", 3396), planet("Tatooine", 55000),
						planet("Arrakis", 10123), planet("Solaris", 12700)));

		// when
		Planet planet = planetService
				.retrievePlanetWithRadiusMostSimilarToEarths();

		// then
		assertThat(planet).isNotNull().isNotSameAs(earth);
		assertThat(planet.getName()).isEqualTo("Mars");
	}

The code above defines the expected behavior of the retrievePlanetWithRadiusMostSimilarToEarthsTest method. The fixture set-up section (the given section) defines the indirect inputs to the method under test. As opposed to the standard Mocking frameworks like Mockito or !EasyMock, Mockarro does not couple the test method to collaborators within the given section. It does not define how the indirect inputs will be provided. It does, on the other hand, clearly specify what the indirect inputs the method under test are.
The method that is going to be implemented, briefly, will be given a list of all planets in the database and an instance of the planet Earth. It is required to find a planet whose radius is most similar Earth’s radius, but at the same time it is required not to return the Earth as the result.

A possible implementation of the method could use a PlanetRepository to get both: the instance of a planet Earth and a list of all planets available for the application.

	@Inject
	private PlanetRepository planetRepository;

	public Planet retrievePlanetWithRadiusMostSimilarToEarths() {
		Planet earth = planetRepository.getByName("earth");

		if (earth != null) {
			double earthRadius = earth.getKilometersOfRadius();

			Planet mostSimilarPlanet = null;
			double smallestDiff = Double.POSITIVE_INFINITY;
			for (Planet planet : planetRepository.getAllPlanets()) {
				if (planet != earth) {

					double diff = Math.abs(planet.getKilometersOfRadius()
							- earthRadius);
					if (diff < smallestDiff) {
						smallestDiff = diff;
						mostSimilarPlanet = planet;
					}
				}
			}
			return mostSimilarPlanet;
		} else {
			throw new IllegalStateException(
					"No earth in the planet repository");
		}
	}

Let’s assume that at some stage of the application life cycle a SolarSytemRepository is created. The Earth will be obtained directly from the new service. The input parameters will not change whatsoever.


	@Inject
	private PlanetRepository planetRepository;

	@Inject
	private SolarSystemService solarSystemService;

	public Planet retrievePlanetWithRadiusMostSimilarToEarths() {
		Planet earth = solarSystemService.getEarth();

		if (earth != null) {
			double earthRadius = earth.getKilometersOfRadius();

			Planet mostSimilarPlanet = null;
			double smallestDiff = Double.POSITIVE_INFINITY;
			for (Planet planet : planetRepository.getAllPlanets()) {
				if (planet != earth) {

					double diff = Math.abs(planet.getKilometersOfRadius()
							- earthRadius);
					if (diff < smallestDiff) {
						smallestDiff = diff;
						mostSimilarPlanet = planet;
					}
				}
			}
			return mostSimilarPlanet;
		} else {
			throw new IllegalStateException(
					"No earth in the planet repository");
		}
	}

This refactoring does not require the test method to be changed. The input parameters stayed the same (both direct and indirect). It has to be pointed out though, that the test method will have to be changed every time the set of the indirect input parameters is modified.

The source code of the examples in this post can be found at https://github.com/marekdec/planetary-system. The interesting stages of the development process have been tagged, navigate to https://github.com/marekdec/planetary-system/tags to find them.

, ,

4 Comments

‘Explicit interface per class’ antipattern

I recall, right after the lecture of the Gang of Four’s masterpiece on the design patterns, I suffered from this kind of Russell Crowe-John Nash syndrome: I started seeing patterns all over my code just as Russell-John did in the code cracking scene. Then, it took me some time to understand that no class of problems has a universal solution. The solutions to the problems have to be always based on the context the problem appears in.

I guess it happened to the majority of the developers that their initial enthusiasm about the design patterns resulted in some highly over-engineered pieces of code. But eventually all of us make their peace with the precooked solutions and we exactly know when to and when not to use them.

This surprisingly does not apply to some practices widely used within the Java EE ecosystem. Providing an explicit interface per each Java class is a notable example. By many it is considered to be a costless solution which brings only benefits and provokes no side effects. Worse, it’s often applied as a no-brainer that cannot be done wrong.

Why do people do that? This practice undoubtedly originates from the early Java Enterprise frameworks. The great inventions like Dependency Injection or Aspect Oriented Programming were possible thanks to the JDK proxies based on the existence of explicit interfaces. However, given the fact that every Java class implicitly defines its interface and given the improvements that were introduced to the Java world over the years, all modern frameworks have overcome this imperfection and nowadays they are capable of providing the same functionality with no explicit interfaces present in the classpath. Also, with the advent of the mocking frameworks (among them my favorite Mockito and PowerMock), class mocking is no longer a good reason for providing an explicit interface per class.

So why do people keep doing that? An explicit interface is an extremely powerful tool. It gives you a possibility to separate the implementation from the interface. In other words, you are able to decouple the essence of your application from the underlying technologies. Why would like to do this? Well, the technologies do get better, your client’s no-functional requirements may be volatile or  your management might change their mind on the technologies you use. You want to be prepared to adapt to new technologies easily. The problem is that it is not enough to extract an interface from a class using some one-click -IDE magic.This may be good enough for Spring so it creates the javassist proxies. However, if you want to take the real advantage of the interface separation, you have to design them with a big dose of care.

It is necessary to realize that providing any explicit interface does not guarantee you any flexibility when it comes to replacing the implementations. It is a common error in the Java webapps world that the explicit interfaces are build for specific implementations or worked out in the bottom-up manner: from existing implementations (often using some IDE helpers).
If you want to take advantage of the explicit interfaces you define in order to be able to replace the implementations easily, you have to have in mind that you design an API that has to be implementation agnostic.
To be more precise you define a special kind of API called  SPI that will be used by other clients of your module (or maybe you in some future) to build any implementation of the service described by the explicit interface . That is why the interfaces cannot leak anything from the originally proposed implementation. You have to have in mind that an SPI cannot be modified once it is published, it has to be done right in the first place. Getting it right has to cost time and effort. If you however never publish your modules and your team has the complete ownership of the whole application you should consider deferring creating the explicit interfaces until it is necessary.
Joshua Bloch cites the Rule of Threes by Will Tracz in this video where he claims it takes three implementations to get the SPI right (the whole video is certainly worth seeing, if you are interested in the SPI design – navigate to 16:30). In any case, one has to be very optimistic to trust that an interface extracted from a specific implementation (e.g. using IDE assistance) will be good for any other implementation.

Please see the following list of indicators that should warn you that you may be getting it wrong:

  1. Your Interface is tied to some implementation.
    This is probably the most dangerous issue and at the same time the easiest one to run into.
    Make sure following does not take place:

    • the interface or any of its methods contain the name of some technology used (e.g. JPAPersistentStore),
    • the parameters of any of the methods are coupled to the implementation (e.g. a Hibernate Criteria object as a parameter of a persistence service), this applies to the generic parameters too,
    • the return type of your method is coupled to the underlying implementation,
    • the Exception type reveals details of the implementation (e.g. a method that throws a JMSException).

    The naming issue may seem at first less important, though it is the name where everything starts. If you get it wrong in the first place it is very likely at some stage you will forget about the real purpose of the existence of the interface. It is more obvious with the rest o the bullets. What is important to remember is to take all parts o the methods signature into consideration. Still this may not be enough. Make sure that even if the interface declarations and the interface signature are not directly linked to any implementation, the purpose of the methods has to be implementation agnostic too. For example, if it happens that some implementation of a service has to be initiated and you want to delegate this responsibility to the client you have to think twice before publishing the init() method through the interface. Will all implementation need to be initiated?

    An excellent trick to get this done correctly is to create javadocs for all elements of your interface. If you manage not to mention anything about any possible implementation there, then you are probably good.

  2. The names of your implementations contain the Impl postfix or begin with the default word or contain any other keyword that does not describe the implementation.
    Names are important.  In the Java EE world, one of the best reasons for separating the interface from implementation is to separate the underlying technology from other modules of your application (to be able to replace it easily in the future). If this is your motivation, should be able to come up with a good, descriptive name for your implementation. If you cannot do that you may be pretty sure your default implementation will stay the only one forever. Then you gain nothing providing the explicit interfaces for your implementation. You do, on the other hand, increase the complexity of your architecture (and it does not matter how smart your IDE is, you simply duplicate the artifacts with no good reason).

Martin Fowler in his book named Patterns of Enterprise Application Architecture (released in 2002) identified a pattern called Separated Interface (in the Chapter 18 he defines exactly when to apply it). He also states following:
I come across many developers who have separate interfaces for every class they write. I think this is excessive, especially for application development.” and “I recommend using a separate interface only if you want to break a dependency or you want to have multiple independent implementations. If you put the interface and implementation together and need to separate them later, this is a simple refactoring that can be delayed until you need to do it.”
These words are nearly 10 years old, however it looks like Martin would still come across such developers. What’s probably worse is that now they have much less reasons to do so.
The general message of this blog entry is that providing explicit interfaces for services in a standard Java web application in no longer easily justified, it increases the complexity and if costs time if it supposed to bring benefits. Spring, EJB, the set of unit tests can do without them perfectly. If you provide the explicit interfaces in order to decouple your application business logic from the underlying technologies, you have to do it extremely carefully. If you fail to make it implementation agnostic you are wasting your time and the lines of code – you effectively fail to decouple the application from the technology.
Moreover if you or your team have a full control of the code and/or the changes to the technologies you use are unlikely, your inner self should raise a little YAGNI flag once you start writing the ‘just-in-case’ explicit interfaces.
And of course, all the decisions have to be taken consciously with a reasonable dose of skepticism. No solution is good if the context of the problem has not been taken into consideration.


See more:

  1. How To Design A Good API and Why it Matters – the aforementioned presentation by Joshua Bloch,
  2. Service s = new ServiceImpl() – Why You Are Doing That?– a blog post by Adam Bien,
  3. Java Interfaces Methodology: Should every class implement an interface? – a question on a similar topic raised on stackoverflow.

, , , , , , ,

Leave a comment

%d bloggers like this: