Nacos Spring

This section provides a detailed description of the key features of nacos-spring-context:

• Annotation-Driven
• Dependency Injection
• Externalized Configuration
• Event-Driven

1. Annotation-Driven

1.1. Enable Nacos

@EnableNacos is a modular-driven annotation that enables all features of Nacos Spring, including Service Discovery and Distributed Configuration. It equals to @EnableNacosDiscovery and@EnableNacosConfig, which can be configured separately and used in different scenarios.

1.2. Configure Change Listener method

Suppose there was a config in Nacos Server whose dataId is "testDataId" and groupId is default group("DEFAULT_GROUP"). Now you would like to change its content by using the ConfigService#publishConfig method:

@NacosInjected
private ConfigService configService;
@Test
public void testPublishConfig() throws NacosException {
    configService.publishConfig(DATA_ID, DEFAULT_GROUP, "9527");
}

Then you would like to add a listener, which will be listening for the config changes. You can do this by adding a config change listener method into your Spring Beans:

@NacosConfigListener(dataId = DATA_ID)
public void onMessage(String config) {
    assertEquals("mercyblitz", config); // asserts true
}

The code below has the same effect:

configService.addListener(DATA_ID, DEFAULT_GROUP, new AbstractListener() {
    @Override
    public void receiveConfigInfo(String config) {
        assertEquals("9527", config); // asserts true
    }
});

Note: @NacosConfigListener supports richer type conversions.

• See Simple Sample of @NacosConfigListener

1.2.1. Type Conversion

The type conversion of @NacosConfigListener includes both build-in and customized implementations. By default, build-in type conversion is based on Spring DefaultFormattingConversionService, which means it covers most of the general cases as well as the rich features of the higher Spring framework.

For example, the content "9527" in the preceding example can also be listened by a method with integer or the Integer argument:

@NacosConfigListener(dataId = DATA_ID)
public void onInteger(Integer value) {
    assertEquals(Integer.valueOf(9527), value); // asserts true
}
@NacosConfigListener(dataId = DATA_ID)
public void onInt(int value) {
    assertEquals(9527, value); // asserts true
}

Of course, nacos-spring-context provides elastic extension for developers. If you define a named nacosConfigConversionService Spring Bean whose type is ConversionService , the DefaultFormattingConversionService will be ignored. In addition, you can customize the implementation of the NacosConfigConverter interface to specify a listener method for type conversion:

public class UserNacosConfigConverter implements NacosConfigConverter<User> {
    @Override
    public boolean canConvert(Class<User> targetType) {
        return true;
    }
    @Override
    public User convert(String source) {
        return JSON.parseObject(source, User.class);
    }
}

The UserNacosConfigConverter class binds the @NacosConfigListener.converter() attribute:

@NacosInjected
private ConfigService configService;
@Test
public void testPublishUser() throws NacosException {
    configService.publishConfig("user", DEFAULT_GROUP, "{\"id\":1,\"name\":\"mercyblitz\"}");
}
@NacosConfigListener(dataId = "user", converter = UserNacosConfigConverter.class)
public void onUser(User user) {
    assertEquals(Long.valueOf(1L), user.getId()); 
    assertEquals("mercyblitz", user.getName());
}

• See Type Conversion Sample of @NacosConfigListener

1.2.2. Timeout of Execution

As it might cost some time to run customized NacosConfigConverter, you can set max execution time in the @NacosConfigListener.timeout() attribute to prevent it from blocking other listeners:

@Configuration
public class Listeners {
    private Integer integerValue;
    private Double doubleValue;
    @NacosConfigListener(dataId = DATA_ID, timeout = 50)
    public void onInteger(Integer value) throws Exception {
        Thread.sleep(100); // timeout of execution
        this.integerValue = value;
    }
    @NacosConfigListener(dataId = DATA_ID, timeout = 200)
    public void onDouble(Double value) throws Exception {
        Thread.sleep(100); // normal execution
        this.doubleValue = value;
    }
    public Integer getIntegerValue() {
        return integerValue;
    }
    public Double getDoubleValue() {
        return doubleValue;
    }
}

The integerValue of Listeners Bean is always null and will not be changed. Therefore, those asserts will be true:

@Autowired
private Listeners listeners;
@Test
public void testPublishConfig() throws NacosException {
    configService.publishConfig(DATA_ID, DEFAULT_GROUP, "9527");
    assertNull(listeners.getIntegerValue()); // asserts true
    assertEquals(Double.valueOf(9527), listeners.getDoubleValue());   // asserts true
}

• See Timeout Sample of @NacosConfigListener

1.3. Global and Special Nacos Properties

The globalProperties is a required attribute in any @EnableNacos, @EnableNacosDiscovery or @EnableNacosConfig, and its type is @NacosProperties. globalProperties initializes "Global Nacos Properties" that will be used by other annotationsand components, e,g @NacosInjected. In other words, Global Nacos Properties" defines the global and default properties. It is set with the lowest priority and can be overridden if needed. The precedence of overiding rules is shown in the following table:

*.properties() defines special Nacos properties which come from one of the following:

• @NacosInjected.properties()
• @NacosConfigListener.properties()
• @NacosPropertySource.properties()
• @NacosConfigurationProperties.properties()

@NacosInjected
private ConfigService configService;
@NacosInjected(properties = @NacosProperties(encode = "UTF-8"))
private ConfigService configService2;
@NacosInjected(properties = @NacosProperties(encode = "GBK"))
private ConfigService configService3;
@NacosInjected
private NamingService namingService;
@NacosInjected(properties = @NacosProperties(encode = "UTF-8"))
private NamingService namingService2;
@NacosInjected(properties = @NacosProperties(encode = "GBK"))
private NamingService namingService3;
@Test
public void testInjection() {
    Assert.assertEquals(configService, configService2);
    Assert.assertNotEquals(configService2, configService3);
    Assert.assertEquals(namingService, namingService2);
    Assert.assertNotEquals(namingService2, namingService3);
}

• See Dependency Injection Sample

3. Externalized Configuration

Externalized configuration is a concept introduced by Spring Boot, which allows applications to receive external property sources to control runtime behavior. Nacos Server runs an isolation process outside the application to maintain the application configurations. nacos-spring-context provides properties features including object binding, dynamic configuration(auto-refreshed) and so on, and dependence on Spring Boot or Spring Cloud framework is required.

Here is a simple comparison between nacos-spring-context and Spring stack:

• See Auto-Refreshed Sample of @NacosConfigurationProperties
• See Sample of @NacosPropertySources and @NacosPropertySource

4. Event/Listener Driven

Nacos Event/Listener Driven is based on the standard Spring Event/Listener mechanism. The ApplicationEvent of Spring is an abstract super class for all Nacos Spring events:

• See Event/Listener Sample

Related Projects

• Nacos
• Nacos Spring
• Nacos Spring Boot
• Spring Cloud Alibaba