AngularJS provider and app configuration

AngularJS provides 3 different ways to create a service:

Factory

A factory is a well known pattern in software development. It aims to create a certain object, in this case a service. In AngularJS this is simply a function which returns an object with methods. In my opinion, this is the cleanest way to create a service in AngularJS.

Service

Another way to create a service is a mechanism called “service”. In this case, your service is a function which has other functions attached to this. It is the shortest way to create a service in AngularJS. However, it sometimes becomes confusing when you need to refer to your own functions using this.

Provider

The last way to create a service, is a provider. A provider fulfils a certain interface and implements a method called $get. This method returns a function which in turn returns the service object. So by calling $get on a provider, you will receive a service factory. This is obviously the most verbose way to create a service.

So why should I use a provider?

So if a provider is the most verbose method you have to create a service, why should you use it at all? To answer this question, it’s important to know that no matter which way you use – factory, service or provider – AngularJS will always create a provider for you internally. That’s why you will sometimes see an error message like this:

When an AngularJS app is started, it has a certain “boot-order”. From the perspective of a developer, it looks like this:

After you defined your application/module, you have a configuration phase and a run phase. The difference between both phases is the service instantiation. During the config phase, the providers have been registered, but they have not been called yet! During the run phase all providers have been called and their services have been registered. This means that you cannot inject any service during the config phase and that you cannot inject any provider during the run phase. Though you can use the config phase to configure your providers and it’s service.

Let’s take a look at the AngularJS UI-Router for an example. If you don’t know it, you can find the documentation at https://github.com/angular-ui/ui-router/wiki/quick-reference.

The AngularJS UI-Router provides both, a provider called $stateProvider as well as a service called $state. The usage would look like this:

By using a provider we have the possibility to configure a service before the AngularJS application runs. We can setup things in advance which can be constant during our application lifecycle. If you need something like this, go with a provider. Other wise use a factory or service.

More

Best regards,
Thomas

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

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

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

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

Thread pools with Java’s ExecutorService

Some days ago I had to do a migration of legacy data to a new system. The task was mainly about copying stuff from the old system to the new system. This was done via a REST interface of the new service. So the task was completely IO bound and most of the time the migration script was waiting for a response of a REST call. A perfect situation to do some threading!

The idea was to start a new thread for every data record to migrate. So while the first record was already waiting for the REST response, the second record would be build together and sent to the REST service and so on. This would hopefully speed up the process a lot.

However, since I got about ~5000 records, I didn’t want to spawn a new thread for each of those. 5000 threads (at the same time) would be hard – for my own system as well as for the REST service. So I decided to use Java’s ExecutorService to spawn a fixed number of threads at any time:

In the example above I do the following:

  1. I make an ExecutorService instance with a fixed size of 10 threads. So at any time, a maximum of 10 threads will run!
  2. I execute 100 threads. However, if 10 threads are already running, the ExecutorService will wait until one of those has finished, before starting the next one.
  3. I call shutdown() and awaitTermination(...) on the ExecutorService which will make it impossible to run new threads (except the 100 threads submitted before) and block until all 100 threads have finished.

This pattern makes it possible to submit a large number of threads for execution, but only run a fixed number of threads in a pool.

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

Development speed, the Docker remote API and a pattern of frustration

One of the challenges Docker is facing right now, is its own development speed. Since its initial release in January 2013, there have been over 7.000 commits (in one year!) by more than 400 contributors. There are more than 1.800 forks on GitHub and Dockers brings up approximately one new release per month. Docker is in a super fast development right now and this is really great to see!

However, this very high development speed leaves a lot of third-party tools behind. If you develop a tool for Docker, you have to keep a very high pace. If not, your tool is outdated within a month.

Docker remote API client libraries

A good example how this development speed affects projects, are the remote API libraries for Docker. Docker offers a JSON API to access Docker in a programmatic way. It enables you for example to list all running containers and stop a specific one. All via JSON and HTTP requests.

To use this JSON API in a convenient way, people created bindings for their favorite programming language. As you can see below, there exist bindings for JavaScript, Ruby, Java and many more. I used some of them on my own and I am really thankful for the great work their developers have done!

But many of those libraries are outdated at the time I am writing this. To be exact: all of them are outdated! The current remote API version of Docker is v1.11 (see here for more) which none of the remote API libraries supports right now. Many of them don’t even support v1.10 or v1.9.

Here is the list of remote API tools as you find it at http://docs.docker.io/reference/api/remote_api_client_libraries/.

Language Name Remote API
Python docker-py v1.9
Ruby docker-api v1.10
JavaScript (NodeJS) dockerode v1.10
JavaScript (NodeJS) ocker.io v1.7
JavaScript (Angular) WebUI dockerui v1.8
Java docker-java v1.8
Erlang erldocker v1.4
Go dockerclient v1.10
PHP Docker-PHP v1.9
Scala reactive-docker v1.10

How to deal with rapidly evolving APIs

How to deal with rapidly evolving APIs is a difficult question and IMHO Docker made the right decision. By solely providing a JSON API Docker chose a modern and universal technique. A JSON API can be used in any language or even in a web browser. JSON (together with a RESTful API) is the state-of-the-art technique to interact with services. Docker even leaves the possibility to fall back to an old API version by adding an version identifier to the request. Well done.

But the decision to stay “universal” (by solely providing a JSON API) also means to don’t get specific. Getting specific (which means to use Docker in a certain programming language) is left to the developers of third party tools. These tools are also evolving rapidly right now, no matter if those are remote API bindings, deployment tools (like Deis.io), or hosting solutions (like CoreOS). This enriches the Docker ecosystem and makes the project even more interesting.

Bad third party tools will fall back on you

The problem is, even if Docker made a good job (which they did!), outdated or poorly implemented third party tools will fall back on Docker, too. If you use a third party library (which you maybe found via the official website) and it works fine, you will be happy with Docker and the third party library. But if the library doesn’t work next month because you updated Docker and the library doesn’t take care of the API version, you will be frustrated about the tool and about Docker.

Pattern of frustration

This pattern of frustration occurs a lot in software development. Bad libraries cause frustrations about the tool itself. Let’s take Java as an example. A lot of people complain about Java that it is verbose, uses class-explosions as a pattern and makes things much more complicated as they should be. The famous AbstractSingletonProxyFactoryBean class of the Spring framework is just such an example (see +Paul Lewis). Another example is reading a file in Java which was an awful pain:

And even the new NIO API which came with Java 7 is not as easy as it could be:

You need to put a String into a Path to pass it into static method which output you need to put into a String again. Great idea! But what about something like this:

However, it is not the fault of Java, but of a poorly implemented third party tool. If you need to put a File into a FileReader which you need to put into a BufferedReader to be able to read a file line by line into a StringBuilder you use a terrible I/O library! But anyway, you will be frustrated about Java and how verbose it is (and maybe also about the API itself).

This pattern applies to many other things: You are angry about your smartphone, because of a poorly coded app. You are angry about Eclipse because it crashes with a newly installed plugin. And so on…

I hope this pattern of frustration will not apply to Docker and the community will develop a stable ecosystem of tools to provide a solid basis for development and deployment with Docker. A tool like Dockers lives trough its ecosystem. If the tools are buggy or outdated, people will be frustrated about Docker – and that would be a shame, because Docker is really great!

Best regards,
Thomas

What static methods for interfaces tell you about the Java community

Recently I was putting together some code for an OSGi plugin at work. I created an interface to add listeners to an extension point. The code looked something like this:

The idea was simple: At some points in my application I would call all registered listeners, pass them an object and let them do whatever they are supposed to do. The only problem was, that the code to call these listeners is pretty cumbersome:

FML! In reality it looks even more cumbersome with some exception-handling and logging.

So the first thing I did was a utility class to put that code to and never see it again. But utility classes are not a very good practice at all. So I thought about a suitable place for my code. Some kind of a factory? Or some invoker object? But isn’t that just another name for a utility class? Or… why not put it in the interface itself? So the method to deal with the interface would stay in the interface itself.

A minute and a compile time error later it came back to my mind: interface can’t have static methods in Java! (I will come back to this later…)

But why can’t interfaces have static methods?

The question seems legit to me. Classes as well as abstract classes can have static methods and interfaces can have static classes and static fields. But no static methods. Why?

Ask Google!

I did what I’m always doing when I have a question, I asked Google. Five minutes later I had a bunch of different answers:

It’s not possible!

Everything is possible. Especially in Computer Science.

It doesn’t make sense!

I can give you 10 situations in a minute where it makes sense. Let’s start with the one above.

Your desing is wrong!

Is it? Would a new class with just a single method make it better?

You know nothing about OO!

So if I put a static method in an abstract class it’s called a pattern (the Factory Pattern of the GoF) and if I want to do something similar in an interface, I have no clue what I’m doing? Languages like Ruby which are OO from the ground up (not like Java) have similar concepts.

The truth?

As always in software development there’s no certainty. There are a thousand ways to implement the case a both, every with its own pros and cons. One is beautiful OO, one reads nice, another one is easy to test and one is just as sophisticated as it could be. But the best explanation I found is this:

It’s just a design decision of the Java makers.

It is! Like everything that is in the language or not. And as many things that were discussed over the years, it will finally come with the next Java release. Java 8 will have static methods for interfaces. It will also have default implementations for interfaces and Lambda-expressions. OO? Nope, just good to write code.

The community

I looked in a dozen different forums and Q&A sites for a proper explanation. But I didn’t find much good answers. It is just a decision of some guys made a couple of years ago. And right now, it seems that they are doing the very reverse – put static methods for interface in Java 8.

But what really shock me is the way it is discussed in the community. A lot of people are almost religious about it. They don’t have a clue what it’s about, so it must be huge design mistake, not OO or even not possible.

I think strong opinions are never. Not in politics, not in art and especially not in software development. Maybe that’s why Java moves as fast as it does?

The hack

Btw, there is a very easy hack to add static methods to an interface in Java 7. Interfaces can have static classes which can have static methods. It’s not the nicest thing ever, but at least it lets you put your “utility class” together with the interface.

Best regards,
Thomas