Monday, 25 September 2017

Convenience Factory Methods for Collections in Java 9

Java 9 doesn't bring as dramatic changes to the way of coding as its predecessor did but surely we will have some fancy features, one of which I would like to present to you in this article. When I started coding in Groovy about 5 years ago, I was amazed by the collections support there. Especially when it came to initialize an immutable list, I could do it in one simple line:

def band = ["Bruce", "Steve", "Adrian", "Dave", "Janic", "Nicko"].asImmutable()

This year I also started coding in scala, and here we have some fancy tricks like:
val band = "Bruce" :: "Steve" :: "Adrian" :: "Dave" :: "Janick" :: "Nicko" :: Nil

or simply

val band = List("Bruce", "Steve", "Adrian", "Dave", "Janick", "Nicko")

At the same time Java seemed to be torturing me with an add statement list:

List<String> band = new ArrayList<>();
band.add("Bruce");
band.add("Steve");
band.add("Adrian");
band.add("Janick");
band.add("Nicko");
band = Collections.unmodifiableList(band);

or so called "double-brace" initialization (which in fact isn't any special Java feature, but rather a workaround benefiting from anonymous classes and initialization blocks):

List<String> band = Collections.unmodifiableList(new ArrayList<>() {{
  add("Bruce");
  add("Steve");
  add("Adrian");
  add("Janick");
  add("Nicko");
}});

or using arrays API to convert array to an ArrayList

List<String> band = Collections
  .unmodifiableList(Arrays.asList("Bruce","Steve","Adrian", 
                                  "Dave", "Janick","Nicko"));

Lately I could also benefit from Stream API:

List<String> band = Collections
  .unmodifiableList(Stream.of("Bruce","Steve","Adrian", "Dave", "Janick","Nicko")
    .collect(toList()));


Two last options are the cutest ones, but why do I need to first create an array or a stream in order to create a list, and why can't I just use Collections API instead of Arrays API or Stream API? Well, I don't even want to recall the way we can create Sets or Maps in Java - thinking of it makes me wake up in sweat in the middle of the night.

So far, the most concise and elegant way of creating immutable collections was provided by Guava library and classes like ImmutableList, ImmutableMap, ImmutableSet, etc. Below is an example of what was desired to be available in Java out of the box:

List<String> band = ImmutableList.of("Bruce", "Steve", "Dave",
                                     "Adrian", "Janick", "Nicko");

Fortunately, authors of Java 9 implemented JEP 269: Convenience Factory Methods for Collections, which simply provides a set of static factory methods supporting creation of immutable collection instances. Saviours! Read on to get the overview of this feature.

Immutable collections


Before we dig into the topic you should know what immutable collections really are. So, they are collections that cannot be modified once they are created. What I mean by modified is that their state (references they hold, order in which those references are being kept, and the number of elements) will stay untouched. Please note that if an immutable collection holds mutable objects, their state won't be protected anyhow. Although immutable collections still implement List, Set or Map interfaces, methods modifying their contents throw UnsupportedOperationException. You will find sets of such methods in subsequent sections.

Implementation


Implementation can be devided into two main parts. Firstly, java.util package was enriched with package-private ImmutableCollections class, that contains classes providing the immutability feature. Secondly, instances of those classes are being created with the help of static factory methods in already existing interfaces, i.e. List, Set, and Map. In following sections you will find description of both sets of functionalities per each collection interface.

List


An immutable list has an abstract base class AbstractImmutableList<E> and four implementations:

  • List0<E>
  • List1<E>
  • List2<E>
  • ListN<E>

Each of these types correspond to the number of elements that is used to their creation. In java.util.List interface we have 12 static factory methods that use the above implementations to create immutable objects:

// creates empty immutable list
static <E> List<E> of()

// creates one-element immutable list
static <E> List<E> of(E e1)

// creates two-element immutable list
static <E> List<E> of(E e1, E e2)

...

// creates ten-element immutable list
static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)

// creates N-element immutable list
static <E> List<E> of(E... elements)

Methods that throw UnsupportedOperationException:

boolean add(E e);
boolean addAll(Collection<? extends E> c);
boolean addAll(int index, Collection<? extends E> c);
void    clear();
boolean remove(Object o);
boolean removeAll(Collection<?> c);
boolean removeIf(Predicate<? super E> filter);
void    replaceAll(UnaryOperator<E> operator);
boolean retainAll(Collection<?> c);
void    sort(Comparator<? super E> c);

Apart from protecting the content of our list, we also get a validation, that prevents us from initiating a list with a null value. Trying to run the following piece of code, we will end up with NullPointerException:

// throws NullPointerException
List<String> band = List.of("Bruce","Steve","Adrian", "Dave", "Janick", null);

Now here is an example of how to properly create immutable list:

List<String> band = List.of("Bruce","Steve","Adrian", "Dave", "Janick","Nicko");

Set


An immutable set is implemented similarly to what we have seen with the List interface. It has an abstract base class AbstractImmutableSet<E> and four implementations:

  • Set0<E>
  • Set1<E>
  • Set2<E>
  • SetN<E>

that again correspond to the number of elements that is used to their creation. In java.util.Set interface we have 12 static factory methods:

// creates empty immutable set
static <E> Set<E> of()

// creates one-element immutable set
static <E> Set<E> of(E e1)

// creates two-element immutable set
static <E> Set<E> of(E e1, E e2)

...

// creates ten-element immutable set
static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)

// creates N-element immutable set
static <E> Set<E> of(E... elements)


Methods that throw UnsupportedOperationException:

boolean add(E e)
boolean addAll(Collection<? extends E> c)
void    clear()
boolean remove(Object o)
boolean removeAll(Collection<?> c)
boolean removeIf(Predicate<? super E> filter)
boolean retainAll(Collection<?> c)


Like with immutable lists, we cannot instantiate a Set with a null value:

// throws NullPointerException
Set<String> band = Set.of("Bruce","Steve","Adrian", "Dave", "Janick", null);


You should also know, that sets differ from lists in a way, that they cannot have duplicate values. With newly provided factory methods, we won't be able to initialize an immutable Set passing more than one object of the same value - we will get IllegalArgumentException:

// throws IllegalArgumentException
Set<String> guitarists = Set.of("Adrian", "Dave", "Janick", "Janick");

Now here is an example of how to properly create immutable set:

Set<String> band = Set.of("Bruce","Steve","Adrian", "Dave", "Janick","Nicko");

Map


Before we describe immutable map technical details we should start with the concept of an entry (java.util.Map.Entry interface) - an aggregate of key - value pair. From Java 9 we have yet another Entry's package private implementation - java.util.KeyValueHolder -  an immutable container, that prevents from instantiating an entry with key or value equal to null (throwing NullPointerException if done so).

In order to create an immutable entry, we can use following static factory method from java.util.Map interface:

static <K, V> Entry<K, V> entry(K k, V v)

Immutable map has an abstract base class AbstractImmutableMap<K, V> with three implementations:

  • Map0<K, V>
  • Map1<K, V>
  • MapN<K, V>

Again we have the following set of factory methods inside java.util.Map interface:

// creates an empty map
static <K, V> Map<K, V> of()

// creates one-element map
static <K, V> Map<K, V> of(K k1, V v1)

// creates two-element map
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2)

...

// creates ten-element map
static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4,
                           K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, 
                           K k9, V v9, K k10, V v10)

// creates N-element map
static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries)

You can see that it differs from List or Set factory methods from previous chapters. Using one of the of methods we can create immutable maps that contain up to 10 elements. If we want to have a bigger one, we need to use ofEntries method, accepting varargs of Entry. It shouldn't be any surprise, as we can use varargs for only one argument in a method, so we have no way of passing keys and values of different types this way.

Like with lists and sets, we have some methods that throw UnsupportedOperationException:

void clear()
V compute(K key, BiFunction<? super K,? super V,? extends V> rf)
V computeIfAbsent(K key, Function<? super K,? extends V> mf)
V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> rf)
V merge(K key, V value, BiFunction<? super V,? super V,? extends V> rf)
V put(K key, V value)
void putAll(Map<? extends K,? extends V> m)
V putIfAbsent(K key, V value)
V remove(Object key)
boolean remove(Object key, Object value)
V replace(K key, V value)
boolean replace(K key, V oldValue, V newValue)
void replaceAll(BiFunction<? super K,? super V,? extends V> f)

Regardless the way of creating immutable map (of or ofEntries method) we won't be able to instantiate it with key, value or whole entry equal to null. Below are the examples of code that will throw NullPointerException:

// throws NullPointerExcepton because of null key
Map<String, Long> age = Map.of(null, 59L, "Steve", 61L);

// throws NullPointerExcepton because of null value
Map<String, Long> age = Map.of("Bruce", null, "Steve", 61L);

// throws NullPointerExcepton because of null entry
Map<String, Long> age = Map.ofEntries(Map.entry("Bruce", 59L), null);

Similarily to immutable set, we cannot create a map with duplicate values. Trying to do so will end up with throwing IllegalArgumentException:

Map<String, Long> age = Map.of("Bruce", 59L, "Bruce", 59L);

Map<String, Long> age = Map.ofEntries(Map.entry("Bruce", 59L),
                                      Map.entry("Bruce", 59L));

And here are some examples of how can we properly create immutable maps in Java 9:

Map<String, Long> age = Map.of("Bruce", 59L, "Steve", 61L, "Dave", 60L,
                               "Adrian", 60L, "Janick", 60L, "Nicko", 65L);

Map<String, Long> age = Map.ofEntries(Map.entry("Bruce", 59L),
                                      Map.entry("Steve", 61L),
                                      Map.entry("Dave", 60L),
                                      Map.entry("Adrian", 60L),
                                      Map.entry("Janick", 60L),
                                      Map.entry("Nicko", 65L));


Conclusions


Since Java 9, creating immutable collections is very convenient. We have a set of static factory methods for each interface, that, apart from creating immutable objects, prevent from inserting nulls or duplicates (in Set and Map). We are warned about any problems at creation time, and we are secured from getting NullPointerExceptions while traversing collection elements. It is a tiny feature, but surely a useful one!


Monday, 18 September 2017

Following OOP principles - hermetization

Have you ever looked at the code that you had written couple of months ago and asked yourself: “who could leave such a mess here?” Have you ever been so lazy that you didn’t think of what accessors/mutators you need, simply hitting “Generate getters and setters” for your entity in IDE? Or maybe you have used lombok’s @Getter/@Setter annotations to get the same effect? Yep, just as I thought! Well, honestly, I did this way too many times, too. The problem is that it is not the only crime that we can commit in order to break some of the basic OOP principles. In this article we will focus on hermetization (information hiding) but other paradigms, like abstraction or encapsulation will be mentioned too, as they all are complementary to each other. In the following paragraphs I will give you an explanation of what is hermetization and how to provide one within Java. We will discuss common pitfalls and some good practices. You will also find here some philosophical considerations and my own judgements and opinions. I am very open for further discussions. I will walk you through an example of a very poorly written classes, which we will improve step by step, looking at hermetization from numerous perspectives. Enjoy!

Hermetization


Hermetization is about hiding information (implementation details) that shouldn’t be visible to clients of a class or a module. As long as we follow the encapsulation paradigm, we enclose information (state) and interface (behavior) in a class. Now an interface (API) is a declaration of how we can interact with a particular object. Should we care about how this interaction is implemented? Should we care about the data representation inside? Should we publish methods modifying internal state, that is supposed to be done automatically? Nope, not at all. We just want to send it a command, get the result, and forget. At the same time we want our internals to stay safe and untouched (intentionally or unintentionally) from the outside.

The less information we expose to the outer world, the less coupled modules we get. Thus, we gain a better separation of classes, which it turn means that we can easily:
  • manipulate the logic/internals inside a class not worrying that we will break our clients,
  • analyse, use, and test such classes, as we have a clear interface
  • reuse them, as independent classes might appear to be useful in some other contexts
  • keep object's state safe.

Example overview


In this article we will focus on a simple business case. We need to provide following things:

  • the ability to create both contact person and a customer,
  • each contact person can have an email address - we want to both present and modify this data,
  • a particular contact person might be assigned to more than one customer
  • each customer can have a name, and a list of contact people
  • we want to store a timestamp of the moment of customers' creation and activation
  • we also want to be able to easily activate a customer and verify if a customer is activated or not
  • we want to present customer's name, contact people, creation date and a flag of activation
  • name and contact person list can be modified in future, but creation date must be set only once during creation phase.

Here is a piece of extremely poorly written code:

public class ContactPerson {
  public long id;
  public String email;
}
public class Customer {
  public long id;
  public String name;
  public Date creationDate;
  public Date activationDate;
  public ArrayList<ContactPerson> contactPeople = new ArrayList<>();
}
public class CustomerService {

  public Customer createCustomer(String name,
                                 ArrayList<ContactPerson> contactPeople) {
    if(contactPeople == null) {
      throw new IllegalArgumentException("Contact people list cannot be null");
    }
    if (StringUtils.isEmpty(name)) {
      throw new IllegalArgumentException("Name cannot be empty");
    }
    final Customer customer = new Customer();
    customer.id = Sequence.nextValue();
    customer.creationDate = new Date();
    customer.name = name;
    customer.contactPeople = contactPeople;
    return customer;
  }

  public ContactPerson createContactPerson(String email) {
    final ContactPerson contactPerson = new ContactPerson();
    contactPerson.id = Sequence.nextValue();
    contactPerson.email = email;
    return contactPerson;
  }

  void activateCustomer(Customer customer) {
    customer.activationDate = new Date();
  }

  boolean isCustomerActive(Customer customer) {
    return customer.activationDate != null;
  }

  void addContactPerson(Customer customer, ContactPerson contactPerson) {
    customer.contactPeople.add(contactPerson);
  }

  void removeContactPerson(Customer customer, ContactPerson contactPerson) {
    customer.contactPeople.removeIf(it -> it.id == contactPerson.id);
  }
}

You can see that we have two model classes and a service fulfilling mentioned business requirements. Let's try to work on this example to make it a shiny one. You can find the final version of this example here.

Please note that we skip here all aspects of concurrency.


Access control, accessors, mutators


The first facility for information hiding that Java gives us is access control mechanism. We have a few options to choose:
  • Private
  • Package-private
  • Protected
  • Public
By default, we are granted a package-private scope which gives us a bit of hermetization out of the box. The language itself suggests that we should keep our modules (packages) independent, reusable - it should be our conscious decision to make a class, a method or a field a public one.

The code from above does what it is supposed to do, but with this approach you face following problems:
  • you cannot change the data representation without modifying client's code - the information about how you store data becomes a part of your API,
  • you cannot perform any extra actions  (like validation) when field is being accessed/modified.
It means we have no hermetization at all. The easiest way of dealing with it is to restrict all instance members' visibility to private scope and define their accessors (getters) and mutators (setters) like below:

public class ContactPerson {
  private long id;
  private String email;

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  @Override
  public String toString() {
    return "ContactPerson{" +
      "id=" + id +
      ", email='" + email + '\'' +
      '}';
  }
}

public class Customer {
  private long id;
  private String name;
  private Date creationDate;
  private Date activationDate;
  private ArrayList<ContactPerson> contactPeople = new ArrayList<>();

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Date getCreationDate() {
    return creationDate;
  }

  public void setCreationDate(Date creationDate) {
    this.creationDate = creationDate;
  }

  public Date getActivationDate() {
    return activationDate;
  }

  public void setActivationDate(Date activationDate) {
    this.activationDate = activationDate;
  }

  public ArrayList<ContactPerson> getContactPeople() {
    return contactPeople;
  }

  public void setContactPeople(ArrayList<ContactPerson> contactPeople) {
    this.contactPeople = contactPeople;
  }

  @Override
  public String toString() {
    return "Customer{" +
      "id=" + id +
      ", name='" + name + '\'' +
      ", creationDate=" + creationDate +
      ", activationDate=" + activationDate +
      ", contactPeople=" + contactPeople +
      '}';
  }
}
And now our client's code need to be refactored, too:
public class CustomerService {

  public Customer createCustomer(String name,
                                 ArrayList<ContactPerson> contactPeople) {
    if(contactPeople == null) {
      throw new IllegalArgumentException("Contact people list cannot be null");
    }
    if (StringUtils.isEmpty(name)) {
      throw new IllegalArgumentException("Name cannot be empty");
    }
    final Customer customer = new Customer();
    customer.setId(Sequence.nextValue());
    customer.setCreationDate(new Date());
    customer.setName(name);
    customer.setContactPeople(contactPeople);
    return customer;
  }

  public ContactPerson createContactPerson(String email) {
    final ContactPerson contactPerson = new ContactPerson();
    contactPerson.setId(Sequence.nextValue());
    contactPerson.setEmail(email);
    return contactPerson;
  }

  public void activateCustomer(Customer customer) {
    customer.setActivationDate(new Date());
  }

  public boolean isCustomerActive(Customer customer) {
    return customer.getActivationDate() != null;
  }

  public void addContactPerson(Customer customer, ContactPerson contactPerson) {
    customer.getContactPeople().add(contactPerson);
  }

  public void removeContactPerson(Customer customer, long contactPersonId) {
    customer.getContactPeople().removeIf(it -> it.getId() == contactPersonId);
  }
}

You may think now that we are done - our fields are private, accessors and mutators cover implementation details, right? Well, it is a common mistake that we treat objects as data containers. We start with defining a set of fields, and afterwards we declare corresponding getters and setters to each and every field in a class. Then we put the whole logic into some service class making our entity a dumb data structure. As long as a class can manage the values of its fields (e.g. there is no need to call a repository or some external system) it should be done inside this class. In other words, every class should encapsulate both instance fields and business methods, which are nothing more than an abstraction of a real-life domain object, hermetizing implementation details as much as possible. You see - OOP is about composing all paradigms together. Now let's try to answer a few questions, bearing in mind previously defined example's business requirements:

ContactPerson:
  1. Do I really need getters to all fields? Well, I suppose yes - we might want to present customers' contact people information. Okay then, let's leave the getters.
  2. Is ID something that I should set? Do I even need what value should I give it? No. It is something that shouldn't bother us. It should be generated automatically, e.g. by Hibernate. It means that having a setId method we break hermetization! Let's remove this mutator and put its logic to a constructor. For the simplicity of an example - we put a static sequence generator there.
Customer:
  1. Do I really need getters to all fields? Nope. Like we said in the example description, we just want to get information whether a customer is active or not. Exposing getActivationDate method forces our clients to put some logic around activationDate value. It smells badly to me. A customer is able to decide about its activation status using its own fields' values (one field actually). It suggests that we hermetize activation details inside an entity. We simply move isCustomerActive method logic into isActive method inside Customer class, like it is depicted below.
  2. Is ID something I should set? You should know the answer now - it is the same situation like with ContactPerson.
  3. Should I set creationDate in client's code? Well, as the name implies it is a timestamp of object creation and shouldn't be modifiable at any other time. Thus, giving a setter we create a threat that someone will update this value in the future or set something really strange. It is up to entity to decide what time it should set. Let's move it to the constructor, then, and forget about this mutator.
  4. Do I need to set activationDate in client's code? Well, who told you (the client) that we store activation date? Ha! We don't care about data representation again, we just want to be able to activate a customer. What we should do is to remove setActivationDate from the service and create activateCustomer method inside an entity instead.
  5. Do I really need methods that add or remove contact people from my customer in a service class? Well again, collection belongs to a Customer entity, and letting some third parties modify that collection is a crime. Let's move these methods to the entity, too.
  6. Should I keep validations in service? In this case we can validate params without calling external services or resources, so the answer is no. Every condition that must be fulfilled while creating or setting a field should be hermetized inside the entity (in constructors and/or mutators), so that clients don't need to worry about performing such checks. Thus, we will have consistent conditions across all clients. Passing wrong parameters will simply cause an exception. 
Uhh, finally... that was tough. Let's see how our code looks now:

public class ContactPerson {
  private long id;
  private String email;

  public ContactPerson() {
    this.id = Sequence.nextValue();
  }

  public long getId() {
    return id;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  @Override
  public String toString() {
    return "ContactPerson{" +
      "id=" + id +
      ", email='" + email + '\'' +
      '}';
  }
}
public class Customer {
  private long id;
  private String name;
  private Date creationDate;
  private Date activationDate;
  private ArrayList<ContactPerson> contactPeople = new ArrayList<>();

  public Customer() {
    this.id = Sequence.nextValue();
    this.creationDate = new Date();
  }

  public long getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    if (StringUtils.isEmpty(name)) {
      throw new IllegalArgumentException("Name cannot be empty");
    } else {
      this.name = name;
    }
  }

  public Date getCreationDate() {
    return creationDate;
  }

  public ArrayList<ContactPerson> getContactPeople() {
    return contactPeople;
  }

  public void setContactPeople(ArrayList<ContactPerson> contactPeople) {
    if (contactPeople == null) {
      throw new IllegalArgumentException("Contact people list cannot be null");
    } else {
      this.contactPeople = contactPeople;
    }
  }

  public void activate() {
    this.activationDate = new Date();
  }

  public boolean isActive() {
    return this.activationDate != null;
  }

  public void addContactPerson(ContactPerson contactPerson) {
    this.contactPeople.add(contactPerson);
  }

  public void removeContactPerson(long contactPersonId) {
    this.contactPeople.removeIf(it -> it.getId() == contactPersonId);
  }

  @Override
  public String toString() {
    return "Customer{" +
      "id=" + id +
      ", name='" + name + '\'' +
      ", creationDate=" + creationDate +
      ", activationDate=" + activationDate +
      ", contactPeople=" + contactPeople +
      '}';
  }
}
public class CustomerService {

  public Customer createCustomer(String name, ArrayList<ContactPerson> contactPeople) {
    final Customer customer = new Customer();
    customer.setName(name);
    customer.setContactPeople(contactPeople);
    return customer;
  }

  public ContactPerson createContactPerson(String email) {
    final ContactPerson contactPerson = new ContactPerson();
    contactPerson.setEmail(email);
    return contactPerson;
  }

}


What we can see now, is that our entities are not just simple data stores. They have a real behavior. Implementation details are hidden behind constructors, and business methods. Those business methods are nothing more than an abstraction of a real-world behavior of customer and its contact people. You can see now that abstraction, encapsulation and hermetization are complementary to each other. As a result of our refactoring, the CustomerService does nothing more than just creating objects, so we could even remove this class, and implement proper constructors or factory methods. Nice, huh?

Interface vs implementation


Let's have a look at the list of contact people. It is working, right? But don't we tell our client too much with getContactPeople and setContactPeople methods' signatures? I think we are, as we are using a concrete implementation of a java.util.List interface to declare a type of contact people collection. We are sharing yet another implementation detail here. In such situations what we should do is to use an interface (if such interface exists of course) instead - java.util.List in this case. The only place where we can refer to a specific class is object's construction. This way we both hide data representation and create a possibility to change the implementation from an ArrayList to a LinkedList if needed, without modifying our clients. Isn't it cool?

Don't think that you must always follow this approach. It is completely correct to refer to objects via class when one of the following situations apply to your case. Firstly, when you hava a class that does not implement any interface - then you simply have no choice, and must use class as a type.Secondly, when a class belongs to some class hierarchy, then it is recommended to refer to an object via the base class (usually an abstract one). And finally, your class might implement an interface, but contain some additional methods, not existing in mentioned interface. If and only if your client's code need to call this extra methods - then you need to refer to object via this class instead of using its interface.

It is all about providing both hermetization and flexibility. Let's have a look at Customer class now:
public class Customer {
  private long id;
  private String name;
  private Date creationDate;
  private Date activationDate;
  private List<ContactPerson> contactPeople = new ArrayList<>();

  public Customer() {
    this.id = Sequence.nextValue();
    this.creationDate = new Date();
  }

  public long getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    if (StringUtils.isEmpty(name)) {
      throw new IllegalArgumentException("Name cannot be empty");
    } else {
      this.name = name;
    }
  }

  public Date getCreationDate() {
    return creationDate;
  }

  public List<ContactPerson> getContactPeople() {
    return contactPeople;
  }

  public void setContactPeople(List<ContactPerson> contactPeople) {
    if (contactPeople == null) {
      throw new IllegalArgumentException("Contact people list cannot be null");
    } else {
      this.contactPeople = contactPeople;
    }
  }

  public void activate() {
    this.activationDate = new Date();
  }

  public boolean isActive() {
    return this.activationDate != null;
  }

  public void addContactPerson(ContactPerson contactPerson) {
    this.contactPeople.add(contactPerson);
  }

  public void removeContactPerson(long contactPersonId) {
    this.contactPeople.removeIf(it -> it.getId() == contactPersonId);
  }

  @Override
  public String toString() {
    return "Customer{" +
      "id=" + id +
      ", name='" + name + '\'' +
      ", creationDate=" + creationDate +
      ", activationDate=" + activationDate +
      ", contactPeople=" + contactPeople +
      '}';
  }
} 

toString()


It might look trivial to override default toString() method, but my experience shows that the way you print your object details is very vital. First of all, there might be some crazy guy that will write an application reading your logs, parsing them and calculating something - yep, I saw that on production. Secondly, lots of people have access to our log files and may read some sensitive information. It means that toString() method should be implemented with the same attention like an API. It should expose only those information, that are accessible programmatically. It is a common mistake that we just hit "Generate toString()" in our IDE, because it usually creates a method printing all your private fields and breaking hermetization by publishing all information about data representation. We have one violation of this rule in Customer class, then. Below you can see how our toString() method should look like:

public class Customer {
  ...

  @Override
  public String toString() {
    return "Customer{" +
      "id=" + id +
      ", name='" + name + '\'' +
      ", creationDate=" + creationDate +
      ", active=" + isActive() + //activation date no longer here!
      ", contactPeople=" + contactPeople +
      '}';
  }
} 


equals() and hashCode()


Another couple of methods common for all objects are equals() and hashCode(). They are also strongly connected with OOP principles, as they are part of your API. Each time when objects of your class are considered to be compared or play the role of a key in some data structure, and their equality is based on some logical assumptions, then you should override Object's default equals() method. It is said that if you can do something inside your class or a library - do it there - don't force your clients to implement it on their own, because you will spread the logic outside of the class and break the hermetization. This problem is similar to what we described in Access control, accessors, mutators chapter, while moving activateCustomer() and isCustomerActive() methods from service to Customer class. Of course you should also remember that overriding equals() implies necessity of implementing hashCode(), too. As soon as you have both methods, your clients doesn't have to worry about deciding how they should compare objects, or wondering if they can use them in a hash map - you hide (hermetize) it inside your class. Below you will find out how equals() and hashCode() could look like in our example (let's assume that all instance fields define object's identity).

Please note that the description of rules which should be followed while implementing equals() and hashCode() are out of the scope of this article.
public class ContactPerson {

  ...
    
  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    final ContactPerson that = (ContactPerson) o;

    if (id != that.id) return false;
    return email != null ? email.equals(that.email) : that.email == null;
  }

  @Override
  public int hashCode() {
    int result = (int) (id ^ (id >>> 32));
    result = 31 * result + (email != null ? email.hashCode() : 0);
    return result;
  }

}

public class Customer {

  ...
  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    final Customer customer = (Customer) o;

    if (id != customer.id) return false;
    if (name != null ? !name.equals(customer.name) : customer.name != null) return false;
    if (creationDate != null ? !creationDate.equals(customer.creationDate) : customer.creationDate != null) return false;
    if (activationDate != null ? !activationDate.equals(customer.activationDate) : customer.activationDate != null) return false;
    return contactPeople != null ? contactPeople.equals(customer.contactPeople) : customer.contactPeople == null;
  }

  @Override
  public int hashCode() {
    int result = (int) (id ^ (id >>> 32));
    result = 31 * result + (name != null ? name.hashCode() : 0);
    result = 31 * result + (creationDate != null ? creationDate.hashCode() : 0);
    result = 31 * result + (activationDate != null ? activationDate.hashCode() : 0);
    result = 31 * result + (contactPeople != null ? contactPeople.hashCode() : 0);
    return result;
  }
}

Object references


When we operate on objects, we pass their references back and forth, especially when we pass an object as a method parameter or return it as a method's call result. Having a reference to a mutable object we can easily update its state. It means that if it is a reference to an instance field of some other object - we may break its hermetization. Let's have a look at our example. Imagine a situation, when our client calls getCreationDate() method like below:
Date creationDate = customer.getCreationDate();
creationDate.setTime(1504259400000L);

Did we just find a way of changing the state of our Customer object not even calling any of its mutators? Exactly. One of the possibilities to defend ourselves from this kind of threats is using immutable objects (check-out next chapter). Here we will focus on another option, then, that is defensive copying. Defensive copying is about returning copies (references to copies - to be precise) of our mutable instance fields and working on copies of objects passed as constructor or mutator parameters.

Well, in order to secure our creationDate field we will produce a copy. Here are two possible solutions:

  1. Cloning - it is a para-Java mechanism of creating objects without using constructors. There are lots of dangerous things around it, that won't be covered in detail here. It is considered as not-safe and we should avoid it but I also think that we should be aware of what can be possibly done via this technique. In a big short, it is about calling object's protected clone() method. In most cases, classes that enable cloning provide a public equivalent of clone(). What you need to know is that you should use it for defensive copying only if the class is declared final (nobody can extend it). Why is that? It is because there is a real threat that a subclass overrides clone() method which does both cloning and registering reference to original object somewhere, and we will lose hermetization (more about inheritance in furhter chapter) You must be also aware that clone() does just a shallow copy based on an assignment, which means that all instance fields will be initialized with = operator. Thus, if the object you are copying has an instance field which is a reference to some other object, this reference will be copied one to one (instance field of the object's clone will point to the same place in memory - any change within this object may corrupt all clones, unless you implement a deep cloning!). Now, please take a look at a sample cloning (don't use it with Date in a real life, as Date is not a final class):
    public Date getCreationDate() {
      return (Date) creationDate.clone();
    }
    

  2. Copying via constructor or factory method (which may be called a copy constructor) - this is a quick and safe method, free from threats carried by clone(), where you can fully control creation process yourself.
    public Date getCreationDate() {
      return new Date(creationDate.getTime());
    }
    

The same problem refers to the contactPeople collection. Whatever mutable collection you expose to the outter world, anyone can modify it freely without any notice. It means that we should neither return reference to the collection nor save such reference to our instance field within a setter. There are plenty of methods to perform the shallow copy of a collection (shallow in this case means that we will create a completely different collection object, but containing the same references to content elements!). Defensive copying for accessor method is rather straightforward. We could simply use Collections API like below:
public List<ContactPerson> getContactPeople() {
  return Collections.unmodifiableList(contactPeople);
}

Regarding mutator, we could either remove it and force our clients to use add/remove methods (addContactPerson/removeContactPerson) or make a shallow copy manually:
public void setContactPeople(List<ContactPerson> contactPeople) {
  if (contactPeople == null) {
    throw new IllegalArgumentException("Contact people list cannot be null");
  } else {
    this.contactPeople = new ArrayList<>(contactPeople);
  }
}

You should see now that the problem we face here is that (despite defensive copying of collection) we keep references to all elements and enable our clients to modify them. We could discuss now whether shallow copy gives a real hermetization or not, and... it depends. If we have references to immutable objects (please refer to further chapter) - we don't need to worry about hermetiaztion violations during copying. Well, immutables don't even need to be copied at all! If an object is mutable, though, then changing its state means changing indirectly the state of all objects containing its reference. Sometimes when we need to store a reference to a mutable object, we simply cannot copy all its fields. We have a perfect example of that in our code - is there a way of copying id field without using reflection? There is none, as we have id field generated automatically inside the constructor and there is no setter available. Now it is the moment where you should ask: okay, so why don't we restore setId methods? Personally, I consider it as a bad idea, because cloning is a very low level procedure, and it shouldn't influence our abstraction and hermetization. Thus, to workaround this problem we could e.g. create a private constructor that accepts all fields as parameters and provide our own copy() method that would call it and return a proper copy (you see, no reflection needed, no hermetization violations). Take a look:
public class ContactPerson {
  private long id;
  private String email;

  private ContactPerson(long id, String email) {
    this.id = id;
    this.email = email;
  }

  ...
  public ContactPerson copy() {
    return new ContactPerson(this.id, this.email);
  }
}

As soon as we have the ability to make a copy of the elements from our collection we can easily make deep copies inside getter and setter:
public List<ContactPerson> getContactPeople() {
  return this.contactPeople.stream().map(ContactPerson::copy).collect(toList());
}

public void setContactPeople(List<ContactPerson> contactPeople) {
  if (contactPeople == null) {
    throw new IllegalArgumentException("Contact people list cannot be null");
  } else {
    this.contactPeople = contactPeople.stream()
      .map(ContactPerson::copy).collect(toList());
  }
}

If we have a collection of objects of type that we have no authority to modify (e.g. as it comes from some external library), we should just perform a shallow copy and advise other programmers with a proper comment not to mutate the state of these objects.

Inheritance


Inheritance breaks hermetization! Every subclass is based on the logic encapsulated in its superclass, right? In order to work properly, a subclass needs to call its parent's super methods, which means it depends on implementation details of the predecessor. Now a superclass may change, and those changes influence all its subclasses. As a consequence, every alteration might require changes in children classes. Let me show you an example. Let's imagine, that we want to store a number of contact people in an instance variable inside a subclass of a Customer (yes, I know it is just a size() of our collection, but I want to visualise the problem) - let's call it a SpecialCustomer.
public class SpecialCustomer extends Customer {
  private int numberOfContactPeople = 0;

  @Override
  public void setContactPeople(List<ContactPerson> contactPeople) {
    numberOfContactPeople = contactPeople.size();
    super.setContactPeople(contactPeople);
  }

  @Override
  public void addContactPerson(ContactPerson contactPerson) {
    super.addContactPerson(contactPerson);
    numberOfContactPeople++;
  }

  public int getNumberOfContactPeople() {
    return numberOfContactPeople;
  }
}

And here we have a simple test, where we create SpecialCustomer setting one-element ContactPerson list:
@Test
public void specialCustomerShouldHaveContactPeopleCounterEqualToOne() {
  //given
  final ContactPerson contactPerson = 
    new ContactPerson("Steve", "Harris", "steve@gmail.com");
  final List<ContactPerson> contactPeople = new ArrayList<>();
  contactPeople.add(contactPerson);

  //when
  final SpecialCustomer specialCustomer = new SpecialCustomer();
  specialCustomer.setContactPeople(contactPeople);

  //then
  assertEquals(1, specialCustomer.getNumberOfContactPeople());
}

And what we get after running this test is:
java.lang.AssertionError: 
Expected :1
Actual   :2

The reason is that we didn't know, that setContactPeople method from Customer class calls addContactPerson inside, so our counter gets incremented twice. Hermetization of our subclass is broken by the dependency to its parent, and it is a clear example of a strong and dangerous coupling that inheritance bears. Ok, so how to deal with it?

Well, we could of course override every public method and put a desired logic in subclass without calling super methods, but this clearly isn't something that inheritance is for, and of course, we might not be aware e.g. about validations that are implemented in our super class. Another idea might be to use inheritance only when we want to add new methods, not overriding existing ones. Great, but if a method of the same signature is added to the base class, then the problem is back. What if a parent class has some errors? Then we populate all this errors to its children. Okay, I won't keep you in suspense anymore - you should prefer composition over inheritance. We won't discuss this pattern further, but as you know the threats connected with inheritance I would rather like to point out, that if we see a possibility of breaking hermetization, and we don't think our class should be extendable, we should declare it final (and we will do so with our example). If it is not the case, then we should declare as many methods final as possible and document exactly how each method should be overriden properly and hope that other programmers will stick to that rules.

Immutables


We had said it many times before that when we have immutable objects, we don't have to worry about hermetization issues. Sounds great, huh? What are those immutables, then? As the name implies, these are objects that cannot be modified once they are created. It means that they have one, consistent state throughout their lifecycle, and thus they may be safely shared among numerous threads. In terms of hermetization it is an essence of hiding and securing internals. Here are the features that immutable class must provide:

  • All instance fields are private
  • No mutators (setters) - there shouldn't be any possibility of changing the state of existing object
  • Any method that is supposed to change a state creates the object's copy with a properly updated fields
  • No method can be overriden - it is about dealing with threats carried with inheritance
  • All instance fields should be declared final, and thus, should be initialized inside constructor
  • Access to all mutable instance fields must be secured with defensive copying mechanism
As you can see, all those features reflect our previous discussion. Unless there is a strong reason of creating modifiable classes, we should do our best to provide immutable ones. What a wonderful world would it be if we could have our projects built upon immutables only... Basically, yes, it would be, but as everything in this world it has its drawbacks, too, and we should be aware of them. Now if an object is immutable, operations that require returning a new instance might be costly in terms of memory. Imagine copying arrays of thousand of elements each time we call addToYourArray method! Another side-effect is that the "old" instance will be alive as long as something holds its reference (or GC cleans it). Sometimes making immutables is even impossible. You may e.g. use JPA that requires no-arg constructor and you simply cannot declare your fields final and instantiate them at creation time. If we cannot make our classes immutable we should declare as many fields final as possible to keep the hermetization and security at the highest possible level.

When talking about immutables, it is also worth mentioning that immutable objects are desired to be used with so called Value Objects. Not digging deep into the topic, these are the objects that don't have any conceptual identity, and we specify them only by the state of their properties (fields). Keeping value objects immutable ones combines very good abstraction and encapsulation (by converting a logical value into an object) with hermetization, therefore securing their state (value) from any manipulations from the outside.

There are lots of good examples of immutables in core Java libraries: java.lang.String, java.math.BigInteger, java.time.ZonedDateTime. You should now know why didn't we do any defensive copy for String fields. Remember, if you only have an option - use immutables! Yes, we will do so too, we will throw Date away in favour of ZonedDateTime.

How do you think, can we make our classes pure immutable ones? Let's try it with a ContactPerson:
public final class ContactPerson {
  private final long id;
  private final String email;
 
  private ContactPerson(long id, String email) {
    this.id = id;
    this.email = email;
  }

  public long getId() {
    return id;
  }

  public String getEmail() {
    return email;
  }

  @Override
  public String toString() {
    return "ContactPerson{" +
      "email='" + email + '\'' +
      '}';
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    final ContactPerson that = (ContactPerson) o;

    if (id != that.id) return false;
    return email != null ? email.equals(that.email) : that.email == null;
  }

  @Override
  public int hashCode() {
    int result = (int) (id ^ (id >>> 32));
    result = 31 * result + (email != null ? email.hashCode() : 0);
    return result;
  }

  public ContactPerson copy() {
    return new ContactPerson(this.id, his.email);
  }

  public static ContactPerson valueOf(String email) {
    return new ContactPerson(Sequence.nextValue(), email);
  }
}

  • All instance fields private - checked
  • No mutators (setters) - checked
  • Any method that is supposed to change a state must create a copy with a properly updated fields - no such methods
  • No method can be overriden - checked
  • All instance fields final - checked
  • Mutable instance fields must be secured with defensive copying - checked
Success! We made ContactPerson an immutable class. You can see here that we added a static valueOf factory method instead of a public constructor, which gives a convenient way of creating objects (no more new operator) and gives another level of hermetization - client does not need to know what constructors are used inside.

Now can we do the same to a Customer class? Yes, but with a few regards. Firstly, if we declare activationDate final, we won't be able to activate the same object - we will need to create its copy. Similarily, we will need to clone whole customer while adding or removing any contact person. If we are okay with that, let's see how it works:

public class Customer {
  private final long id;
  private final String name;
  private final ZonedDateTime creationDate;
  private final ZonedDateTime activationDate;
  private final List<ContactPerson> contactPeople;
  
  private Customer(long id, String name, ZonedDateTime creationDate,
                   ZonedDateTime activationDate, List<ContactPerson> contactPeople) {
    if (contactPeople == null) {
      throw new IllegalArgumentException("Contact people list cannot be null");
    }
    if (StringUtils.isEmpty(name)) {
      throw new IllegalArgumentException("Name cannot be empty");
    }
    this.id = id;
    this.name = name;
    this.creationDate = creationDate;
    this.activationDate = activationDate;
    this.contactPeople = new ArrayList<>(contactPeople);
  }

  public long getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public ZonedDateTime getCreationDate() {
    return creationDate;
  }

  public List<ContactPerson> getContactPeople() {
    return Collections.unmodifiableList(contactPeople);
  }

  public Customer activate() {
    return new Customer(this.id, this.name, this.creationDate,
      ZonedDateTime.now(), new ArrayList<>(this.contactPeople));
  }

  public boolean isActive() {
    return this.activationDate != null;
  }

  public Customer addContactPerson(ContactPerson contactPerson) {
    final List<ContactPerson> newContactPersonList =
      new ArrayList<>(this.contactPeople);
    newContactPersonList.add(contactPerson);
    return new Customer(this.id, this.name, this.creationDate,
      this.activationDate, newContactPersonList);
  }

  public Customer removeContactPerson(long contactPersonId) {
    final List<ContactPerson> newContactPersonList =
      new ArrayList<>(this.contactPeople);
    newContactPersonList.removeIf(it -> it.getId() == contactPersonId);
    return new Customer(this.id, this.name, this.creationDate,
      this.activationDate, newContactPersonList);
  }

  @Override
  public String toString() {
    return "Customer{" +
      "id=" + id +
      ", name='" + name + '\'' +
      ", creationDate=" + creationDate +
      ", activationDate=" + activationDate +
      ", contactPeople=" + contactPeople +
      '}';
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    final Customer customer = (Customer) o;

    if (id != customer.id) return false;
    if (name != null ? !name.equals(customer.name) : customer.name != null) return false;
    if (creationDate != null ? !creationDate.equals(customer.creationDate) : customer.creationDate != null) return false;
    if (activationDate != null ? !activationDate.equals(customer.activationDate) : customer.activationDate != null) return false;
    return contactPeople != null ? contactPeople.equals(customer.contactPeople) : customer.contactPeople == null;
  }

  @Override
  public int hashCode() {
    int result = (int) (id ^ (id >>> 32));
    result = 31 * result + (name != null ? name.hashCode() : 0);
    result = 31 * result + (creationDate != null ? creationDate.hashCode() : 0);
    result = 31 * result + (activationDate != null ? activationDate.hashCode() : 0);
    result = 31 * result + (contactPeople != null ? contactPeople.hashCode() : 0);
    return result;
  }

  public static Customer valueOf(String name, List<ContactPerson> contactPeople) {
    return new Customer(Sequence.nextValue(), name, ZonedDateTime.now(),
      null, contactPeople);
  }
}

  • All instance fields private - checked
  • No mutators (setters) - checked
  • Any method that is supposed to change a state must create a copy with a properly updated fields - checked
  • No method can be overriden - checked
  • All instance fields final - checked
  • Mutable instance fields must be secured with defensive copying - checked
Please note that in getContactPeople method we got back to a shallow copy solution. This is because ContactPerson is an immutable class so we don't need to copy its objects any more. All right, we have our classes hermetized!

Serialization


It is a common thing that we send our objects throughout the network or persist them somehow (in a queue, event store, etc.). In order to convert object to some unified binary form we often use Java serialization mechanism. We are not going to describe how serialization works but rather point out its connection with hermetization.

Well, what my experience shows, there is something about serialization that makes people think that the only thing they should do is to implement Serializable interface. Unfortunately it might be illusive. Let me explain.

Deserialization restores the private state of an object. It means that we can treat readObject method as another public constructor. Thus, we cannot trust the external byte stream (like we don't trust our clients) that it will always contain proper data. If there are any validations implemented in our constructors or setters, they should be applied within readObject method, too. It will prevent us from initializing corrupted object.

Another threat that we are exposed to is that the serialized byte stream might contain so called back references to objects that are already inside the stream. If these objects are mutable, then we face the same problem like we described in Object references chapter. You should know by now, that what we should do inside readObject method is a defensive copy of all mutable objects.

In case of ContactPerson class, default serialized form of an object corresponds to its logical content, and we don't have any references to mutable objects nor validations there. As a result it is enough to simply impement Serializable interface, like below:

public final class ContactPerson implements Serializable {
  private static final long serialVersionUID = 1L;
  ...
}

In Customer class, apart from implementing Serializable interface, we need to override readObject method and both put appropriate validations and make defensive copies of all instance fields that are mutable.

public class Customer implements Serializable {
  private static final long serialVersionUID = 1L;

  private final long id;
  private final String name;
  private final ZonedDateTime creationDate;
  private final ZonedDateTime activationDate;
  private List<ContactPerson> contactPeople;

  ...

  private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
    s.defaultReadObject();
    if (contactPeople == null) {
      throw new NotSerializableException("Contact people list cannot be null");
    }
    if (StringUtils.isEmpty(name)) {
      throw new NotSerializableException("Name cannot be empty");
    }
    contactPeople = new ArrayList<>(contactPeople);
  }
}

One thing that we needed to do was removing the final keyword from contactPeople field. It is because we are doing defensive copying (shallow one) after the object is constructed - readObject works like constructor but it isn't one. Here we partially break one of the rules from immutable object definition, but having defensive copy mechanism for this field, we will still have effectively immutable object and safe deserialization, too.

Conclusions


As you could see in this long article, there is a lot of philosophy around OOP concepts, which is not that simple as it might sometimes seem to be. You had a chance to see that all OOP concepts are complementary, and overlap each other. We cannot talk about hermetization, not mentioning encapsulation, abstraction or inheritance. Here are some rules that you should follow to have hermetization in your code:

  • Create immutables when possible.
  • Keep access to instance members as restricted as possible.
  • Give your class a public access modifier only when you are sure that you want to expose it outside the package.
  • Declare accessors only to fields you want to expose to the outter world.
  • Declare modifiers only to fields that really might be changed in the future and that are not to be set automatically.
  • Give your class a behavior, so that methods reflect the abstraction, hiding data representation and other implementation details.
  • If you have instance fields that are references to mutable objects, provide defensive copying in getters, setters and constructors.
  • Try to keep your class final. If you want your class to be extended, declare as many methods final as possible, and document the class clearly.
  • Always prefer interfaces (or base classes from class hierarchy) rather than their implementations as types of fields/params/method return values.
  • Override toString() method so that it prints information accessible programmatically from the outside of a class - it is like your API.
  • If your objects are supposed to be compared to each other or used as keys in data structure, provide your own equals() and hashCode() methods.
  • Prefer composition over inheritance.
  • Put proper validations and defensive copying (if needed) inside readObject method while implementing Serializable interface.

Wednesday, 5 July 2017

Transaction synchronization and Spring application events - understanding @TransactionalEventListener

The aim of this article is to explain how @TransactionalEventListener works, how it differs from a simple @EventListener, and finally - what are the threats that we should take into account before using it. Giving a real-life example, I will mainly focus on transaction synchronization issues  not paying too much attention neither to consistency nor application event reliability. A complete SpringBoot project with described examples you will find here.

Example overview


Imagine we have a microservice which manages customers' basic information and triggers activation token generation after a customer is created. From the business perspective token generation is not an integral part of user creation and should be a separate process (this is very important assumption, which I will refer to later). To keep things simple, let's assume that a customer looks like this:
@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
    private String token;

    public Customer() {}

    public Customer(String name, String email) {
        this.name = name;
        this.email = email;
    }

    public void activatedWith(String token) {
        this.token = token;
    }

    public boolean hasToken() {
        return !StringUtils.isEmpty(token);
    }

    ...
    //getters
    //equals and hashcode
}

We have a simple spring-data-jpa repository:
public interface CustomerRepository extends JpaRepository<Customer, Long> {}

And below you can see an essence of the business problem - creating new customer (persisting it in DB) and returning it.

@Service
public class CustomerService {

    private final CustomerRepository customerRepository;
    private final ApplicationEventPublisher applicationEventPublisher;

    public CustomerService(CustomerRepository customerRepository, ApplicationEventPublisher applicationEventPublisher) {
        this.customerRepository = customerRepository;
        this.applicationEventPublisher = applicationEventPublisher;
    }

    @Transactional
    public Customer createCustomer(String name, String email) {
        final Customer newCustomer = customerRepository.save(new Customer(name, email));
        final CustomerCreatedEvent event = new CustomerCreatedEvent(newCustomer);
        applicationEventPublisher.publishEvent(event);
        return newCustomer;
    }
}

As you can see, CustomerService depends on two beans:
  1. CustomerRepository - interface for the purpose of saving customer
  2. ApplicationEventPublisher - Spring's super-interface for ApplicationContext, which declares the way of event publishing inside Spring application
Please note the constructor injection. If you are not familiar with this technique or not aware of its benefits relative to field injection, please read this article.

Remember to give -1 during the code review if there is no test included! But wait, take it easy, mine is here:

@SpringBootTest
@RunWith(SpringRunner.class)
public class CustomerServiceTest {

  @Autowired
  private CustomerService customerService;

  @Autowired
  private CustomerRepository customerRepository;

  @Test
  public void shouldPersistCustomer() throws Exception {
    //when
    final Customer returnedCustomer = customerService.createCustomer("Matt", "matt@gmail.com");

    //then
    final Customer persistedCustomer = customerRepository.findOne(returnedCustomer.getId());
    assertEquals("matt@gmail.com", returnedCustomer.getEmail());
    assertEquals("Matt", returnedCustomer.getName());
    assertEquals(returnedCustomer, persistedCustomer);

}

The test does one simple thing - checks whether createCustomer method creates a proper customer. One could say that in this kind of tests I shouldn't pay attention to implementation details (persisting entity through the repository, etc.) and rather put it in some unit test, and I would agree, but let's just leave it to keep the example clearer.

You may ask now, where is the token generation. Well, due to the business case that we are discussing, createCustomer method does not seem to be a good place to put any logic apart from simple creation of user (method name should always reflect its responsibility). In that kind of cases it might be a good idea to use the observer pattern to inform interested parties that a particular event took place. Following this considerations, you can see that we are calling publishEvent method on applicationEventPublisher. We are propagating an event of the following type:

public class CustomerCreatedEvent {

  private final Customer customer;

  public CustomerCreatedEvent(Customer customer) {
    this.customer = customer;
  }

  public Customer getCustomer() {
    return customer;
  }

  ...
  //equals and hashCode
}

Note that it is just a POJO. Since Spring 4.2 we are no longer obliged to extend ApplicationEvent and can publish any object we like instead. Spring wraps it in PayloadApplicationEvent itself.

We do also have an event listener component, like this:
@Component
public class CustomerCreatedEventListener {

    private static final Logger LOGGER = LoggerFactory.getLogger(CustomerCreatedEventListener.class);

    private final TokenGenerator tokenGenerator;

    public CustomerCreatedEventListener(TokenGenerator tokenGenerator) {
        this.tokenGenerator = tokenGenerator;
    }

    @EventListener
    public void processCustomerCreatedEvent(CustomerCreatedEvent event) {
        LOGGER.info("Event received: " + event);
        tokenGenerator.generateToken(event.getCustomer());
    }
}

Before we discuss this listener, let's briefly look at TokenGenerator interface:
public interface TokenGenerator {

    void generateToken(Customer customer);
}


and its implementation:
@Service
public class DefaultTokenGenerator implements TokenGenerator {

    private final CustomerRepository customerRepository;

    public DefaultTokenGenerator(CustomerRepository customerRepository) {
        this.customerRepository = customerRepository;
    }

    @Override
    public void generateToken(Customer customer) {
        final String token = String.valueOf(customer.hashCode());
        customer.activatedWith(token);
        customerRepository.save(customer);
    }
}


We are simply generating a token, setting it as customer's property and updating the entity in database. Good, let's update our test class now, so that it checks not only the customer creation but also token generation.
@SpringBootTest
@RunWith(SpringRunner.class)
public class CustomerServiceTest {

    @Autowired
    private CustomerService customerService;

    @Autowired
    private CustomerRepository customerRepository;

    @Test
    public void shouldPersistCustomerWithToken() throws Exception {
        //when
        final Customer returnedCustomer = customerService.createCustomer("Matt", "matt@gmail.com");

        //then
        final Customer persistedCustomer = customerRepository.findOne(returnedCustomer.getId());
        assertEquals("matt@gmail.com", returnedCustomer.getEmail());
        assertEquals("Matt", returnedCustomer.getName());
        assertTrue(returnedCustomer.hasToken());
        assertEquals(returnedCustomer, persistedCustomer);
    }

}

@EventListener


As you can see, we have moved token generation logic into a separate component which is good (note the assumption at the beginning of the previous chapter), but do we have a real separation of concerns? Nope. @EventListener registers the processCustomerCreatedEvent as the listener of CustomerCreatedEvent but it is called synchronously within the bounds of the same transaction as CustomerService. It means, that if something goes wrong with token generation - customer won't be created. Is this the way it should really work? Surely not. Before we generate and set token, we would rather have a customer already created and saved in database (committed). Now this is the time to introduce @TransactionalEventListener annotation.

@TransactionalEventListener - transaction synchronization

 

@TransactionalEventListener is an @EventListener enhanced with the ability to collaborate with surrounding transaction's phase. We call this a transaction synchronization - in other words it is a way of registering callback methods to be invoked when transaction is being completed. Synchronization is possible within following transaction phases (phase attribute):
  • AFTER_COMMIT (default setting) - specialization of AFTER_COMPLETION, used when transaction has successfully committed
  • AFTER_ROLLBACK - specialization of AFTER_COMPLETION, used when transaction has rolled back
  • AFTER_COMPLETION - used when transaction has completed (regardless the success)
  • BEFORE_COMMIT - used before transaction commit
When there is no transaction running then the method annotated with @TransactionalEventListener won't be executed unless there is a parameter fallbackExecution set to true.

Good, looks like this is something that we are looking for! Let's change @EventListener annotation with @TransactionalEventListener in CustomerCreatedEventListener, then:
@TransactionalEventListener
public void processCustomerCreatedEvent(CustomerCreatedEvent event) {
    LOGGER.info("Event received: " + event);
    tokenGenerator.generateToken(event.getCustomer());
}

We need to check now if everything works as we expect - let's run our test:
 
java.lang.AssertionError: 
Expected :Customer{id=1, name='Matt', email='matt@gmail.com', token='1575323438'}
Actual   :Customer{id=1, name='Matt', email='matt@gmail.com', token='null'}
 
Why is that? What have we missed? I tell you what: we spent too little time on analysing how transaction synchronization works. Now the crucial thing is that we have synchronized token generation with the transaction after it has been committed - so we shouldn't even expect that anything will be committed again! Javadoc for afterCommit method of TransactionSynchronization interface says it clearly:

The transaction will have been committed already, but the transactional resources might still be active and accessible. As a consequence, any data access code triggered at this point will still "participate" in the original transaction, allowing to perform some cleanup (with no commit following anymore!), unless it explicitly declares that it needs to run in a separate transaction. Hence: Use {@code PROPAGATION_REQUIRES_NEW} for any transactional operation that is called from here.

As we have already stated, we need to have a strong separation of concerns between a service call and an event listener logic. This means that we can use the advice given by Spring authors. Let's try annotating a method inside DefaultTokenGenerator:
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void generateToken(Customer customer) {
    final String token = String.valueOf(customer.hashCode());
    customer.activatedWith(token);
    customerRepository.save(customer);
}

If we run our test now, it passes!

Caveat: We are discussing interacting with AFTER_COMMIT phase only, but all these considerations apply to all AFTER_COMPLETION phases. In case of BEFORE_COMMIT phase none of the above problems should worry you, although you need to make a conscious decision whether your listener's code should really be executed in the same transaction.

Asynchronous execution


What if a token generation is a long lasting process? If it is not an essential part of creating a customer, then we could make one step forward and make our @TransactionalEventListener-annotated method asynchronous one (via anotating it with @Async). Asynchronous call means that we will execute listener's processCustomerCreatedEvent in a separate thread. Bearing in mind that a single transaction in Spring framework is by default thread-bounded, we won't need autonomous transaction in DefaultTokenGenerator anymore.

Good, let's write a test for this case:
@SpringBootTest
@RunWith(SpringRunner.class)
@ActiveProfiles("async")
public class CustomerServiceAsyncTest {

  @Autowired
  private CustomerService customerService;

  @Autowired
  private CustomerRepository customerRepository;

  @Test
  public void shouldPersistCustomerWithToken() throws Exception {
      //when
      final Customer returnedCustomer = customerService.createCustomer("Matt", "matt@gmail.com");

      //then
      assertEquals("matt@gmail.com", returnedCustomer.getEmail());
      assertEquals("Matt", returnedCustomer.getName());

      //and
      await().atMost(5, SECONDS)
          .until(() -> customerTokenIsPersisted(returnedCustomer.getId()));
  }

  private boolean customerTokenIsPersisted(Long id) {
      final Customer persistedCustomer = customerRepository.findOne(id);
      return persistedCustomer.hasToken();
  }
}

The only thing that differentiates this test from the previous one is that we are using Awaitility library (a great and powerful tool) in order to await for the async task to complete. We also wrote a simple customerTokenIsPersisted helper method to check if token was properly set. And surely test passes brilliantly!

Caveat: I don't recommend performing any async tasks in BEFORE_COMMIT phase as you won't have any guarantee that they will complete before producer's transaction is committed.

Conclusions

 

@TransactionalEventListener is a great alternative to @EventListener in situations where you need to synchronize with one of transaction phases. You can declare listeners as synchronous or asynchronous. You need to keep in mind that with synchronous call you are by default working within the same transaction as the event producer. In case you synchronize to AFTER_COMPLETION phase (or one of its specializations) you won't be able to persist anything in the database as there won't be commit procedure executed anymore. If you need to commit some changes anyway, you can  declare an autonomous transaction on event listener code. BEFORE_COMMIT phase is much simplier, because commit will be performed after calling event listeners. With asynchronous calls you don't have to worry about declaring autonomous transactions, as Spring's transactions are by default thread-bounded (you will get a new transaction anyway). It is a good idea if you have some long running task to be performed. I suggest using asynchronous tasks only when synchronizing to AFTER_COMPLETION phase or one of its specializations. As long as you don't need to have your event listener's method transactional - described problems shouldn't bother you at all.

Further considerations


In a real-life scenarios numerous other requirements might occur. For example you might need to both persist customer and send an invitation email like it is depicted below:
@Component
public class CustomerCreatedEventListener {

    private final MailingFacade mailingFacade;
    private final CustomerRepository customerRepository;

    public CustomerCreatedEventListener(MailingFacade mailingFacade, CustomerRepository customerRepository) {
        this.mailingFacade = mailingFacade;
        this.customerRepository = customerRepository;
    }

    @EventListener
    public void processCustomerCreatedEvent(CustomerCreatedEvent event) {
        final Customer customer = event.getCustomer();
        // sending invitation email
        mailingFacade.sendInvitation(customer.getEmail());
    }
}

Imagine a situation when an email is sent successfully, but right after it, our database goes down and it is impossible to commit the transaction (persist customer) - thus, we lose consistency! If such situation is acceptable within your business use case, then it is completely fine to leave it as it is, but if not then you have a much more complex problem to solve. I intentionally haven't covered consistency end event reliability issues here. If you want to have a broader picture of how you could possibly deal with such situations, I recommend reading this article.