Programming to an interface

Interface Message Processor Front Panel

There are many types of interfaces

Program to an interface, not an implementation.

This short sentence, introduced in 1994 by the GoF, is one of the most important design principles in software development. However, I have seen several projects where this principle has gone wrong. Here’s why:

Interface vs. Interface

If you come from a Java background like myself and you hear the word interface you will typically think of something like that:

Yes, that’s an interface. No doubt. However, it’s not the same interface as in “program to an interface“! Sounds strange? Not at all.

Many modern programming languages doesn’t have a keyword called “interface”. JavaScript has no interface keyword; Ruby has no interface keyword; Scala has not interface keyword; and so on… But it’s still possible to program to an interface in all of those languages.

An interface might be a language keyword and an interface might be a design principle. Don’t confuse both!

The language keyword

The language keyword interface can be found in typed languages like Java or C#. It enables the programmer to create an abstract type with multiple concrete implementations.

A consumer can use the interface without even knowing about the concrete implementations.

You should use an interface whenever you have multiple implementations. For example if you use a different persistence in production as in development or if you have an algorithm which is interchangeable.

The design principle

The design principle interface refers to lose coupling between modules or systems.

Whenever you build a larger piece of software, you will have dependencies to other systems. For example to a relational database or to a REST service. All of those dependencies represent tools for your software to fulfil its goals. Such a goal might be to manage contacts in an address bock app or to process orders in an online shop. But whatever the goal of your software is, your goal as a software developer should be to model your problem domain nice and clean.

To achieve such a clean domain layer in your application, you need to create a separation between your domain and external systems. So instead of programming to a relational database, you program to a “data store interface”. Instead of programming to a REST service, you program to a “client interface”. This will make your application independent of all dependencies and focused on its own domain. If you use MongoDB instead of a relational database tomorrow, it’s no problem. All you code is developed to an interface and doesn’t even know that there is any database behind it.

untitled-drawing

Pitfalls

So working with interfaces isn’t as easy as it sounds like. Here are some typical pitfalls in my opinion.

#1: Using an interface, but don’t program to an interface

If you want to achieve the design principle of programming to an interface, it’s very likely that you will use a language construct called interface if your programming language has such (e.g. Java). However, just using an interface keyword, doesn’t mean that you are also programming to an interface. Let’s make an example:

In the example above, your dependency (obviously a relational database) defines your interface. Because the database requires a technical ID for each entity, your interface just reflects this. It doesn’t hide the fact that you use a database, it even has the word “Database” in its name and returns database entities instead of domain objects.

By using such an interface, you don’t decouple your software from the other system. Wherever you use the interface, you will know that you work with a database and you will need to deal with the entity classes from the database layer.

#2: An interface for everything

Of course, we want to do things right. But sometimes, too much is wrong. I have seen some projects where there was an interface for (nearly) everything:

Whenever you have an interface which is a one-to-one copy of a class called ...Impl, something is wrong and you should consider if you really need this interface. There are two rules to think of:

  • Use interfaces (the language keyword) if you have multiple concrete implementations.
  • Use interfaces (the design principle) to decouple your own system from external system.

So if you have a domain service (e.g. AccountingService) there is no need to have an interface (the language keyword) for this service if you don’t have multiple types of it (e.g. CreditCardAccountingService and PayPalAccountingService). Such a service is also part of your own application, so there is no need to decouple yourself from it. There will always be just one single implementation! Our own!

Best regards,
Thomas

Using the console on Windows

I tell you a secret: I’m a Windows user. I don’t use OSX, I don’t use Linux, I use Windows. And I tell you something more: I like it 😉

Usually I develop Java or JavaScript applications which perfectly run under Windows, Linux, OSX or what so ever. So developing under Windows is no problem at all. Runtime environments, IDEs, editors – Windows has it all. However, people keep wondering how I can do the most simple task:

How do you connect to another server? Do you use Putty? – Argh, no, I just type ssh some.server.com and I’m done.

Or:

Do you use your IDE to work with GIT? Or do you have Source Tree? – Argh, no, I just type git add . and git commit -m "..." and I’m done.

But I also know, that not everybody is doing it like this. People use the weirdest tools and techniques when working under Windows. A lot of people use that f***ing small Windows CMD, Putty with its broken key-format or CygWin to be a little bit more Linux-like. But I don’t like all of these. The Windows CMD is unusable, Putty is unnecessary and CygWin is a monster you don’t need. Here is what I do.

Don’t use the Windows default CMD

The first thing I do, is to don’t use Windows’ default CMD. Why? It can’t even mark and copy things! However, there’s an easy and open-source alternative: ConEmu. ConEmu has all the simple things you expect: colors, tabs, resizable, copy-and-paste and much more. You can get it from GitHub and it even works without installation.

2016-05-21 21_51_21-Settings

Use GIT as a toolbox for Windows

The other thing I do, is to use GIT as a toolbox for Windows. When people are talking about using the console, they are actually talking about using tools. They talks about SCP, SSH or CURL like they come with their console – but they don’t! All of those things are just individual programs installed on their machine. They are not related to the command line! So why don’t install them on Windows?

If you use GIT, you already have everything you need in the bin folder (e.g. on C:\Program Files (x86)\Git\bin\):

ssh, scp, curl, cat, grep, less, sh, bash, ls, mv, cp, diff, gzip, and much more…

2016-05-21 22_09_29-Using the console on Windows – Thomas Uhrig

The only thing you need to do is to put GIT’s bin folder to your Windows variable path. You will have everything at a fingertip in your console.

2016-05-21 22_26_43-Environment Variables

Put my SSH-certificates to my user-folder

The last thing I usually do is to put my SSH-certificates to my user folder at C:\Users\tug\.ssh, so that SSH can find them.

Best regards,
Thomas

More

Anti Pattern: Don’t use Optionals for data repositories

Java 8 Optionals

Java 8 introduced a new feature call Optionals. Optionals are an easy way to force the caller of a method to deal with a possible null return value:

If you use an Optional as the return type of your method, whoever calls the method will be reminded that it might return null. If you use Optionals, you don’t need to think about NotFoundExceptions, special return types or JavaDoc comments which state that the method might return null. An Optional says more than a thousand comments!

Optionals might just postpone the problem

But an Optional doesn’t do one thing: it doesn’t answer the question what to do if there is no method result. It just postpones the problem to the caller. This might be OK if null is a quite expected result of the method, but in most cases null means something went wrong. Don’t postpone this!

An example

Nearly every application stores data. Whenever data is stored, it will be loaded again which might go wrong as the data simply couldn’t be found. That sounds like a good use case for Optionals! Let’s see how it could look like:

Nice! If there is no Person with the given ID the repository will return an empty Optional and the caller has to deal with it. Technically, this is a nice and clean solution. But from the business perspective it isn’t. The real question is: Can it happen that we look for an ID which is not present? If yes, than an Optional is a good solution, but I would doubt that in many case.

Whenever you attempt to load data by its ID, it must be present! There are hardly any cases where you guess or search for an ID. Such IDs are like references or pointers in a programming language: they must point to something and returning an ID which points to nothing is a very bad idea. A typical situation where you load data by its ID goes like this: You provide a list of data (maybe a result of a search) and you provide a detail view on a single entry. So, you show the list in your UI and on a click on of the elements, the details of ID XYZ-123 are shown. This set of data must be there! Don’t use an optional here!

Never return null

Back in the days (which means before Java 8), there was a rule which said that you shall never return null. This rule was always a bit tricky to follow as it might lead to a lot of hidden traps. People started to return empty objects, special objects, return codes and other crazy stuff. If you did this in the past and you are using Optionals now, you definitely improved! But you should still ask you, why there might be no result and if it is OK to have no result. Not only from a technical perspective but also from the business perspective.

Optional is just a new name for null.

When to use Optionals

The actual use case for Optionals is functional programming in Java 8. If you use this, you will filter, map or reduce data and you will often come to the point where there might be the possibility that no data exists. It’s a good idea to use Optionals here, as you often write this code in a fluent style. A null pointer is really ugly to handle here. But the main difference is another: You do a search or filtering which perfectly could have no result. This is the main point for using an Optional. Don’t use an Optional, because you don’t want to deal with null (you need to do it anyway later!), use it because you have a really good reason to return null.

Best regards,
Thomas

Create random test objects with Java reflection

Although Java is an object oriented language, you will often separate our data and your actual business logic. You will write POJOs, entities, domain models and DTOs which you will pass to services, repositories and controllers. If you do so, you will properly need test data for those objects. Often, the data you pass will be very important as it represents the state of your application and business process. You must design it carefully to get the test results you are looking for. However, there are also some cases where the data isn’t so important – it must just be there! You need an object, filled with random data. That’s it.

Java’s reflection mechanism offers an easy method to create POJOs filled with random data. Here is a basic code snippet which will take a class, instantiate it and fills its fields with random data. Maybe it makes your test setup easier.

Best regards,
Thomas

Using Spring Data for database views without an ID

A database view is a great way to prepare complicated data structures right in the database and present it in a more convenient way. We usually use database views to map our technical driven database structure (with a lot of tables and foreign keys) to a more business driven structure. This means that we might join tables, concatenate values or just rename the columns, because a particular name suits better to the current business context.

To map those views to Java entities, we simply use Spring data:

However, the example above wouldn’t work. Spring would complain that the @Id annotation is missing and would throw a org.hibernate.AnnotationException: No identifier specified for entity exception.

From a business perspective, this is bad. The id of a company is its company id, the id of a person is its person id. But both are missing in the view, which has not unique identifier.

We could solve this problem by a simple trick: we invent an unique identifier – our current row number!

We can now use the row number in our Spring Data entity:

Best regards,
Thomas

Everytime a mock returns a mock a fairy dies

As I was reading about some Mockito features last week, I stumbled over the following tweet, which really made me laugh:

I actually found the reference to the tweet in the Mockito source code about “deep mocking” and it’s worth to think about it for a minute…

Deep mocking

Deep mocking is a really great feature from Mockito. It lets a mock return a mock, which will return a mock, which will return a mock, which will… I think you got it. Here’s an example how it works:

By passing the Mockito.RETURNS_DEEP_STUBS argument to Mockito, we tell Mockito to make a deep mock. This makes it possible to mock the result of a complete method chain in the next step.

Use deep mocking for fluent APIs

Deep mocking is very elegant way to mock fluent APIs/interfaces which are very popular right now. Fluent APIs are described by Martin Fowler (here) and are often used for builders, factories, queries or configurations.

While method-call chaining is a really bad way to write code as it’s hard to read, hard to debug and hard maintain, fluent APIs are very handy to avoid repetition in the code (e.g. to write something like builder.setId(1); builder.setName("My Object"); ...) and to lead the developer through a certain process (e.g. an object creation). Since Java’s stream API they are also part of the core Java language. You will find them in many other places, too:

  • Java 8 streams: list.stream().filter(...).map(...).sum()
  • Mockito: when(...).thenReturn(...)
  • Apache HTTP Client: Request.GET(...).connectTimeout(...).execute().returnContent()
  • Spring MockMVC: mockMvc.perform(get(...).accept(...)).andExpect(status().isOk())

Don’t use deep mocking for call chains

This brings me back to the tweet about the dying fairies on the top of this post. While the tweet doesn’t apply fluent APIs (IMHO), it definitely applies to bad written code. When every a mock returns a mock (and so on…) some encapsulation is broken. As you need to know details about the internal behavior of the mocked object (to mock it again), you are violating the Law of Demeter (the principle of least knowledge).

Fluent APIs vs. Code Chains

It’s important to know the difference between a smart and handy fluent API (which you might mock!) and a bunch of ugly code chains (which you better refactor!). Code chains break encapsulations and leak the internals of an object to the outer world. Fluent APIs on the other provide a small DSL (domain specific language) which doesn’t leek internals as it only returns the “next possible step” and guides you on your way.

References

Best regards,
Thomas

When modularity comes down to OSGi

Last week I attended a tech talk by Christian Schlichtherle, organized by Euro Staff in Berlin. The talk was about modularity and its different forms in software development. Christian talked about packages, libraries, APIs, dependency management and – as always when it comes down to modularity – about OSGi.

Every time somebody is talking about OSGi I get this tiny pain in my stomach. OSGi is a really great idea and a lot of people are working with it for many years right now. That’s cool! But I still have some questions about this…

Who wants to install code during run time on a server?

Let’s start with my biggest point of criticism. OSGi has two main points:

  • OSGi (maybe) solves the class path hell (we will come to this later)
  • OSGi introduces modularity during run time for Java software

But really – who builds software with a highly static language such as Java but then installs code during run time on his production environment!? Maybe I just don’t know the use-case, but every company I saw so far is looking for a stable server architecture. They want to deploy something in their test environment, then go to staging and finally do a green-blue-deployment. They don’t want to throw some new software in and let itself install it. And if they would do so, I would wonder how they deal with open user sessions, with buggy updates which breaks the system, with security and so on. In my opinion there are only very few cases where you really need and want modularity on the server.

OSGi is solving the class path hell!

It’s often said that OSGi is solving the class path hell. And when somebody is saying this, he comes up with the diamond problem:

Some package A needs a package B and C. B and C need a package D but in two different version. And you are screwed!

OSGi solves this problem, because every package will get its own class loader and every Java class is not only identified by its name but also by it class loaded. This makes it possible to load the same class in different version for package B and C. Problem solved!

But what happens when package B and C are returning objects from package D? Let’s make some stupid example: Package D contains a model: Person.class, Address.class. Package B and C are different factory strategies for this model. Package B reads data from a web service and package C from a local file. And package A is using both of them:

The problem with this code is that it looks perfectly fine and will compile, too. But it will fail on run time with a class cast exception! Why? Because User.class from package B was loaded with a different class loader as User.class from package C. So for Java, those are two different classes!

To solve this problem in OSGi you would write a service with an interface in package B and C, describe it in XML and wire it in package A. You would expose those services explicitly and create bunch of XML. Then you would package everything with an OSGi compatible manifest, assign version number to each bundle, re-pack third party libraries to OSGi bundles too, define a start-up order for the bundles, load an OSGi run time environment and then – a couple of hours later – you really solved the diamond problem.

IMHO

I think solving the class path hell in OSGi means to introduce a class loader and bundle hell instead. In pure Java it’s simple: if something is on the class path, you can use it. In OSGi, this is more complicated and if you miss to strictly use OSGi services to decouple you software you will end up with a highly coupled bunch of bundles which might throw class cast exception because you still cannot user version 1.5 and version 2 at the same time.

Best regards,
Thomas

Why using Spring’s @Value annotation is bad

@Value

Configuration is an important topic of every application which has more than a couple of hundred lines of code. In case you are using Spring, you would typically use Spring’s @Value annotation to load values from a Java properties file. This could look like this:

If you do so, Spring would inject the value for the key my.config.property.key from your properties file right into your class and you are done. Easy! Maybe too easy…

What will happen…

What will happen when you use this technique through your application? Well, whenever you need some property, you will inject it. You will inject it in services, controllers and components and you will properly inject the same property in different classes. That’s easy and absolutely what the mechanism is about.

However, this means nothing else than scattering your configuration about your whole application. Every class can pick a couple of properties to use. You will have no idea or control which class is using which properties. You will end-up with doing a full text search on your project to find out where a single key is used. You will have a lot of fun if you want to rename one of those keys or when you need to set each and every property for each and every class in your unit tests.

Configuration is an service

Instead of this, configuration should be an encapsulated service of your application such as any other functionality, too. You encapsulate persistence in DAOs, you encapsulate REST services in controllers and you encapsulate security in authenticators. So why not encapsulating configuration?

If you do so, you will have a single point of responsibility to load and get your configuration from. As any other service, you can easily change the implementation. Maybe you don’t want to load your properties from a properties file, but from a database or web service! If you encapsulate your configuration in a service, that’s not a big deal. You just change the implementation. You can also write some unit tests for your configuration (Why not? Configuration can become complicated when properties are combined or a certain configuration is determined based on a couple of other properties!) or you can do sanity checks for properties in the configuration service. You can do logging, you can do security (Maybe the path to the password file shouldn’t be visible everywhere, right?), you can do caching, you can do… well, you get the point.

Best regards,
Thomas

Anti Patterns

A couple of days ago I have been to a tech talk from eBay in Berlin. The talk was hold by a developer of the eBay Kleinanzeigen team (a subsection of eBay in Germany) who talked about development patterns his team learned during the years. He mentioned behavioral patterns, design patterns and coding pattern his colleagues and he discovered as good practices for their projects. Since nearly everything could be seen as a pattern, the talk was a mix of learned lessons and actual advises on how to structure code. Cool! It is always good to talk and hear about coding experiences and it also reminded me at something which is often more important than patterns: anti patterns!

2015-01-22 19.27.11

The idea of anti patterns always comes to my mind when I’m reading some old code. And it comes more often if the code is super sophisticated and fancy. The more people try to engineer their code, the more they build things which looks like some complicated pattern but are actually anti patterns.

You like some examples? Here’s a very trivial anti pattern, not a big thing. It’s just a bad habit. It looks like that:

Anything wrong here? No, just a factory. Anything useless? Yes, a little bit. It’s very likely to see a class with only static methods (like a factory) to have a private constructor. Why? Because the developer thought it’s evil to instantiate it and he must prevent it for the safety of everybody in the room! So he creates something which look like a singleton (but isn’t). He does this in every suitable class, because it’s his patterns. But it is actually nothing. What would happen if you instantiate such an object? Nothing. And if you call static methods on that object? Nothing, too. It doesn’t look good, but it would work and your IDE would warn you. So what problem does it solve? There’s none. It just looks like some useful pattern, but actually does nothing but clutter your code. An anti pattern.

There are more of those small bad habits (like using final everywhere) but also bigger ones (like an interface for everything). I’m going to think about this a little more and come up with another example!

Best regards,
Thomas

Making a Spring bean session scoped

Spring can not only inject beans (components, services, entities, however you want to call them), it can also inject them according to a certain scope. This is great if you have state-full objects which belongs (for example) to a dedicated user and not to the whole application. To do that, Spring introduced the @Scope annotation.

The usage of @Scope is straight forward: just annotate your bean with it and specify the scope to use:

The value of @Scope can be one of singleton (one single instance for the whole app), prototype (a new instance for every injection), request (an instance per web request) or session (an instance per web session). See here.

The last two scopes (request and session) are only available in Spring web applications where the current session is exposed. To do so, you need to add a listener to the web.xml which makes the context available:

If you got both, your annotated bean and the listener in your web.xml, you will typically have another problem: how to use a session scoped bean in a normal (not session scoped) service?

To solve this problem, Spring provides a proxy mechanism. This means Spring can wire a proxy with the same interface as your actual bean instead of the bean itself. The proxy will not be session scoped (it will be a singleton), but it will fetch the according session scoped bean for each request. This means you can wire your session scoped bean in a not session scoped service and the proxy will do the rest behind the scenes.

To use such a proxy, you can just add it to the @Scope annotation like that:

If you do so, you will discover the next problem soon: what about your integration tests you made which probably will fail now as they got no session? The easiest fix for this, is to add the following bean configuration, which adds a session context for each thread (see the post of Tarun Sapra for the original description):

Best regards,
Thomas