Spring @Qualifier Annotation with Example

The @Qualifier annotation is used to resolve ambiguity when multiple beans of the same type are available for dependency injection. It helps specify which exact bean should be injected into a class when Spring cannot automatically determine the correct one.

Key features of @Qualifier Annotation:

• Used with @Autowired to resolve dependency ambiguity.
• Specifies the bean name (ID) to inject.
• Can be applied on: Fields, Setter methods, Constructor parameters.
• Without @Qualifier, if more than one matching bean exists, Spring throws a NoUniqueBeanDefinitionException.
• Ensures correct and controlled dependency injection.

How @Autowired Works Internally

Spring resolves dependencies in the following order:

• By Type - matches the bean type.
• By Name - matches bean ID with property name.
• Throws an exception if ambiguity still exists.

This is where @Qualifier becomes necessary.

Problem with @Autowired Annotation

To understand the need for the @Qualifier annotation, let’s first look at a scenario where the @Autowired annotation can cause issues. Consider a Human class that depends on a Heart class. The Heart class has a simple method called pump()

Heart.java

public class Heart {
    public void pump() {
        System.out.println("Heart is Pumping");
    }
}

Explanation:

• This class represents a simple dependency with a pump() method.
• It is the bean that will be injected into another class (Human).
• Multiple objects of this class can cause ambiguity during autowiring.

Human.java

Human class does has a dependency on another class named Heart.

import org.springframework.beans.factory.annotation.Autowired;

public class Human {
    private Heart heart;

    @Autowired
    public void setHeart(Heart heart) {
        this.heart = heart;
    }

    public void startPumping() {
        heart.pump();
    }
}

Explanation:

• private Heart heart: Declares a dependency that needs to be injected by Spring.
• @Autowired on setHeart(): Tells Spring to inject a matching Heart bean automatically.
• this.heart = heart: Assigns the injected bean to the class variable.
• startPumping():Uses the injected Heart object to call its pump() method.

beans.xml (Single Bean)

<context:annotation-config/>
<bean id="heartObjValue" class="Heart"/>
<bean id="humanObject" class="Human"/>

Output

Heart is Pumping

Explantion:

• <context:annotation-config/> → Activates Spring annotations like @Autowired so dependencies can be injected automatically.
• <bean id="heartObjValue" class="Heart"/> → Creates a Heart bean managed by the Spring container.
• <bean id="humanObject" class="Human"/> → Creates a Human bean; Spring injects the Heart bean into it based on @Autowired.

It Works correctly because only one Heart bean exists.

Multiple Beans of Same Type

This configuration shows the real problem that occurs when Spring finds multiple beans of the same type during autowiring.

beans.xml (Multiple Bean)

<context:annotation-config/>
<bean id="humanHeart" class="Heart"/>
<bean id="octopusHeart" class="Heart"/>
<bean id="humanObject" class="Human"/>

Output

NoUniqueBeanDefinitionException

Explanation:

• <context:annotation-config/>: Enables annotation-based dependency injection such as @Autowired.
• <bean id="humanHeart" class="Heart"/>: Registers one Heart bean with the ID humanHeart.
• <bean id="octopusHeart" class="Heart"/>: Registers another Heart bean of the same type.
• <bean id="humanObject" class="Human"/>: Creates the Human bean that depends on a Heart.
• Spring finds two beans of type Heart, so autowiring by type becomes ambiguous.
• Autowiring by name also fails because the property name heart does not match humanHeart or octopusHeart.
• Result: Spring throws a NoUniqueBeanDefinitionException due to multiple matching beans.

Solution: Using @Qualifier Annotation

When multiple beans of the same type exist, @Qualifier helps specify which one to inject. For example, in the Human class, we can use @Qualifier("humanHeart") to avoid confusion and ensure the correct bean is wired.

Human.java (Setter Injection)

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

public class Human {

    private Heart heart;

    @Autowired
    @Qualifier("humanHeart")
    public void setHeart(Heart heart) {
        this.heart = heart;
    }

    public void startPumping() {
        heart.pump();
    }
}

Output:

Heart is Pumping

Explanation:

• private Heart heart: Declares a dependency of type Heart in the Human class.
• @Autowired: Tells Spring to inject a Heart bean automatically.
• @Qualifier("humanHeart"): Specifies that the bean with ID humanHeart must be injected.
• setHeart(Heart heart): Setter method where Spring injects the selected Heart bean.
• this.heart = heart: Assigns the injected bean to the class variable.
• startPumping(): Calls the pump() method on the injected Heart bean, confirming successful wiring.

Alternative: Using @Qualifier on Field Injection

We can also use the @Qualifier annotation directly on the field, eliminating the need for a setter method.

Example: This code demonstrates field injection using @Autowired and @Qualifier to inject a specific Heart bean.

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

public class Human {
    @Autowired
    @Qualifier("humanHeart")
    private Heart heart;

    public void startPumping() {
        heart.pump();
    }
}

Explanation:

• @Autowired → Instructs Spring to automatically inject a dependency.
• @Qualifier("humanHeart") → Tells Spring to inject the Heart bean with ID humanHeart.
• private Heart heart; → Declares a dependency of type Heart.
• Field-level injection → Eliminates the need for a setter method.
• startPumping() → Uses the injected Heart bean to call pump(), confirming correct wiring.

Advantages of @Qualifier

• Eliminates ambiguity in dependency injection.
• Provides precise control over bean selection.
• Improves application reliability in large projects.