The @Qualifier annotation in Spring Boot is used to resolve ambiguity when you have multiple beans of the same type but want to inject a specific one. It helps Spring determine which bean should be autowired when multiple candidates exist.

Here are all the common scenarios where @Qualifier is useful with examples:

Scenario 1: Multiple Beans of the Same Type

You may have multiple beans of the same type, and you want to inject a specific one.

Example:

import org.springframework.stereotype.Component;

@Component
public class Dog implements Animal {
    @Override
    public String sound() {
        return "Bark";
    }
}

@Component
public class Cat implements Animal {
    @Override
    public String sound() {
        return "Meow";
    }
}

Here, both Dog and Cat implement the Animal interface.

Usage of @Qualifier:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

@Service
public class AnimalService {

    private final Animal animal;

    @Autowired
    public AnimalService(@Qualifier("cat") Animal animal) {
        this.animal = animal;
    }

    public String getAnimalSound() {
        return animal.sound();
    }
}

In this example, the @Qualifier("cat") annotation specifies that the Cat bean should be injected into the AnimalService. Without @Qualifier, Spring would throw an exception due to ambiguity.

Scenario 2: Using @Qualifier with Primary and Secondary Beans

Sometimes, you may have one "primary" bean and others that are less frequently used, but you still want to be able to inject the specific ones with @Qualifier.

Example:

@Component
@Primary
public class Dog implements Animal {
    @Override
    public String sound() {
        return "Bark";
    }
}

@Component
public class Cat implements Animal {
    @Override
    public String sound() {
        return "Meow";
    }
}

The @primary annotation ensures that Dog is injected by default. But you can still use @Qualifier to inject Cat.

Usage of @Qualifier to Override @primary:

@Service
public class AnimalService {

    private final Animal animal;

    @Autowired
    public AnimalService(@Qualifier("cat") Animal animal) {
        this.animal = animal;
    }

    public String getAnimalSound() {
        return animal.sound();
    }
}

In this case, despite Dog being marked as @primary, the Cat bean is injected due to the @Qualifier annotation.

Scenario 3: @Qualifier with Constructor Injection and Field Injection
@Qualifier can be used with both constructor-based and field-based injection.

Example: Field Injection with @Qualifier:

@Service
public class AnimalService {

    @Autowired
    @Qualifier("dog")
    private Animal animal;

    public String getAnimalSound() {
        return animal.sound();
    }
}

In this case, the @Qualifier("dog") ensures that the Dog bean is injected into the AnimalService.

Scenario 4: @Qualifier with Method Parameter Injection

You can also use @Qualifier when injecting dependencies via method parameters.

Example:

@Service
public class AnimalService {

    private Animal animal;

    @Autowired
    public void setAnimal(@Qualifier("dog") Animal animal) {
        this.animal = animal;
    }

    public String getAnimalSound() {
        return animal.sound();
    }
}

Here, @Qualifier("dog") ensures that the Dog bean is injected through the setter method.

Scenario 5: @Qualifier with Custom Annotations

You can create custom qualifiers to avoid hardcoding bean names, making the code cleaner and more maintainable.

Example: Custom Qualifier:
Create a Custom Qualifier:

import org.springframework.beans.factory.annotation.Qualifier;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Qualifier
@Retention(RetentionPolicy.RUNTIME)
public @interface DogQualifier {
}

Apply the Custom Qualifier:

@Component
@DogQualifier
public class Dog implements Animal {
    @Override
    public String sound() {
        return "Bark";
    }
}

@Component
public class Cat implements Animal {
    @Override
    public String sound() {
        return "Meow";
    }
}

Inject Using the Custom Qualifier:

@Service
public class AnimalService {

    private final Animal animal;

    @Autowired
    public AnimalService(@DogQualifier Animal animal) {
        this.animal = animal;
    }

    public String getAnimalSound() {
        return animal.sound();
    }
}

In this example, @DogQualifier is used to specify which bean to inject, instead of using @Qualifier("dog").

Scenario 6: @Qualifier in Collections

You can use @Qualifier when autowiring a collection of beans to ensure that only specific beans are injected.

Example:

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;

@Component
@Qualifier("domestic")
public class Dog implements Animal {
    @Override
    public String sound() {
        return "Bark";
    }
}

@Component
@Qualifier("domestic")
public class Cat implements Animal {
    @Override
    public String sound() {
        return "Meow";
    }
}

@Component
public class Lion implements Animal {
    @Override
    public String sound() {
        return "Roar";
    }
}

Usage with a Collection:

@Service
public class AnimalService {

    private final List<Animal> animals;

    @Autowired
    public AnimalService(@Qualifier("domestic") List<Animal> animals) {
        this.animals = animals;
    }

    public void printAnimalSounds() {
        animals.forEach(animal -> System.out.println(animal.sound()));
    }
}

In this example, only Dog and Cat beans are injected because they are marked with the @Qualifier("domestic").

Summary:

@Qualifier helps in injecting specific beans when there are multiple candidates of the same type.

It is used in scenarios like constructor injection, field injection, method injection, custom qualifiers, and even with collections.

By understanding these scenarios, you can use @Qualifier effectively to resolve ambiguity and manage bean injection in a Spring Boot application.

@Qualifier Annotation Spring Boot Explained