@Qualifier for ambiguous beans in Spring Boot

Introduction

Sometimes Spring finds more than one bean of the same type and doesn't know which one to use. @Qualifier helps tell Spring exactly which bean to pick.

You have two or more beans of the same type and want to choose one for injection.

You want to avoid errors caused by Spring not knowing which bean to use.

You want to clearly name beans and inject them by those names.

You want to inject different implementations of the same interface in different places.

You want to make your code easier to understand by explicitly specifying beans.

Syntax

Spring Boot

@Autowired
@Qualifier("beanName")
private BeanType bean;

@Qualifier uses the bean's name to pick the right one.

You put @Qualifier right where you inject the bean.

Examples

Here, two beans implement Service. @Qualifier("fastService") tells Spring to use the FastService bean.

Spring Boot

@Component("fastService")
public class FastService implements Service {}

@Component("slowService")
public class SlowService implements Service {}

@Autowired
@Qualifier("fastService")
private Service service;

Using @Qualifier with @Bean methods to pick the right greeting bean.

Spring Boot

@Bean(name = "englishGreeting")
public Greeting englishGreeting() {
    return new EnglishGreeting();
}

@Bean(name = "spanishGreeting")
public Greeting spanishGreeting() {
    return new SpanishGreeting();
}

@Autowired
@Qualifier("spanishGreeting")
private Greeting greeting;

Sample Program

This Spring Boot app has two Printer beans. Using @Qualifier("consolePrinter") tells Spring to use the ConsolePrinter bean. When run, it prints a message from the chosen bean.

Spring Boot

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

interface Printer {
    void print();
}

@Component("consolePrinter")
class ConsolePrinter implements Printer {
    public void print() {
        System.out.println("Printing to console");
    }
}

@Component("filePrinter")
class FilePrinter implements Printer {
    public void print() {
        System.out.println("Printing to file");
    }
}

@SpringBootApplication
public class QualifierExample implements CommandLineRunner {

    @Autowired
    @Qualifier("consolePrinter")
    private Printer printer;

    public static void main(String[] args) {
        SpringApplication.run(QualifierExample.class, args);
    }

    @Override
    public void run(String... args) {
        printer.print();
    }
}

Important Notes

If you forget @Qualifier when multiple beans exist, Spring throws an error about ambiguity.

You can use @Qualifier on constructor parameters, fields, or setter methods.

Bean names are case-sensitive when used with @Qualifier.

Summary

@Qualifier helps Spring pick the right bean when there are many of the same type.

Use @Qualifier("beanName") where you inject the bean.

This avoids errors and makes your code clearer.