Groovy / Maven

Micronaut Scope Types

Learn about the available scopes: Singleton, Prototype, Request, Refreshable, Context...

Sergio del Amo
On this guide
In this section

Introduction

Micronaut features an extensible bean scoping mechanism based on JSR-330.

What you will need

To complete this guide, you will need the following:

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=management,validation \
    --build=maven \
    --lang=groovy \
    --test=spock
Note
 If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add management, and validation features.

Note
 If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

Scenario

We use the following scenario to talk about the different types of scopes.

The following @Controller injects two collaborators.

groovy/src/main/groovy/example/micronaut/singleton/RobotController.groovy
package example.micronaut.singleton

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller('/singleton') // 

class RobotController {

    private final RobotFather father
    private final RobotMother mother

    RobotController(RobotFather father,  // 
                    RobotMother mother) { // 
        this.father = father
        this.mother = mother
    }

    @Get // 
    List<String> children() {
        [
                father.child().serialNumber,
                mother.child().serialNumber
        ]
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /.
2 Use constructor injection to inject a bean of type RobotFather.
3 Use constructor injection to inject a bean of type RobotMother.
4 The @Get annotation maps the children method to an HTTP GET request on /.

Each collaborator has an injection point for a bean of type Robot.

groovy/src/main/groovy/example/micronaut/singleton/RobotFather.groovy
package example.micronaut.singleton

import jakarta.inject.Singleton

@Singleton // 
class RobotFather {
    private final Robot robot

    RobotFather(Robot robot) { // 
        this.robot = robot
    }

    Robot child() {
        robot
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Use constructor injection to inject a bean of type Robot.
groovy/src/main/groovy/example/micronaut/singleton/RobotMother.groovy
package example.micronaut.singleton

import jakarta.inject.Singleton

@Singleton // 
class RobotMother {
    private final Robot robot

    RobotMother(Robot robot) { // 
        this.robot = robot
    }

    Robot child() {
        robot
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Use constructor injection to inject a bean of type Robot.

Let’s discuss how the application behaves depending on the scope used for the bean of type Robot.

Singleton

Singleton scope indicates only one instance of the bean will exist.

To define a singleton, annotate a class with jakarta.inject.Singleton at the class level.

The following class creates a unique identifier in the constructor. This identifier allows us to identify how many Robot instances are used.

groovy/src/main/groovy/example/micronaut/singleton/Robot.groovy
package example.micronaut.singleton

import jakarta.inject.Singleton

import java.util.UUID

@Singleton // 
class Robot {
    private final String serialNumber = UUID.randomUUID().toString()

    String getSerialNumber() {
        serialNumber
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.

Singleton Test

The following test verifies @Singleton behavior.

groovy/src/test/groovy/example/micronaut/SingletonScopeSpec.groovy
package example.micronaut

import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification
import spock.lang.Unroll

@MicronautTest // 
class SingletonScopeSpec extends Specification {
    @Inject
    @Client('/')
    HttpClient httpClient // 

    @Unroll

    void 'only one instance of the bean exists for singleton beans'() {
        given:
        Set<String> responses = executeRequest(httpClient, path) as Set

        expect:
        responses.size() == 1 // 

        when:
        responses.addAll(executeRequest(httpClient, path))

        then:
        responses.size() == 1 // 

        where:
        path << ['/singleton']
    }

    private static List<String> executeRequest(HttpClient client, String path) {
        client.toBlocking().retrieve(HttpRequest.GET(path), Argument.listOf(String))
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the HttpClient bean and point it to the embedded server.
3 The same instance fulfills both injection points at RobotFather and RobotMother.
4 Same instance is used upon subsequent requests.

Prototype

Prototype scope indicates that a new instance of the bean is created each time it is injected

Let’s use @Prototype instead of @Singleton.

groovy/src/main/groovy/example/micronaut/prototype/Robot.groovy
package example.micronaut.prototype

import io.micronaut.context.annotation.Prototype

import java.util.UUID

@Prototype // 
class Robot {
    private final String serialNumber = UUID.randomUUID().toString()

    String getSerialNumber() {
        serialNumber
    }
}
1 Use io.micronaut.context.annotation.Prototype to designate the scope of bean as Prototype - a non-singleton scope that creates a new bean for every injection point.

Prototype Tests

The following test verifies the behavior of Prototype scope.

groovy/src/test/groovy/example/micronaut/PrototypeScopeSpec.groovy
package example.micronaut

import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification
import spock.lang.Unroll

@MicronautTest // 
class PrototypeScopeSpec extends Specification {
    @Inject
    @Client('/')
    HttpClient httpClient // 

    @Unroll

    void 'prototype scope indicates that a new instance of the bean is created each time it is injected'() {
        given:
        Set<String> responses = executeRequest(httpClient, path) as Set

        expect:
        responses.size() == 2 // 

        when:
        responses.addAll(executeRequest(httpClient, path))

        then:
        responses.size() == 2 // 

        where:
        path << ['/prototype']
    }

    private static List<String> executeRequest(HttpClient client, String path) {
        client.toBlocking().retrieve(HttpRequest.GET(path), Argument.listOf(String))
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the HttpClient bean and point it to the embedded server.
3 A new instance is created to fulfill each injection point. Two instances - one for RobotFather and another for RobotMother.
4 Instances remain upon subsequent requests.

Request

@RequestScope scope is a custom scope that indicates a new instance of the bean is created and associated with each HTTP request

groovy/src/main/groovy/example/micronaut/request/Robot.groovy
package example.micronaut.request

import io.micronaut.http.HttpRequest
import io.micronaut.runtime.http.scope.RequestAware
import io.micronaut.runtime.http.scope.RequestScope

@RequestScope // 
class Robot implements RequestAware { // 
    String serialNumber

    @Override
    void setRequest(HttpRequest<?> request) {
        serialNumber = request.headers.get('UUID')
    }
}
1 Use io.micronaut.runtime.http.scope.RequestScope to designate the scope of bean as Request - a new instance of the bean is created and associated with each HTTP request.
2 RequestAware API allows @RequestScope beans to access to the current request.

Request Tests

The following test verifies the behavior of @RequestScope scope.

groovy/src/test/groovy/example/micronaut/RequestScopeSpec.groovy
package example.micronaut

import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification

@MicronautTest // 
class RequestScopeSpec extends Specification {
    @Inject
    @Client('/')
    HttpClient httpClient // 

    void 'request scope creates an instance associated with each HTTP request'() {
        given:
        String path = '/request'
        Set<String> responses = executeRequest(httpClient, createRequest(path)) as Set

        expect:
        responses.size() == 1 // 

        when:
        responses.addAll(executeRequest(httpClient, createRequest(path)))

        then:
        responses.size() == 2 // 
    }

    private static List<String> executeRequest(HttpClient client, HttpRequest<?> request) {
        client.toBlocking().retrieve(request, Argument.listOf(String))
    }

    private static HttpRequest<?> createRequest(String path) {
        HttpRequest.GET(path).header('UUID', UUID.randomUUID().toString())
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the HttpClient bean and point it to the embedded server.
3 Both injection points, RobotFather and RobotMother, are fulfilled with the same instance of Robot. An instance associated with the HTTP Request.
4 Both injection points are fulfilled with the new instance of Robot.

Refreshable

Refreshable scope is a custom scope that allows a bean’s state to be refreshed via the /refresh endpoint.

groovy/src/main/groovy/example/micronaut/refreshable/Robot.groovy
package example.micronaut.refreshable

import io.micronaut.runtime.context.scope.Refreshable

import java.util.UUID

@Refreshable // 
class Robot {
    private final String serialNumber = UUID.randomUUID().toString()

    String getSerialNumber() {
        serialNumber
    }
}
1 @Refreshable scope is a custom scope that allows a bean’s state to be refreshed via the /refresh endpoint.

Your application needs the management dependency to enable the refresh endpoint.

pom.xml
<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-management</artifactId>
    <scope>compile</scope>
</dependency>

Refreshable Tests

The following test enables the refresh endpoint and verifies the behavior of @Refreshable

groovy/src/test/groovy/example/micronaut/RefreshableScopeSpec.groovy
package example.micronaut

import io.micronaut.context.annotation.Property
import io.micronaut.core.type.Argument
import io.micronaut.core.util.StringUtils
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification

@Property(name = 'endpoints.refresh.enabled', value = StringUtils.TRUE) // 
@Property(name = 'endpoints.refresh.sensitive', value = StringUtils.FALSE) // 
@MicronautTest // 
class RefreshableScopeSpec extends Specification {
    @Inject
    @Client('/')
    HttpClient httpClient // 

    void 'refreshable scope allows a bean state to be refreshed via the refresh endpoint'() {
        given:
        String path = '/refreshable'
        Set<String> responses = executeRequest(httpClient, path) as Set

        expect:
        responses.size() == 1 // 

        when:
        responses.addAll(executeRequest(httpClient, path))

        then:
        responses.size() == 1 // 

        when:
        refresh(httpClient) // 
        responses.addAll(executeRequest(httpClient, path))

        then:
        responses.size() == 2 // 
    }

    private static void refresh(HttpClient client) {
        client.toBlocking().exchange(HttpRequest.POST('/refresh', [force: true]))
    }

    private static List<String> executeRequest(HttpClient client, String path) {
        client.toBlocking().retrieve(HttpRequest.GET(path), Argument.listOf(String))
    }
}
1 Annotate the class with @Property to supply configuration to the test.
2 The refresh endpoint is sensitive by default. To invoke it in the test, we set endpoints.refresh.sensitive to false.
3 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
4 Inject the HttpClient bean and point it to the embedded server.
5 The same instance fulfills both injection points at RobotFather and RobotMother.
6 The same instance serves a new request.
7 Hitting the refresh endpoint, publishes a RefreshEvent, which invalidates the instance of Robot.
8 A new instance of Robot is created the next time the object is requested.

@Context

Context scope indicates that the bean will be created at the same time as the ApplicationContext (eager initialization)

The following example uses @Context in combination with @ConfigurationProperties.

groovy/src/main/groovy/example/micronaut/context/FrameworkConfiguration.groovy
package example.micronaut.context

import io.micronaut.context.annotation.ConfigurationProperties
import io.micronaut.context.annotation.Context
import jakarta.validation.constraints.Pattern

@Context // 
@ConfigurationProperties('framework') // 
class FrameworkConfiguration {

    @Pattern(regexp = 'groovy|java|kotlin') // 
    String language
}
1 The life cycle of classes annotated with io.micronaut.context.annotation.Context is bound to that of the bean context.
2 The @ConfigurationProperties annotation takes the configuration prefix.
3 Use jakarta.validation.constraints Constraints to ensure the data matches your expectations.

The result is validation being performed on the Application Context start-up.

groovy/src/test/groovy/example/micronaut/ContextSpec.groovy
package example.micronaut

import io.micronaut.context.ApplicationContext
import io.micronaut.context.exceptions.BeanInstantiationException
import spock.lang.Specification

class ContextSpec extends Specification {

    void 'life cycle of classes annotated with Context is bound to that of the BeanContext'() {
        when:
        ApplicationContext.run(['framework.language': 'scala'])

        then:
        BeanInstantiationException e = thrown()
        e.message.contains('must match "groovy|java|kotlin"')
    }
}

Other scopes

Micronaut Framework ships with other built-in scopes:

@Infrastructure

@Infrastructure scope represents a bean that cannot be overridden or replaced using @Replaces because it is critical to the functioning of the system.

@ThreadLocal

@ThreadLocal scope is a custom scope that associates a bean per thread via a ThreadLocal

Next Steps

Read more about Scopes in the Micronaut Framework.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note
 All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).