An intercession for a Bean

Recently I joined a new project team. We implement a microservice architecture using Spring Boot and several other cutting edge technology. While most team members are experienced programming in Java and Java EE, some of them are new to the Spring Framework and most are not quite familiar with how to structure Spring Beans properly.

In this post I will briefly explain how to implement a “good” Bean (read Java class) and why following these simple rules will make your life easier. For this we’ll take a look at a basic Java class and then dissect it to understand what details make it a good Bean.

Interfaces 101

Just before we start dismantling a real Spring Bean, let’s have a look at the interface which the Bean implements.


 * A service to manage {@link User}s.
 * @author WaldemarBiller
public interface UserService {

     * Persists the given {@link User} into the datastore.
     * @param user the user to persist, must not be {@literal null}
     * @return the persisted user or {@literal null}
     * @throws UserExistsException in case when a user with same normalized name already exists
    User create(User user) throws UserExistsException;

     * Updates the given {@link User} in the datastore
     * @param user the user to update, must not be {@literal null}
     * @return the persisted user or {@literal null}
    User update(User user);

     * Removes the given user from the datastore
     * @param user the user to remove, must not be {@literal null}
     * @return {@literal true} in case the {@link User} does not exists anymore, {@literal false} otherwise
    boolean delete(User user);

As usual the interface starts with a package declaration. No magic; please just avoid underscores in names.
It’s good style to provide a brief JavaDoc comment which states the general purpose of the interface. Don’t explain the world! The interface name should fit that purpose as well. An established naming pattern is to use an entity name and the kind of Bean type (in terms of Domain Driven Design, which knows Services, Repositories etc). If this doesn’t fit an adjective might be the right thing.

Each method the interface defines should also have a JavaDoc comment. The description usually starts with a verb.
For each parameter give a little description and tell the preconditions the parameter has to fulfill e.g. an integer being positive.
If the method throws a checked exception describe under which circumstances it is supposed to happen. Finally describe every possible kind of value that can be returned.
Following design by contract this JavaDoc is the contract for any implementing class. Implementors are not allowed to break it!

Back to Beans

Now let’s take that look at the example class.


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.util.Assert;

 * Default implementation of the {@link UserService}. 
 * This class uses {@link UserRepository} to store {@link User}s.
 * @author WaldemarBiller
class UserServiceImpl implements UserService {

    /* constants ******************************************************************************************************/
    private static final Logger LOG = LoggerFactory.getLogger(UserServiceImpl.class);

    /* dependencies ***************************************************************************************************/
    private final UserRepository repository;

    /* constructors ***************************************************************************************************/
     * @param repository the user repository, must not be {@literal null}
    UserServiceImpl(UserRepository repository) {
        this.repository = repository;

    /* methods ********************************************************************************************************/
    public User create(User user) throws UserExistsException {

        Assert.notNull(user, "user must not be null");"Looking up count of users with normalized name '{}", user.getNormalizedName());
        if (repository.countByNormalizedName(user.getNormalizedName()) > 0) {
            throw new UserExistsException(user.getNormalizedName());
        }"Persisting user '{}'", user.getNormalizedName());

    public User update(User user) {

        Assert.notNull(user, "user must not be null");"Persisting user '{}'", user.getNormalizedName());

    public boolean delete(User user) {

        Assert.notNull(user, "user must not be null");

        Integer id = user.getId();"Removing user '{}'", user.getNormalizedName());

        return !repository.exists(id);

Like almost every Java Class file this Spring Bean starts with a package declaration followed by the imports, and also sports a JavaDoc comment. Here you state what makes this implementation special and discriminates it from alternatives.

It’s good practice to divide the class into sections. A good order might be: inner classes, constants, members, dependencies, constructors, property methods, methods. But that’s just my preference.
Each class should have a logger if any necessary. Please declare it private, static and final! That way it has to be instantiated only once per class while still allowing to filter the logs properly.

Dependency Injection

Spring and Java EE are all about Dependency Injection.

The dependencies section features every dependency of the Bean. If a dependency is mandatory it should also be declared final. Please avoid field injection, as it harms you when you try to test the Spring Bean. Instead of this the constructor is annotated with @Autowired and every mandatory dependency is provided as a parameter. If your parameter list exceeds 5 items you should rethink your class structure and divide the Bean into several parts. Any optional dependency can be set via a setter, which has to be annotated with @Autowired, too.

Assert Parameters

Just like the method declarations in the interface the constructor defines a contract with preconditions. All preconditions can be checked for instance using Spring’s Assert helper class. You could also use Guava’s Preconditions class or some such, as long as it throws an IllegalArgumentException or some domain driven derivative if a precondition is violated. Please make sure to check the preconditions before any calculation!

The methods don’t need to have a JavaDoc comment as long as they just follow the contract which was defined in the interface. Keep it DRY!

That’s it. Spring Beans made easy.


The origin if the title picture is It is in the public domain.

Teilen Sie diesen Beitrag

Das könnte dich auch interessieren …

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Durch die weitere Nutzung der Seite stimmen Sie der Verwendung von Cookies zu. Weitere Informationen

Die Cookie-Einstellungen auf dieser Website sind auf "Cookies zulassen" eingestellt, um das beste Surferlebnis zu ermöglichen. Wenn du diese Website ohne Änderung der Cookie-Einstellungen verwendest oder auf "Akzeptieren" klickst, erklärst du sich damit einverstanden.