Object Oriented Frameworks: Concepts, White Box and Black Box Examples

When teaching Object Oriented Frameworks (usually in Advanced Object Oriented Programming courses) there is a challenge for students to understand their nature, differences with libraries and the difference between white box frameworks vs black box frameworks.

In this post I will start talking very briefly about general concepts of frameworks. Then I will implement a pretty simple white box framework as an example and after that I will transform the white box framework into a black box framework.

Frameworks Definition

The key driver that made to evolve software development into the creation and use of Frameworks was, is and will be code reuse.

Before frameworks appeared, the only software constructions used to obtain code reuse were library of functions, for procedural / imperative programming languages and library of classes for object oriented languages (other ways you can find out there are modules in Modula, packages in Ada and/or clusters in CLU). Libraries in general allows you to reuse only source code and for an specific task.

Frameworks came into the world of software development to provide design and source code reuse. Frameworks provides a greater level of reuse. They define a design and the implementation of an specific class of software application allowing the users, which are developers, to use it as it is (with some configuration like connection strings and i18n for instance), or extend it to adapt it to their specific needs.

To give a definition of what a framework is, I will take the one from the GOF book: “A framework is a set of cooperating classes that make up a reusable design for a specific class of software”. A framework define the design of our application, the key classes, responsibilities and collaborations. It will also determine the control flow of our application, where the execution always start in the framework’s code.

How Frameworks are different from Libraries?

When you use a software library, the execution start in the application’s code and is the application who call the library to use it. With frameworks, the execution start in the framework’s code, and is the framework who call application methods. This is called Inversion of Control and is one of the key concepts for frameworks and a key distinction between frameworks and libraries.

How to provide extension points and how they are achieved?

There are no new or magic mechanisms in how the frameworks provides extension points, also called hook methods. They are available thanks to the dynamic binding concept, well known from the very beginnings of Object Oriented Programming. Frameworks are able to make calls to object methods which can be replaced or interchanged at runtime with developer’s code (users of the framework) thanks to the dynamic binding mechanism.

Within the flow of collaborations implemented in a framework, there will exists documented extension points or hook methods that users can take advantage of to inject their own behaviour. This is the way of how you can extend a framework.

Why White Box or Black box Frameworks?

The way in which the framework provides the extensibility make the framework be of type white box or black box. A framework that provides extensibility by using inheritance are white box. Which means that if you need to customize a framework and to do that you have to inherit from a framework’s class and override a method then that is white box.

A framework that provides extensibility by composing and injecting objects to combine different collaborations are black box. Which means that if you need to customize a framework and to do that you have to implement an specific interface and somehow the framework will pick your class and call it at the extension points that was documented, then that is a black box.

White Box Framework Example

Lets imagine that in the Java programming language, printing a message in a dialog box is very hard. So, in order to make a software that need to do that you need to use a framework to make your life easier. Here we will develop the framework using white box design and then we will demonstrate how a developer can use our framework.

Below you will see our PrintOnScreen framework, including some comments to explain how is used.

package ar.cpfw.whitebox;

import javax.swing.JFrame;
import javax.swing.JOptionPane;

/* This framework allows you to show text on a dialog box.
 * 
 * To use it, you have to extends from the PrintOnScreen class 
 * and implement their abstract method.
 * 
 * The framework provides the PrintOnScreen#print method which 
 * makes the magic.
 * */
public abstract class PrintOnScreen {

	public void print() {
		JFrame frame = new JFrame();
		JOptionPane.showMessageDialog(frame, textToShow());
		frame.dispose();
	}

	protected abstract String textToShow();
}

Now, lets extends the framework:

package ar.cpfw.utilization;

import ar.cpfw.whitebox.PrintOnScreen;

public class MyApplication extends PrintOnScreen {

	@Override
	protected String textToShow() {
		return "printing this text on "
				+ "screen using PrintOnScreen "
				+ "white Box Framework";
	}
}

And finally, instantiate it, and run it:

package ar.cpfw.utilization;

public class Main {
	public static void main(String args[]) {
		MyApplication m = new MyApplication();
		m.print();
	}
}

Some conceptual points to highlight about the PrintOnScreen framework and their usage:

  • Note that the framework itself is in a different package that the use of the framework. That is what will normally happen in real life if you use a framework developed by other developer. Even if you develop the framework and use it, it is a good practice to separate the classes in packages (modules).

  • The extension point (hook) is an abstract method. To use and extend the framework I have to inherit from the framework class. That is a key characteristic of a white box framework.

  • It use inversion of control, the framework method PrintOnScrenn#print calls our method MyApplication#textToShow.

  • The framework use the Template Method pattern, which is mainly the pattern used to create white box frameworks.

  • Finally, note that as a developer I would be able to override the PrintOnScreen#print method as is public. That method was not developed for that intention, that is why framework documentation is important for clarifying these things. However, as a developer I might make this mistake. This is a clear drawback of frameworks based on inheritance. Java (but not all Object Oriented languages) provides the final keyword to help framework developers to flag which methods cannot be overridden. If we put the final keyword to the PrintOnScreen#print method, that would be best.

Black Box Framework Example

Here we are going to transform our white box framework into a black box one. Find below the framework’s classes:

package ar.cpfw.blackbox;

import javax.swing.JFrame;
import javax.swing.JOptionPane;

/* This framework allows you to show text on a dialog box.
 * 
 * To use it, you have to implement the interface TextToShow. 
 * Then, create an instance of the class PrintOnScreen passing
 * your implementation of TextToShow as a constructor param. 
 * 
 * The framework provides the PrintOnScreen#print method which 
 * makes the magic.
 * */
public final class PrintOnScreen {

	TextToShow textToShow;
	
	public PrintOnScreen(TextToShow text) {
		this.textToShow = text;
	}
	
	public void print() {
		JFrame frame = new JFrame();
		JOptionPane.showMessageDialog(frame, 
																			textToShow.text());
		frame.dispose();
	}
}
package ar.cpfw.blackbox;

public interface TextToShow {
	String text();
}

Some points to highlight about the changes made:

  • We made the PrintOnScreen class final (we don’t want our users to inherit from it).

  • Then, we created an interface called TextToShow, which is the extension point. And compose it as a private member of the PrintOnScreen class (line 16).

  • After that, we changed the PrintOnScreen#print method to delegate on the TextToShow#text method (line 25).

  • And finally, we created a constructor method on the PrintOnScreen class that accept a TextToShow instance as a parameter (line 18-20). This is the way our users will inject their instance.

In the black box example, words like compose and delegate are now the important ones over inheritance from the white box example.

We have only left to show how to use our black box framework, let follow their instructions. First we implement the TextToShow interface:

package ar.cpfw.utilization;

import ar.cpfw.blackbox.TextToShow;

public class MyTextToShow implements TextToShow {

	@Override
	public String text() {
		return "printing this text on "
				+ "screen using PrintOnScreen "
				+ "black Box Framework";
	}
}

And finally,

package ar.cpfw.utilization;

import ar.cpfw.blackbox.PrintOnScreen;

public class Main {

	public static void main(String args[]) {
		PrintOnScreen m = new PrintOnScreen(new MyTextToShow());
		m.print();
	}
}

That completed our migration from white box to black box and hopefully illustrate the differences.

JQuery: Callback Functions

JQuery is a JavaScript Library, not a framework. However, using it you will notice that provides mechanisms for injecting your own behaviour that will be called by JQuery, hence we have inversion of control. In the JavaScript world, this mechanism or extension point is called callback functions.

To finish this post, I wanted to show how in Web client side development libraries like JQuery, you will find the framework’s concepts described here.

In the html/JavaScript below you will see the use of hide() and show() JQuery functions. Both functions provides the ability to pass as a parameter a callback function, see the lines 8 and 11 below.

<!DOCTYPE html>
<html>
<head>
<script src="https://aserver.com/jquery.min.js"></script>
<script>
$(document).ready(function(){
    $("#hide").click(function(){
        $("p").hide(myFunction);
    });
    $("#show").click(function(){
        $("p").show(myFunction);
    });
});
function myFunction() {
    console.log("This was called by the JQuery library");
}
</script>
</head>
<body>

<p>If you click on the "Hide" button, I will disappear.</p>

<button id="hide">Hide</button>
<button id="show">Show</button>

</body>
</html>

When a user clicks on the Hide or Show button, after (this is clearly specified in the JQuery documentation) hide or show the paragraph p, it will call myFunction, which drops the “This was called by the JQuery library” message in the console.

Posted in Design & Architecture, Frameworks, Object Oriented Programming Tagged with: ,

Hibernate/JPA – Transparent Persistence II

I wanted to add another nice example about Transparent Persistence (explained in a previous post), to insist on the beauty of this. This time, adding JPA mappings in the classes that represent the domain model of my application. Additionally, I will mention how Hibernate/JPA behaves in this case, and how to change that if necessary, to ensure your application perform smoothly.

Suppose I’m implementing an application that allows you to create different competitions and let people (participants) enrol to them. Participants are allowed to enrol the competition only during a period of time, defined within the competition. It will also need validate if the participant is not already enrolled.

As I have been saying in my other post, implement your business requirements inside your domain model, don’t be tempted to put business logic inside Facades, DAOs, Repositories, Controllers, etc. This temptation occurs specially once you have to persist your objects. Think in a way that your memory is persistent, implement your requirements in the domain model and then use Transparent Persistent. Only when the ORM tool you are using does not provide the features to make the transparent persistence perform smoothly, then there is when you are forced to make changes to your objects.

So, lets implement this in the domain model. The domain model with JPA annotations looks like the one below:

@Entity
public class Competition {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;
	@Column
	private String name;
	@Column
	private LocalDate startDate;
	@Column
	private LocalDate endDate;

	@OneToMany(mappedBy = "competition")
	private Collection<Participant> participants
						= new ArrayList<>(); 	        
	//just for Hibernate
	protected Competition() { }

	public Competition(String name, LocalDate startDate, 
							LocalDate endDate) {
		this.name = name;
		this.startDate = startDate;
		this.endDate = endDate;
	}

	public void enrol(Participant p) {
		checkEnrolInPeriod();
		if (!this.participants.contains(p)) {
			participants.add(p);
			p.setCompetition(this);
		}
	}

	private void checkEnrolInPeriod() {
		LocalDate today = LocalDate.now();
		if (!(!today.isBefore(this.startDate) 
				&& !today.isAfter(this.endDate))) {
			throw new RuntimeException("You can't "
							+ "enrol outside the period...");
		}
	}
}

@Entity
public class Participant {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	private String name;
	
	@ManyToOne
	@JoinColumn(name = "competition_id")
	private Competition competition; 
	
	//just for Hibernate
	protected Participant() { }
	
	public Participant(String name) {
		this.name = name;
	}
    
	...
}

Now, in the client code of my domain model, in this case, a Facade that is used by my Front-End, we wrap in a persistent context the following sentences:

	public void enrol(idCompetition, idParticipant) {
		//start persistence context

		Competition aCompetition = // retrieving from the storage by Id
		Participant aParticipant = // retrieving from the storage by Id
		aCompetition.enrol(aParticipant);

		//close persistence context
	}

What happen if we execute the enrol(idCompetition, idParticipant) method ?

  • The first line will retrieve from the persistent storage the aCompetition instance, executing the following SQL statement:

        select
            id,
            competition_id,
            name,
        from
            Competition
        where
            id = idCompetition;
    

    Note that there is no retrieval at all from Participants, which means that the Competition#participants collections is not initialized. This is because by default in JPA the one-to-many relationship is lazy. Lazy means that only if you need somenthing from that collection, then at that point the collection will be initialized.

  • The second line will retrieve from the persistent storage the aParticipant instance, executing the following SQL statement:

        select 
            participan0_.id, 
            participan0_.competition_id, 
            participan0_.name,
            competitio1_.id,
            competitio1_.endDateForInscription,
            competitio1_.name,
            competitio1_.startDateForInscription
        from Participant participan0_ 
                left outer join Competition competitio1_ on   
                participan0_.competition_id = competitio1_.id 
        where participan0_.id = idParticipant;
    

    Note that there is a join with Competition due to in JPA the many-to-one relationship that exists here between Participant and Competition, is eager by default.

  • The third (and last) invoke the business method aCompetition.enrol(aParticipant). Looking at the code of that method:
    • The first sentence: checkEnrolInPeriod(); will check if aParticipant is on time to be enrolled in aCompetition. There is no SQL statement generated here as the instances loaded before has everything needed to execute this check.
    • After that, the sentence this.participants.contains(p) will make Hibernate/JPA to initialize the participants collection. This will produce a SQL statement like the following:
    •     select
              name,        
              id,
              competition_id
          from
              Participant
          where
              competition_id = idCompetition;
      

      After executing that SQL and initializing the collection, the Collection#contains is executed. This is normal Java behaviour, it will compare instances using the equals method, and with that will decide if aParticipant is already enrolled or not.

    • Following that, if the condition evaluates to true, then it will add aParticipant to the participants collection. Generating the following SQL statment
          update 
              Participant
          set 
              competition_id=?, 
          where 
              id = idParticipant;
      

      Note that the SQL statement is generating the relationship between Competition and Participant in the relational model.

It is important to highlight, one more time, that our Competition#enrol(Participant) method has been written without thinking in the underlying persistent storage (in this case a relational model). And in a Transparent way, the persistent storage has been modified to accommodate the changes in the objects that belongs to the domain model.

Performance Improvement

As showed before, the sentence this.participants.contains(p) is bringing to memory all the participants from the persistent storage, in order to compare if aParticipant is already enrolled or not. This works perfect for small collections, but for large collections might not work.

Hibernate/JPA provides an additional annotation for this case called Extra Lazy. The extra lazy mapping will produce that the methods Collection#size and Collection#contains won’t trigger the initialization. Lets make that addition to our class.

@Entity
public class Competition {
	...

	@OneToMany(mappedBy = "competition")
	@LazyCollection(LazyCollectionOption.EXTRA)
	private Collection<Participant> participants
						= new ArrayList<>(); 	        
	...

}

With this in place, our explanation above about what occurs when this.participants.contains(p) is invoked will change. Now, instead of initialize the collection (bring all the participants into memory), it will perform the next SQL statement to let the persistent storage to answer if aParticipant has been enrolled or not.

        select  
                1 
        from 
                Participant 
        where 
                competition_id = idCompetition and 
                id = idParticipant;

Looks good right?

This post presented another example or use case where you are allowed to develop Object Oriented software without having to break how you model your objects or without being forced to break your object model due to persistence. Enjoy Transparent Persistence.

Posted in Persistence Tagged with: , ,

Lambda Expressions in Java, a Concrete Example

Maybe you have read several posts on the web on how Lambda Expressions are used. Most of the ones I have read uses examples for filtering collections with the new Stream API of Java 8. Those examples are good but they are more focused on showing a fancy way of filtering a collection rather than on showing or highlight the code structures that now you don’t have to write, in this case, the for loops. Without Lambda Expressions, each time you need to filter data from a collection, you have to iterate the collection (repeating a for loop construction). That is not necessary any more.

In this post I will show a concrete example of removing duplicated code using Lambda Expressions. For the demonstration I will be using JPA (Java Persistence API), following the topics of my previous post.

I believe that showing how to use Lambda Expressions putting the focus on the removal of duplicated code will open your mind on the potential that they have.

Suppose I’m asked to write some code to do a simple save, update and retrieve of a specific Entity class, using JPA. To implement that, I will write a class called ADataAccessObject (just to name it somehow). Below you will find what I have written in my first development iteration, the make it work step.

public class ADataAccessObject {

	private EntityManagerFactory emf;

	public ADataAccessObject(EntityManagerFactory emf) {
		this.emf = emf;
	}

	public void save(AnEntity anEntity) {
		EntityManager em = this.emf.createEntityManager();
		EntityTransaction tx = null;
		try {
			tx = em.getTransaction();
			tx.begin();

			em.persist(anEntity);

			tx.commit();
		} catch (Exception e) {
			if (tx != null) {
				tx.rollback();
			}
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}

	public void update(long id, String aNewPropertyValue) {
		EntityManager em = this.emf.createEntityManager();
		EntityTransaction tx = null;
		try {
			tx = em.getTransaction();
			tx.begin();

			AnEntity anEntity = em.find(AnEntity.class, id);
			anEntity.setAProperty(aNewPropertyValue);

			tx.commit();
		} catch (Exception e) {
			if (tx != null) {
				tx.rollback();
			}
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}

	public AnEntity byId(long id) {
		EntityManager em = this.emf.createEntityManager();
		try {
			return em.find(AnEntity.class, id);
		} catch (Exception e) {
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}
}

Now lets write the client code that use the class above:

public class Main {
	public static void main(String arg[]) {
		EntityManagerFactory emf = null;
		try {
			emf = Persistence
					.createEntityManagerFactory("a-persistence-name");
			ADataAccessObject dao = new ADataAccessObject(emf);
			//store anEntity ...
			dao.store(new AnEntity("aValuForTheProperty"));
			//update anEntity ...
			dao.update(1l, "anotherValueForTheProperty");
			//retrieving ...
			AnEntity e = dao.byId(1l);
		} finally {
			emf.close();
		}
}

What does not look nice from the code above? As you might have noticed, each method seems to be pretty similar. The try/catch/finally block with the creation of the EntityManager, the Transaction#commit, Transaction#rollback and the EntityManager#close, all of these are duplicated.

To clarify a bit more, below are the sentences unique per method:

//from ADataAccessObject#store
em.persist(anEntity);

//from ADataAccessObject#update
AnEntity anEntity = em.find(AnEntity.class, id);
anEntity.setAProperty(aNewPropertyValue);

//from ADataAccessObject#byId
return em.find(AnEntity.class, id);

How can we remove that duplicated code? There are some options. You can use Dynamic Proxys or AspectJ. Or incorporate a framework like Spring to handle JPA Transactions for you. Do we have simpler approach? I don’t want to incorporate any framework, I would love the language itself provides the syntactical construction to do it.

What if the programming language allows you to pass a block of code as a method parameter? That sounds great, because I can create a private method in my ADataAccessObject class with the try/catch/finally structure and receive each unique block of sentences by parameter.

Before Java 8, this was possible using Anonymous Classes. Lets moving ahead with this approach then.

For implementing this approach we have to create an Interface to specify the signature of the block of code that we need to pass by parameter. Described next:

public interface ABlockOfCode {
	AnEntity execute(EntityManager em);
}

That Inteface above is the type of my block of code. Each block of code will respond to the execute method, it must receive the EntityManager by parameter and must return AnEntity.

Lets go through the second iteration of my code, the make it better step. I will refactor a bit my ADataAccessObject Class adding some anonymous classes to eliminate duplicated code.

public class ADataAccessObject {

	private EntityManagerFactory emf;

	public ADataAccessObject(EntityManagerFactory emf) {
		this.emf = emf;
	}

	public void store(AnEntity anEntity) {
		transactionExecute(new ABlockOfCode() {
			@Override
			public AnEntity execute(EntityManager em) {
				em.persist(anEntity);
				return null;
			}
		});
	}

	public void update(long id, String aNewPropertyValue) {
		transactionExecute(new ABlockOfCode() {
			@Override
			public AnEntity execute(EntityManager em) {
				AnEntity anEntity = em.find(AnEntity.class, id);
				anEntity.setAProperty(aNewPropertyValue);
				return null;
			}
		});
	}

	public AnEntity byId(long id) {
		return transactionExecute(new ABlockOfCode() {
			@Override
			public AnEntity execute(EntityManager em) {
				return em.find(AnEntity.class, id);			}
		});
	}

	private AnEntity transactionExecute(ABlockOfCode aBlockOfCode) {
		EntityManager em = this.emf.createEntityManager();
		EntityTransaction tx = null;
		try {
			tx = em.getTransaction();
			tx.begin();

			AnEntity a = aBlockOfCode.execute(em);

			tx.commit();
			return a;
		} catch (Exception e) {
			if (tx != null) {
				tx.rollback();
			}
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}
}

As you can see, I have created a private method called transactionExecute which expects as parameter an instance of ABlockOfCode. In each public method, I’m creating these instances, as anonymous classes, implementing the execute method of the ABlockOfCode with the sentences unique per method described before. Then, each method calls transactionExecute, passing these ABlockOfCode instances by parameter. Finally, note that inside the transactionExecute method, there is a call to the execute method of the ABlockOfCode instance, inside the try/catch/finally template.

Not bad right? Let’s do it now even better in my third development iteration. I’m going to replace the anonymous classes with Lambdas. In Java 8, Lambdas are a prettier way of writing anonymous classes (not the case for functional programming languages, but this is a different talk). They incorporate a syntactic sugar plus a type inference system, which make the code cleaner and easier to read.

The code below starts moving the transactionExecute private method to its own class.

public class TransactionTemplate {
	public EntityManagerFactory emf;

	public TransactionTemplate(EntityManagerFactory emf) {
		this.emf = emf;
	}

	public AnEntity execute(ABlockOfCode aBlockOfCode) {
		EntityManager em = this.emf.createEntityManager();
		EntityTransaction tx = null;
		try {
			tx = em.getTransaction();
			tx.begin();

			AnEntity returnValue = aBlockOfCode.execute(em);

			tx.commit();
			return returnValue;
		} catch (Exception e) {
			if (tx != null) {
				tx.rollback();
			}
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}
}

public class ADataAccessObject {

	private TransactionTemplate transaction;

	public ADataAccessObject(TransactionTemplate transaction) {
		this.transaction = transaction;
	}

	public void store(AnEntity anEntity) {
		transaction.execute(
			(em) -> { em.persist(anEntity);
								return null;
							});
	}

	public void update(long id, String aNewPropertyValue) {
		transaction.execute(
			(em) -> { AnEntity anEntity = em.find(AnEntity.class, id);
								anEntity.setAProperty(aNewPropertyValue);
								return null;
							});
	}

	public AnEntity byId(long id) {
		return transaction.execute(
			(em) -> {
								return em.find(AnEntity.class, id);
							});
	}
}

On the highlighted lines you will see the Lambda Expressions. A lambda expression, is composed of two parts, separated by the lexical token “->”: (parameters) -> { block of code }. There is no need to specify the type of the parameter in the lambda expression, it will be inferred from an interface, in this case, the ABlockOfCode. If you look at this interface you will note that each lambda expression receives an instance of the EntityManager as parameter, (em), and must return an instance of AnEntity.

As a final development iteration, I will make this more generic. My ABlockOfCode interface and TransactionTemplate class should support any object type, not only AnEntity. So next I will change the AnEntity type for a generic type T.

Starting with the ABlockOfCode interface:

public interface ABlockOfCode<T> {

	T execute(EntityManager em);
}

I have just replaced AnEntity with the generic type T, and I have declared that type T as a generic type, using the <T> syntax (on line 1).

Next, I will make the TransactionTemplate#execute method generic:

	public <T> T execute(ABlockOfCode<T> aBlockOfCode) {
		EntityManager em = this.emf.createEntityManager();
		EntityTransaction tx = null;
		try {
			tx = em.getTransaction();
			tx.begin();

			T returnValue = aBlockOfCode.execute(em);

			tx.commit();
			return returnValue;
		} catch (Exception e) {
			if (tx != null) {
				tx.rollback();
			}
			throw new RuntimeException(e);
		} finally {
			em.close();
		}
	}

On line 1, I’m declaring the generic type <T>, changing the signature of the method returning T and expecting ABlockOfCode<T> as parameter. Note also that the return type of the aBlockOfCode.execute(em) sentence, has change from AnEntity to T, on line 8.

With this last change we have made the TransactionTemplate#execute method generic to be used by any instance of ABlockOfCode that requires a JPA transaction context. The ADataAccessObject class does not need to change, because as I explained before, the Lambdas infer their type from the ABlockOfCode interface.

We just went through out some development iterations in order to remove duplicated code. This nature of the duplicated code shown here, is not able to be removed using simple refactoring techniques like extract method or extract class. It requires more powerful language feature to allow passing sentences, or blocks of code, by parameter. That was achieved using anonymous classes first and then with Lambda Expressions. And remember, don’t do refactoring iterations without test coverage.

Posted in Design & Architecture Tagged with: , ,

Hibernate/JPA – Inheritance and Polymorphic Asociations

This post is part of a series of post I will be written about Hibernate. In this one, I will be describing how Hibernate and JPA deals with inheritance and polymorphic associations.

I’m going to implement a very simple bank domain model to demonstrate how to persist an inheritance hierarchy and deal with polymorphic associations.

Let suppose the bank has clients and accounts. We have two kinds of accounts: SavingsAccount and CheckingAccount. In the SavingsAccount you can do extractions only if you have enough money while in the CheckingAccount you can do extractions until you reach an overdraft set by the bank. In both accounts you can deposit money.

To implement this, I’m going to create the following abstract class called BankAccount, with some common behaviour.

public abstract class BankAccount {

	protected float amount;

	public abstract float extract(float anAmount);

	public void deposit(float anAmount) {
		this.amount += anAmount;
	}

	public float getAmount() {
		return amount;
	}
}

And then the SavingsAccount and CheckingAccount classes extending it.

public class SavingsAccount extends BankAccount {

	public SavingsAccount(float amount) {
		this.amount = amount;
	}

	@Override
	public float extract(float unMonto) {
		if (this.amount >= unMonto) {
			this.amount -= unMonto;
			return this.amount;
		}
		throw new RuntimeException("There is not enough money to do "
				+ "the extraction...");
	}
}
public class CheckingAccount extends BankAccount {

	private float overdraft;

	public CheckingAccount(float amount, float overdraft) {
		this.amount = amount;
		this.overdraft = overdraft;
	}

	public float getOverdraft() {
		return overdraft;
	}

	@Override
	public float extract(float unMonto) {
		if (unMonto <= (this.amount + overdraft)) {
			this.amount -= unMonto;
			return this.amount;
		}

		throw new RuntimeException("There is not enough money to do "
				+ "the extraction...");
	}
}

Now, bank’s clients might have any number and types of accounts. We should also be able to know the total amount of money each client has. To implement this, the clients will respond to the totalMoney() message.

public class Client {

	private String name;
	private Set bankAccounts = new HashSet<>();

	public Client(String name) {
		this.name = name;
	}

	public String getName() {
		return name;
	}

	public float totalMoney() {
		float total = 0;
		for (BankAccount bankAccount : bankAccounts) {
			total += bankAccount.getAmount();
		}
		return total;
	}

	public void addAccount(BankAccount ba) {
		this.bankAccounts.add(ba);
	}
}

Let’s add two test cases before move on:

public class TestClient {

	@Test
	public void client_with_no_accounts_the_total_is_zero() {
		Client client = new Client("aClient");
		Assert.assertEquals(0f, client.totalMoney(), 0);
	}

	@Test
	public void client_with_two_accounts_the_total_is_calculated() {
		Client client = new Client("aClient");
		BankAccount ba1 = new SavingsAccount(350);
		BankAccount ba2 = new CheckingAccount(250, 100);
		client.addAccount(ba1);
		client.addAccount(ba2);
		Assert.assertEquals(600f, client.totalMoney(), 0);
	}
}

So, we have a simple inheritance hierarchy and a Client class with the bankAccounts polymorphic association. Next, we are going to map them into a relational model. I will first add an Id instance variable for entities. Note that the code below will only contain the necessary instance variables and mapping annotations to show our goal (you will also have to add setters and getters and the default constructor as required by Hibernate).

Single Table

I will start showing the way of persisting an inheritance hierarchy in a relational model called Single Table:

@Entity
@Inheritance
@DiscriminatorColumn(name="account_type")
public abstract class BankAccount {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	protected float amount;

	...
}

@Entity
@DiscriminatorValue("SA")
public class SavingsAccount extends BankAccount {
	...
}

@Entity
@DiscriminatorValue("CA")
public class CheckingAccount extends BankAccount {

	@Column
	private float overdraft;

	...
}

And the Client mapping that follows:

@Entity
public class Client {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	private String name;

	@OneToMany
	@JoinColumn(name = "client_id", referencedColumnName = "id")
	private Set bankAccounts = new HashSet<>();

	...
}

The bankAccounts mapping is defining a one-to-many association of BankAccounts that can be SavingsAccount or CheckingAccount, hence a polymorphic persisted association.

Note that the beauty here is that my original code did not change after introducing persistence to the model. This is valid for all the ways of persisting inheritance of course. My test remain exactly the same and that should be the case as I’m testing business logic and ideally, the addition of persistence should not interfere with that.

This mapping will generate a single table, in this case called: bankaccount, for the entire hierarchy. It is using a column called account_type to distinguish between the two kinds of bank accounts. Based on that value, Hibernate will create the instances appropriately.
As an example, the code below creates two accounts, a client and assign the accounts to the client.

// Code snippet (1)
EntityManagerFactory emf = Persistence.
		createEntityManagerFactory("bd_name");
EntityManager em = null;
EntityTransaction tx = null;

try {
	em = emf.createEntityManager();
	tx = em.getTransaction();
	tx.begin();

	Client client = new Client("aClient");
	BankAccount ba1 = new SavingsAccount(350);
	BankAccount ba2 = new CheckingAccount(250, 100);
	client.addAccount(ba1);
	client.addAccount(ba2);

	em.persist(ba1);
	em.persist(ba2);
	em.persist(client);

	tx.commit();
} catch (Exception e) {
	if (tx != null) {
		tx.rollback();
	}
	throw new RuntimeException(e);
} finally {
	em.close();
}

The execution of the code snippet (1) above, will generate a single table like below:

account_type id amount overdraft client_id
CA acount1 250 100 client1
SA acount2 350 null client1

Suppose the code snippet (2) below that retrieve the client1 from the database and print the total amount of money:

//Code Snippet (2)
EntityManagerFactory emf = Persistence.
		createEntityManagerFactory("bd_name");
EntityManager em = null;
EntityTransaction tx = null;
try {
	em = emf.createEntityManager();
	tx = em.getTransaction();
	tx.begin();

	Client client1 = em.find(Client.class, "client1");
	System.out.println(client1.totalMoney());

	tx.commit();
} finally {
	if (em != null) {
		em.close();
	}
}

That snippet will provoke the initialization of the bankAccounts collection by executing a sql statement like the following:

    select
        cliente_id,
        id,
        amount,
        overdraft,
        account_type
    from
        BankAccount
    where
        cliente_id = "client1"

A very simple and best performing sql statement with the drawback of a denormalized relational model with nullable columns.

Joined

For this way of mapping inheritance, each class in the inheritance hierarchy (including abstract classes) will have a table, sharing the primary key which represent the object id. The following code snippet shows how to map the inheritance in this way. Note that the difference in the mapping with the previous way is in the abstract class, in the @Inheritance annotation. The discriminator column is not needed here.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class BankAccount {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	protected float amount;
	...
}

@Entity
public class SavingsAccount extends BankAccount {
	...
}

@Entity
public class CheckingAccount extends BankAccount {

	@Column
	private float overdraft;
	...
}

Now executing the code snippet (1) with our classes with the Joined mapping, it will generate the following 3 tables:

bankaccount:

id amount client_id
acount1 250 client1
acount2 350 client1

savingsaccount:

id
acount2

checkingaccount:

id overdraft
acount1 100

And executing the code snippet (2), the initialization of the bankAccounts collection will generate a sql statement like the following:

    select
        bankaccoun0_.cliente_id,
        bankaccoun0_.id,
        bankaccoun0_.amount,
        bankaccoun0_2_.overdraft,
        case
            when bankaccoun0_1_.id is not null then 1
            when bankaccoun0_2_.id is not null then 2
            when bankaccoun0_.id is not null then 0
            else -1
        end as clazz_1_
    from
        BankAccount bankaccoun0_
    left outer join
        SavingsAccount bankaccoun0_1_
            on bankaccoun0_.id = bankaccoun0_1_.id
    left outer join
        CheckingAccount bankaccoun0_2_
            on bankaccoun0_.id = bankaccoun0_2_.id
    where
        bankaccoun0_.cliente_id = 'client1'

We now have a good normalized relational model with an additional cost when retrieving the the polymorphic association, due to the join sql operation that is required.

Table per Concrete Class

In this way of mapping inheritance, there will be a table per concrete class containing all their instance variables plus the ones that belongs to their super classes. It supports polymorphic associations only if the association is bidirectional.

Let see how to map this. In order to make the association bidirectional, the BankAccount class now contains a @ManyToOne association with the Client. The @OneToMany association defined on the Client has the mappedBy attribute to tell Hibernate which is the owning side.

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public abstract class BankAccount {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	protected float amount;

	@ManyToOne
	@JoinColumn(name = "client_id")
	private Client client;

	...
}

@Entity
public class SavingsAccount extends BankAccount {
	...
}

@Entity
public class CheckingAccount extends BankAccount {

	@Column
	private float overdraft;
	...
}

@Entity
public class Client {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	@Column
	private String name;

	@OneToMany(mappedBy = "client")
	private Set bankAccounts = new HashSet<>();

	...
}

Executing the code snippet (1) will generate two tables, one for CheckingAccount and another for SavingsAccount, as shown next:

checkingaccount:

id amount overdraft client_id
acount1 250 100 client1

savingsaccount:

id amount client_id
acount2 350 client1

And when executing the code snippet (2), the initialization of the bankAccounts collection will generate a sql statement like this:

    select
        bankaccoun0_.client_id as client_i3_5_0_,
        bankaccoun0_.id as id1_0_0_,
        bankaccoun0_.id as id1_0_1_,
        bankaccoun0_.amount as amount2_0_1_,
        bankaccoun0_.client_id as client_i3_0_1_,
        bankaccoun0_.overdraft as overdraf1_3_1_,
        bankaccoun0_.clazz_ as clazz_1_
    from
        (select
            id,
            amount,
            client_id,
            overdraft,
            1 as clazz_
        from
            checkingaccount

        union

        all select
            id,
            amount,
            client_id,
            nullif(0,
            0) as overdraft,
            2 as clazz_
        from
            savingsaccount
        ) bankaccoun0_
        where
                bankaccoun0_.client_id = 'client1'

Note that it is performing a union with the two bank account tables. Union is probably the most expensive operation for a database engine.

I have just presented the three ways of mapping inheritance that supports polymorphic associations. My choice would be the Joined one. Because it generates a normalized relational model. In addition, note that doing operations that require traversing a persisted collection will make the entire collection to be loaded in memory. So, you can do this only if you know that the collection will be small. And if the collection is small the sql joins operation will not be expensive.

Other Way of Persisting Inheritance

The @MappedSupperclass annotation give us another way of persisting inheritance, without supporting polymorphic associations. The @MappedSupperclass is good in case you want to move a bunch of duplicated instance variables into one super class. The following sample code shows how to use it.

@MappedSuperclass
public abstract class PersistentObject {

	@Id
	@GeneratedValue(generator = "system-uuid")
	@GenericGenerator(name = "system-uuid", strategy = "uuid")
	private String id;

	protected String getId() {
		return id;
	}

	//needed by Hibernate
	private void setId(String id) {
		this.id = id;
	}
}

@Entity
public class SomeEntity extends PersistentObject {

	@Column
	private String name;

	...
}

@Entity
public class SomeOtherEntity extends PersistentObject {

	@Column
	private String otherName;

	...
}

This mapping will generate a relational model similar to the one that Table per Concrete Class generates. In this case, the tables generated will be:

someentity:

id name

someotherentity:

id othername

Note that the id instance variable, the mapping of it into a column and their get/set methods are only defined in the PersistentObject class. However, the id column will exist in each table generated by each Entity class extending PersistentObject.

Posted in Persistence Tagged with: , , , ,

Hibernate/JPA – Transparent Persistence

This is the first of a series of posts to provide an insight about Object Oriented Persistence, using an Object Relational Mapping tool like Hibernate. We will start with few concepts.

Object Relational Mapping

JPA (Java Persistence API) is the specification created by the Java Community for persisting objects in the Java Programming Language. And Hibernate ORM (Object-Relational Mapping) is an implementation of that specification.

The goal of an ORM is to let you design your application without taking care about a persistent mechanism. Design your domain model, implement it and test it, just persisting it on memory. The ORM, after configured, will take care of persist your model objects in a persistent storage (in this case a relational storage).

Let illustrate the previous sentence with an example. Suppose I have to model Departments and Employees, where each department knows their employees. I would write the following two classes:

public class Department {

	private String name;

	private Collection employees = new ArrayList<>();

	public Department(String name) {
		this.name = name;
	}

	public void addEmployee(Employee m) {
		employees.add(m);
	}

	public int totalEmployees() {
		return employees.size();
	}
}

public class Employee {

	private float salary;
	private String name;

	public Employee(String name, float salary) {
		this.name = name;
		this.salary = salary;
	}

	public String name() {
		return this.name;
	}

	public float salary() {
		return this.salary;
	}
}

And a test to cover that piece of functionality:

@Test
public void a_new_employee_is_added_then_it_increments_the_total() {

	Department rockAndRoll = new Department("Rock And Roll");
	Employee angus = new Employee("Angus Young", 1239f);
	rockAndRoll.addEmployee(angus);
	Assert.assertEquals(1, rockAndRoll.totalEmployees());
}

And ORM like Hibernate will let you write something like the test above and make the relation between the employee angus and the rockAndRoll department persistent, isn’t that great?

You may be asking, I don’t have to deal with the JDBC API ? I don’t have to write any SQL Statement ? No! you can just write code like this:

	department1.addEmployee(new Employee("José", 10503f));

then José will be persisted and be part of department1.

The real beauty of an ORM is the transparent persistence that provides, which will let you write plain Java objects and make them persistent with little work.

Transparent Persistence

To understand how transparent persistence works, we have to understand the following concepts. The first one is a concept called Persistence Context. The Persistence Context is the place used by the ORM to keep track of your Objects changes in order to persist them at a later point. In JPA this context is managed by the javax.persistence.EntityManager class. Each Java Object in a persistence context will have one of these states:

  • new, or transient: the object has just been instantiated and is not associated with a persistence context. It has no persistent representation in the persistent storage.
  • persistent: the object is associated with a persistence context and has representation in the persistent storage.
  • detached: the object is no longer associated with a persistence context (usually because the persistence context was closed).
  • removed: the object is associated with a persistence context, however it is scheduled for removal from the persistent storage.

The other important concept is called Persistence by Reachability. Which states that any transient object that gets related to a persistent object, will become persistent too.

These two concepts implemented make the so called Transparent Persistence possible.

Let’s put these concepts in code. The following code block defines the persistence context, and illustrate the persistence by reachability.

	EntityManager em = //obtain the EntityManger instance
	EntityTransaction tx = null;
	try {
		tx = em.getTransaction();
		tx.begin();

		Department dept1 = em.find(Department.class, "department1");
		dept1.addEmployee(new Employee("José", 10503f));

		tx.commit();
	} catch (Exception e) {
		if (tx != null) {
			tx.rollback();
		}
		throw new RuntimeException(e);
	} finally {
		em.close();
	}

On line 7, I’m getting the Department department1 from the persistent storage and on line 8 just append a new employee to it. Due to department1 is in the persistent state, by reachability the transient instance of Employee (José) will be persisted and attached to the department.

A similar scenario that also illustrate the two concepts described above is when having two transient objects, Department and Employee, and the Employee has a relation (or is part of) to the Department. If I persist the Department, then the Employee will be persisted too. Code shown below:

	//start persistence context
	...
	Department dept1 = new Department("department1");
	dept1.addEmployee(new Employee("José", 10503f));

	em.persist(dept1);
	...
	//close persistence context

Below are some more examples that continue demonstrating the beauty of the transparent persistence. Changing the name of a department:

	//start persistence context
	...
	Department dept1 = new Department("department1");
	dept1.setName("anotherDepartmentName");
	...
	//close end of persistence context

Removing an employee from a department:

	//start persistence context
	...
	Department dept1 = // retrieving from the storage
	dept1.removeEmployee(new Employee("Javier", 4569f));
	...
	//close end of persistence context

Lets write something a bit richer. Suppose each department gains 5 points each time a woman joins them and 3 points for men and subtract 5 points when an employee leaves them. I would change the Department class in the following way:

public class Department {

	...

	private int points;

	public void addEmployee(Employee e) {
		points += e.points();
		employees.add(e);
	}

	public void removeEmployee(Employee e) {
		points -=  e.points();
		employees.remove(e);
	}

	...
}

Now, if I add an employee to a department:

	//start persistence context
	...
	Department dept1 = // retrieving from the storage
	dept1.addEmployee(new Employee("Julio", 6205f));
	...
	//close end of persistence context

in addition to persist the new Employee and the relation with the department, it will also persist the new points obtained by adding employees to the department. It will be done executing two SQL statements wrapped in a transaction. Something like:

insert into employees values("Julio", 6205f, "department1");
update departments set points = ? where id = "department1";

That was transparent right? You can visualize all the work done by the ORM for you. This means that you can focus the effort on make a good Object Domain Model (and with good I mean, with business logic inside and not an anemic model), test it on memory, get a high test coverage, and let the ORM to take care of the persistence.

The support of Transparent Persistence is what makes Hibernate an invaluable tool.

Posted in Persistence Tagged with: , , , ,

Eclipse and PHP

After installing LAMP, lets configure Eclipse for PHP development.

1. Install Eclipse

Download Eclipse latest version, from here. You just need the Eclipse Standard version (if you only want to develop PHP Web Applications). At the time of writing this post the latest Eclipse version is Luna. Once downloaded, start it up. If you try to create a new project, you will see that only Java projects are available. Now, lets enable PHP projects.

2. Enable PHP in Eclipse

In Eclipse, go to the “Help” menu, then “Install New Software…“. On the “Work with:” input field, type this URL: http://download.eclipse.org/releases/luna. This will display a list of different tools to install. Under the “Programming Languages” category, you will find “PHP Development Tools (PDT)“, check it and click “Next” to follow the wizard to install it.

Restart Eclipse and once is up you will note that in the “Open Perspective” now you have PHP as an option. In addition, in the menu “Windows > Preferences”, you will see a set of PHP options too.

3. Enable User’s Home Directory

As PHP runs using Apache, you will need to create the project in a directory that Apache can see. There are many ways of doing this, but one I like is to use the {user.dir}/public_html that Apache supports pretty well and is accessible from a browser using http://localhost/~{user.dir}.

To enable this do the following:

  1. Go to the mods-enable directory in the Apache home directory, usually under /etc/apache2/mods-enable.
  2. Run the following commands:
    • sudo ln -s ../mods-available/userdir.load
    • sudo ln -s ../mods-available/userdir.conf
  3. Lastly, to enable the PHP interpreter under the {user.dir} directory, edit the /etc/apache2/mods-enabled/php5.conf file and comment out, using #, the lines below:
    • <IfModule mod_userdir.c>
      <Directory /home/*/public_html>
      php_admin_flag engine Off
      </Directory>
      </IfModule>
  4. restart apache: sudo service apache2 restart

4. Set up a PHP Project
On Eclipse go to File->New->PHP Project. A “New PHP Project” window will open. On the Contents section, choose the radio button that says: “Create Project at Existing Location (from existing source)”. In the Directory input choose your {home_directory}/public_html/{project_name}, and press finish. An you are done. To test it, just create a PHP file, called test.php, like this:

<?php echo "<b>Hello World!</b>";?>

save it, and in the browser go to the following URL: http://localhost/~{user_name}/{project_name}/test.php. If you see “Hello World!” in bold, then you are done!.

Posted in Dev&Ops Tagged with: ,

LAMP stack in Ubuntu – Install & Configuration

This is the first post of two where you will end up configuring a PHP development environment in Ubuntu and using Eclipse. This first post is for installing and configuring Apache, MySQL and PHP in Ubuntu.

From a fresh installation of Ubuntu follow these steps:

Installing LAMP

1. Refresh your Ubuntu package index, executing the following command: sudo apt-get update
2. Install the lamp server: sudo apt-get install lamp-server^. Note the caret (^) at the end. That is required to let apt-get to install the lamp-server without using tasksel (another tool for installing common packages that are used together).
During installation you will be informed that 119MBs are required for the installation. And also you will be asked for the MySQL root password.

Apache Configuration

Now, to finally configure apache2, run the following commands:
1. apache2
2. sudo service apache2 restart

To test that apache is running, go to http://localhost/, and if you see on you browser the message “It works!”, then you are OK. The default document root in Ubuntu is /var/www/html. So, when you navigate with http://localhost/, you should see the content of the file /var/www/html/index.html.

Here is a sample command of how to deal with the apache service:
sudo service apache2 [start|stop|restart]

PHP5
Create a file called /var/www/html/test.php, and inside it paste the following code:

<?php 
  phpinfo();
?>

Then go to http://localhost/test.php and verify that you see the php information page.

PHP5 comes with two configuration files, one for development and other for production. You will find them in the following locations: /usr/share/php5/php.ini-development and
/usr/share/php5/php.ini-production. To configure the one for development, first do a backup copy of the current one and then, create a symbolik link, running the following two commands:

sudo mv /etc/php5/apache2/php.ini /etc/php5/apache2/php.ini.bak
sudo cp -s /usr/share/php5/php.ini-development /etc/php5/apache2/php.ini

Debug in PHP
In order you can debug PHP applications, you have to install xDebug. Run the following commands:
sudo apt-get install php5-xdebug
sudo gedit /etc/php5/apache2/php.ini
# Added for xdebug
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=127.0.0.1 xdebug.remote_port=9000

Then, restart the apache service: sudo service apache2 restart

MySQL

You can enter to the mysql console, typing: mysql -u root -p. Or you can install MySQL-Workbench running the following command: sudo apt-get install mysql-workbench. After that to start mysql workbench, just type in a console: mysql-workbench.

Now that you have LAMP installed, configured and tested, you can read the Eclipse/PHP post to install and configure Eclipse to start developing.

Posted in Dev&Ops Tagged with: ,

Use Inheritance Properly

How many times did you ask yourself, in order to avoid duplicated code, if you should use inheritance or composition? Did you ask yourself about the differences between subtype and subclass? Do you always follows the Liskov Substitution Principle? This post will try to help to answer these questions. And try to give you more clarity to how and when subclassing is appropriate to be used.

The content of this post is a combination of paragraphs extracted from two great books: An Introduction to Object Oriented Programming, by Timothy Budd and Program Development in Java, by Barbara Liskov and John Guttag.

I would say that subclassing is used correctly if the subclass is also a subtype of the parent class. Let me try to explain this sentence, starting with what type and subtype means.

Subclass and Subtype

When we say that the number 5 is of type integer, we are stating that 5 belongs to a set of possible values (as an example, see the possible values for the Java primitive types). We are also stating that there is a valid set of methods I can perform on the value like addition and subtraction. And finally we are stating that there are a set of properties that are always satisfied, for example, if I add the values 3 and 5, I will get 8 as a result.

To give another example, think about the abstract data types, Set of integers and List of integers, the values they can hold are restricted to integers. They both support a set of methods, like add(newValue) and size(). And they both have different properties (class invariant), Sets does not allow duplicates while List does allow duplicates (of course there are other properties that they both satisfy).

Subtype is also a type, which has a relation to another type, called parent type (or supertype). The subtype must satisfy the features (values, methods and properties) of the parent type. The relation means that in any context where the supertype is expected, it can be substitutable by a subtype, without affecting the behaviour of the execution. Let’s go to see some code to exemplify what I’m saying. Suppose I write a List of integers (in some sort of pseudo language):

class List {
  data = new Array();

  Integer size() {
    return data.length;
  }

  add(Integer anInteger) {
    data[data.length] = anInteger;
  }
}

Then, I write the Set of integers as a subclass of the List of integers:

class Set, inheriting from: List {
  add(Integer anInteger) {
    if (data.notContains(anInteger)) {
      super.add(anInteger);
    }
  }
}

Our Set of integers class is a subclass of List of Integers, but is not a subtype, due to it is not satisfying all the features of the List class. The values, and the signature of the methods are satisfied but the properties are not. The behaviour of the add(Integer) method has been changed, not preserving the properties of the parent type.

How bad is this?

Well, this allows you to use Sets where Lists are expected. For example, a method in any other class might operate on a List, receiving it as a parameter, but at runtime you might receive a Set, which in that case it will change the behaviour that you are expecting, which is the behavior of the parent type. That is not goodYou have to think from the perspective of the client of your abstractions (a class and subclass in this case). This change in the behaviour will be a big surprise for your clients.

The following test case will pass if we use a List, but it will fail if we use a Set which was defined as a subclass of List.

test_subtype_relation() {
  list = new List(); # using Set() will break this test, not good.
  list.add(10);
  list.add(10);
  assertEquals(2, list.size());
}

The tests you have for your parent classes should still pass if you use instead any of their subclasses.

The example presented above is a classic use of inheritance only for code reuse, the size() method fits perfect with my Set of integers. In these cases, composition is your choice.

I hope this is not a surprise for you, but here is another consequence of this bad use of inheritance: we are violating the Liskov Substitution Principle which has been made popular by the SOLID principles. Remember, if you are subclassing but violating the subtyping relation, you are not following the Liskov Substitution Principle.

Is Overriding Always Bad?

From the example above, you might have gotten the feeling that overriding is always a bad choice if you want your subclass also be a subtype. That is not the case. Think about, for example, what would happen for the Object class in languages like Smalltalk or Java. They both implement a default behaviour for the equals(anObject) (in the case of Java) method, and the =anObject (in the case of smalltalk) method. Your subclasses, most of the time, needs to override this behaviour, and we still need to do it in the proper way.

So, to do it in the right way, we need to reason about the specification, the preconditions and the postconditions, of the method that we want to override. See the specification of the method add(anInteger) below from our previous example:

# pre:  -
# post: adds anInteger to this
List.add(anInteger);
# pre:  -
# post: if anInteger is not in this, then added it to this
Set.add(anInteger);

When you override a method, the precondition and postcondition of your subclass can differ from those on the parent class, but only taking into account the following. The method in the subclass can:

  • weaken the precondition and,
  • strengthen the postcondition.

Both conditions must be satisfied. Weakening the precondition means that the subclass method requires less (or the same) from the client (the caller) than what the supertype method does. This ensures that the client, written in terms of the supertype precondition, will continue be able to execute the method, if a subclass is used instead. Strengthening the postcondition means that when the method returns, the postcondition of the parent class is satisfied and also additional conditions might be added. In the case of our previous example, the precondition on the add(anInteger) is the same for both the subclass and the parent class, but the postcondition has been modified by the subclass method, not preserving the one on the parent class.

The next example, presents a CounterPairList class, which is a subclass of List, and also a subtype. See how the postcondition of the overriden add(anInteger) method preserves the parent type postcondition while also add an additional condition.

class CounterPairList, inheriting from: List {
  counter = 0;

  # pre:  -
  # post: adds anInteger to this, verify if a pair number was added to keep track
  add(Integer anInteger) {
    super.add(anInteger);
    if (anInteger % 2 == 0) {
      counter++;
    }
  }

  # pre:  -
  # post: returns the size of pair intergers in the List
  Integer sizeOfPairNumbers() {
    return counter;
  }
}

As an exercise, think about how you should override the Java Object#equals(anObject) method in order to preserve the subtype properties. Tell me…

Ways of Inheritance

There are several ways in which inheritance can be used, here is a list of some of them which I have used and I have seen other using them too:

  • For code reuse: Like we did in our first example, creating a Set of Integers, inheriting from List of Integers. Of course, avoid the duplication of code is a desirable thing, but there are other ways to do it, like composition. This is not good if you cannot preserve the features of the parent class.
  • For specialization: Like we did for our CounterPairList example, occurs when the subclass is a specialized form of the parent class, preserving the features of the parent class. Other typical example is when we have Cow as a specialized form of Mammal. This is considered a good way of inheritance as subclasses are subtypes.
  • For specification: This is where the subclasses implements behavior specified in the parent. Like the Java interface syntactical construction (or C++ pure virtual functions) or the abstract syntactical construction where some behaviour is implemented in the parent and there are some other bits deferred to the subclasses. This is considered also a good way of inheritance, considering that the subclasses will be also subtypes. I’m making this last comment as you can always define, for instance, the specification (in a Java interface) of the Stack#push and Stack#pop methods, and then implement them like they were a simple Set.
  • For limitation: This is where the behaviour of the subclass is smaller than the behaviour of the parent class. I have seen this way several times. When some methods of a class fits for you, so, you inherit from it. Other methods that you are inheriting should not be used, so you override those methods in order to inform the client that those are not available (throwing an exception with a message: “Not available for instances of this subclass…”). Don’t do this.
  • For naming a thing: Sometimes you just creates a subclass as a way to name or model something you see on your real world, but that subclass does not have behaviour at all. Just a constructor. Don’t do this. A class without behaviour is not really an object. You can find a great example of this on the book Test-Driven Development By Example, from Kent Beck. There you will see how and why the classes Dollar and Franc which are subclasses of Money end up disappearing.

Few Additional Comments on Inheritance

  • Inheritance is highly (and improperly) used for code reuse instead of composition in languages like Java because you have to write much less code. Composition requires you to write more code, for inject the collaborator in the constructor, and delegate on those methods you want to reuse. However, this is a lack of the language. For instance, C++ provides a syntactical construction called private inheritance where you can inherit all the facilities of the parent class, but those are not available for clients nor the subclass can be substituted when the parent class is expected.
  • Even when your subclass is a subtype of the parent class, the parent class might change their pre/postcondition in a subsequent release, which might break the subtype relation. Or the parent class might get an additional method and accidentally there is a method in the subclass with the same signature, then you end up overriding the method without knowing it. Subclasses and their parent classes need to evolve together.
  • Inheritance is a “white box” code reuse style, as you need to know how some methods are implemented to safely create subclasses. The implementation of methodA might call methodB and methodC from the same class, to fulfill an action. In the subclass, you might override methodB and get unexpected results when calling methodA. Inheritance breaks encapsulation.

Use inheritance properly, when subclasses are also subtypes. If you cannot guarantee that, use composition. And even when using inheritance properly keep an eye on how the inheritance hierarchy evolves to avoid surprises.

Posted in Design & Architecture, Object Oriented Programming Tagged with: , ,

An Introduction to Gradle

Reading over the web about the Spring 3.2 new features, I discovered that Spring has been migrated their build scripts from Ant+Ivy to Gradle. All the build scripts that creates and manage the Spring modules were converted into Gradle. This decision put me to read about Gradle. And there is when I decided to add Gradle to my sample application Tnt Book Store, in order to do some “real things”.

Gradle took many ideas from Maven and Ant. But it is not XML based. It is a declarative DSL (Domain Specific Language) based on Groovy, for building and manage applications. It provides a plugin concept like Maven, so it makes common tasks pretty easy with very few lines of code. And if you need more complex builds, you can do it in Groovy, instead of XML. This is probably the main difference: use the Groovy programing language to make complex builds, which will be easier to maintain than XML.

Lets start first by building and running the Tnt Book Store application using Gradle:

  1. Download Gradle.
  2. Add the Gradle bin directory to your PATH environment variable.
  3. Make sure you have the JAVA_HOME environment variable set. Gradle needs it.
  4. Download the source code of the Tnt Book Store application, using svn:
    svn checkout http://tnt-book-store.googlecode.com/svn/trunk/ tnt-book-store-read-only
    
  5. Go to the root directory where the source code is located, the build.gradle file should be there.
  6. Then, just type: gradle -Dspring.profiles.active=dev jettyRunWar
  7. After finishing, gradle will shows you the URL where you can navigate and use the application.

Here we have compiled, retrieved dependencies from the maven public repository, created the war file and deployed it in Jetty (the application use the embedded derby database, and it gets populated with sample data at startup). Below is the build.gradle file that is required for doing this.

apply plugin: 'jetty'

sourceSets {
    main {
        java {
            srcDir 'src'
            srcDir 'db'
        }
        resources {
            srcDir 'resources'
        }
    }
	test {
        java {
            srcDir 'test'
        }
        resources {
            srcDir 'test-resources'
        }
    }
}

war {
	from 'WebContent'
}

repositories {
	mavenCentral()
}

dependencies {
	testCompile 'junit:junit:4.8.2'
	testCompile 'org.springframework:spring-test:3.1.0.RELEASE'

	compile 'joda-time:joda-time:2.0'
	compile ('org.springframework:spring-context:3.1.0.RELEASE') {
		exclude group: 'javax.ejb'
		exclude group: 'javax.jms'
		exclude group: 'com.bea.wlplatform'
	}
	compile 'org.springframework:spring-webmvc:3.1.0.RELEASE'
	compile ('org.springframework:spring-orm:3.1.0.RELEASE') {
		exclude group: 'com.oracle'
		exclude group: 'com.oracle.toplink'
		exclude group: 'org.apache.ibatis'
	}
	compile 'hsqldb:hsqldb:1.8.0.10'
	compile ('org.hibernate:hibernate-core:3.6.7.Final') {
		exclude group: 'antlr'
		exclude group: 'org.jboss.javaee'
	}
	compile 'org.hibernate:hibernate-validator:4.2.0.Final'
	compile 'org.apache.derby:derby:10.9.1.0'
	compile ('com.google.guava:guava:r09') {
		exclude group: 'com.google.code.findbugs'
	}
	compile 'commons-lang:commons-lang:2.6'
	compile 'commons-httpclient:commons-httpclient:3.1'

	compile 'org.codehaus.jackson:jackson-mapper-asl:1.4.2'
	compile 'org.codehaus.jackson:jackson-core-asl:1.4.2'
	compile 'org.mortbay.jetty:servlet-api-2.5:6.1H.14.1'
	compile 'javassist:javassist:3.4.GA'
	compile 'antlr:antlr:2.7.6'
}

The file is divided in four sections. The first section is the plugin definition. In this case, I’m using the jetty plugin. But since the jetty plugin inherit from the war plugin and the war plugin inherits from the java plugin, then I get everything just specifying one plugin.
Then, I have to specify the java source folders names. Gradle needs to know where to locate the source code within your project. This is only necessary because I’m not using the maven naming convention for java source folders. Then, the same for the source files from your web application, which in this case is WebContent. And finally, the declaration of the dependencies. That is pretty much all for building, bundling and deploying a java web application (and I did not write XML :)).

Posted in Dev&Ops Tagged with: ,

Please, use the debugger

Before getting into the point of this post, by debug I mean going through each line of source code one after one or step by step. Reviewing the state of the memory at each step (and if you are really interested on how a debugger works under the hood, you can play with a tool I wrote and presented in the post a bit about programming language implementation).

Now, going to the point of this post, I have found, during my experience (which is far from large one) working with other developers, that few of them use the debugger as the first tool for troubleshooting and learning or understand legacy code. My experience is mostly based on Java/Eclipse. If you are familiar with Java/Eclipse, you will know that debugging an application is pretty simple. Indeed, Java allows you to debug remote JVMs. Yes, you are able to debug a JVM deployed in one continent from an Eclipse running on a workstation on another continent. Very nice.

Why developers don’t use a debugger? Maybe because the experience of most of them came from web scripting languages like the old ASP (MS Active Server Pages) or PHP, which does not provide a way to debug (or is pretty complex to do it). In addition, a couple of years ago, you did not have a tool for debugging Javascript code.

Mostly during my assignments in my undergraduate courses, I used Pascal, C and C++. And a debugger in those languages becomes pretty necessary. Especially if you are trying to find out an issue that may be caused by a dangling reference. So, I have learned those programming languages and learned how to troubleshoot applications using a debugger. On my working experience, I jumped into Java/Eclipse. Java and their Exception mechanisms generates very informative errors making the use of the debugger less necessary than in C (in addition, and among other things, pointers in Java are not managed by the developer which is far less error prone). However, the debugger is still the best tool for troubleshooting and for understanding legacy code.

I have received questions from other developers like: “…when I click on the button X, I get an error page with the suggestion to call the customer service”. My answer is always the same… “Please, use the debugger, and let me know what you find”. In most of the cases, they come after 10 minutes saying something like: “… forget it, it was something wrong I did…”.

Other developers try to understand what is going on looking at the code and trying to follow the flow of the program in their head. Which of course is not easy, and very error prone. Don’t waste your time, please, use the debugger.

If you find an issue, follow these steps:
1. Start the debugger and discover what is going on.
2. Write a unit test that reproduces the issue. You will get the red bar.
3. Fix the issue.
4. Run the unit test you wrote in the step 2, and see if you get the green bar.
5. If you get the green bar, move on.

If you need to deal with legacy code, the debugger is your tool to understand and get the knowledge that later will let you apply light/safe refactors to make the code testable.

Today, you should not choose a programming language to develop an application (even small ones! Unless you just need the Hello World!) which does not provide an IDE for debugging. In addition, your IDE should allow you to run/execute unit tests (and debug them if necessary).

Posted in Notes Tagged with: