The Pimp My Library Pattern
Tags: oop, java, scala, kotlin
Published: 2019-12-17 08:05:58

---
title: "The Pimp My Library Pattern"
published: true
description: "Which is the main problem you have as a developer when you use libraries that you don't own? You can't change them. If something is missing in the public API of a library, there is no chance to extend it. Using some excellent old object-oriented programming, you can overcome this problem by writing much boilerplate code. In the JVM ecosystem, modern programming languages, such as Scala, Kotlin or Groovy, try to give a solution to library extension, the Pimp My Library Pattern."
tags: oop, java, scala, kotlin
cover_image: https://res.cloudinary.com/jerrick/image/upload/fl_progressive,q_auto,w_1024/lfpjhjke9yeawqo1rfos.jpg
---

*Originally posted on: [Big ball of mud](http://rcardin.github.io/)*

Which is the main problem you have as a developer when you use libraries that you don't own? You can't change them. If something is missing in the public API of a library, there is no chance to extend it. Using some excellent old object-oriented programming, you can overcome this problem by writing much boilerplate code. In the JVM ecosystem, modern programming languages, such as Scala, Kotlin or Groovy, try to give a solution to library extension, the Pimp My Library Pattern. Let's go, and see what I am talking.

## The problem

Let's begin with a very extreme example. Imagine you want to add a method `Integer` type in Java that allows you to translate an int into an instance of the `java.time.Period` class. For whom that don't know this class, a `Period` represents a time, using days, months, years.

All that we want to achieve is having something like the following.

```java 
final Period days = Integer.valueOf(42).days();
```

In more evolved languages, such as Scala or Kotlin, the above statement would look like the following.

```scala
val days = 42.days;
```

In Java, you have no many such possibilities to achieve the goal. Since we cannot nor we want to modify directly the `Integer` type, and [we do not want to use inheritance on a concrete type](http://rcardin.github.io/design/programming/oop/fp/2018/07/27/the-secret-life-of-objects-part-2.html), the only remaining possibility is to implement a method somewhere that receives in input an `Integer` and returns a `Period`.

```java 
class Integer2Period {
    private Integer integer;
    Integer2Period(int integer) {
        this.integer = integer;
    }
    Period days() {
        return Period.ofDays(integer);
    }
}
var days = new Integer2Period(42).days();
```

Meh. We used a _wrapper_ or some variance of the Object Adapter Pattern, but we are very far from the objective we originally had.

Let's see how modern JVM languages, such as Kotlin, Scala and Groovy answer this problem.

## Scala

Scala was the language that first introduced the _Pimp My Library_ pattern. The pattern was introduced by the Scala language's dad, Martin Odersky, in his article [Pimp my Library](https://www.artima.com/weblogs/viewpost.jsp?thread=179766), in the far 2006. 

The pattern allows extending a type adding methods to it without using any form of inheritance. Using the pattern, we can add a method to the `Int` type without extending from it.

The Scala language implements the pattern through _implicit conversions_. First of all, we need to declare an `implicit` class that allows the compiler to convert our primary type into a new type that adds the method we want to have. In our case, the primary type is the `Int` type.

```scala
package object extension { 
  implicit class ExtendedInt(val integer: Int) extends AnyVal {
    def days = Period.ofDays(integer)
  }
}
```

Inside the package `extension`, or in any package, explicitly importing the package `extension`, we can use the method defined in the type `ExtendedInt` as a method defined for the `Int` type.

```scala
val days = 42.days;
```

The tricks that make the magic are two: 

1. The declaration of the implicit type inside a package object forces the compiler to automatically import the `ExtendedInt` type in all the files that belong from it.
2. The class `ExtendedInt` is declared as `implicit`.
3. The class `ExtendedInt` is a subclass of the type `AnyVal`. From Scala 2.10, extending from `AnyVal` allows the compiler to perform some code optimisations. It's called _Custom Value Classes_.

If I don't interpret the result of the `javap` command wrongly on the `.class` files generated by the Scala compiler, Scala adopts a conversion to the bytecode of the implicit class similar to the _wrapper_ approach I gave for Java.

```bytecode
public final class org.rcardin.extension.package$ExtendedInt {
  public int integer();
  public java.time.Period days();
  public int hashCode();
  public boolean equals(java.lang.Object);
  public org.rcardin.extension.package$ExtendedInt(int);
}
```

The method `int integer()` is a getter of a private attribute and the constructor of the class takes as input a variable of type `int`. The decompiled implicit Scala class has the same structure as the Java class `Integer2Period`.

The standard library extensively uses the pattern. All the type defined with the suffix `Ops` implement the pattern. Have a look at the [`StringOps`](https://www.scala-lang.org/api/2.12.2/scala/collection/immutable/StringOps.html) type for an example.

## Kotlin

Also, the newbie JVM-based language, Kotlin, has its implementation of the _Pimp my library_ pattern. In Kotlin slang, the pattern implementation it's called _Extension functions_. The pattern was introduced in the language to contrast the fact that the majority of the libraries a Kotlin developer could use are in Java, and not in Kotlin.

The syntax needed to declare an _extension function_ is less verbose than the syntax used in the Scala language ( :O ).

```kotlin
fun Integer.days(): Period = Period.ofDays(this)
```

In our example, the `Integer` type is also called the _receiver type_. Whereas, the `this` reference on the right of the assignment symbol is called the _receiver object_. The `this` reference refers to the integer instance on which the extension method is called. To preserve encapsulation, you can access only to the public methods of the receiver object.

The compiler does not import the extension methods by default. As any other Kotlin entity, you need to import them before using explicitly.

Under the hood, the compiler translates every extension method in a `static` method having the receiver object as its first parameter. The name of the enclosing class is equal to the name of the file that declares the extension function.

Suppose that we declared the `Integer.days` function in a file called IntegerUtil.kt, then the Kotlin compiler compile our code into a static method inside a class called `IntegerUtilKt`.

```java 
class IntegerUtilKt {
    public static Period days(Integer receiver) {
        return Period.ofDays(receiver);
    }
}
```

It's very similar to the solution we gave for the Java language.

The translation that the Kotlin compiler performs on extension functions allows us to call them also on nullable types. No method is called directly on the receiver object passed as the first parameter to a static method.

So, extension functions and the Kotlin type system allow us to declare something like the following.

```kotlin
fun String?.isNullOrBlank(): Boolean = this == null || this.isBlank()
```

You can safely use the above method in _if-statements_, to control if a nullable object contains a `null` reference or not.

```kotlin
val possiblyEmptyString: String? = // Obtaining the string reference
if (possiblyEmptyString.isNullOrBlank()) { // No NullPointerException!!!
    // Do something smart
}
```

Awesome. Kotlin continues to surprise me every day.

## Conclusions

Sometimes a library contains almost all that you need, but it lacks some feature that you desire. Extension using the regular object-oriented mechanisms is not a possibility in such cases. Many JVM-based languages give you the possibility to achieve the goal to add the methods you need to an existing library without modifying it. 

The _Pimp my library_ pattern is the mechanism to make the magic happen. Scala uses _implicit objects_ and conventions to implement such a pattern. In contrast, Kotlin has a more natural approach that integrates very well with the Kotlin type system concerning the handling of null references.

Moreover, let's say that also Groovy implements the pattern, using [Extensions](https://www.baeldung.com/groovy-metaprogramming#extensions) and [Categories](https://www.baeldung.com/groovy-categories).

Where are you Java? Will you ever join the party?

---

If you want, download the code of the Scala example from my repository on GitHub: [pimp-my-library](https://github.com/rcardin/pimp-my-library).

## References

- [Pimp my Library (M. Odersky)](https://www.artima.com/weblogs/viewpost.jsp?thread=179766)
- [Pimp My Library (D. Sfregola)](https://danielasfregola.com/2015/06/08/pimp-my-library/)
- [Chapter 3: Defining and calling function. Kotlin in Action, Dmitry Jemerov and Svetlana Isakova, 2017,
Manning Publications](https://www.manning.com/books/kotlin-in-action)
- [Groovy Extensions](https://www.baeldung.com/groovy-metaprogramming#extensions)
- [Groovy Categories](https://www.baeldung.com/groovy-categories)