Java SDK Properties

1. How the Java SDK Reads Configuration

1.1. Introduction

The Nacos Java SDK uses NacosClientProperties to manage client configuration items in a unified way. Its role is similar to Spring Environment.

1.2. Features

• Unified management of Properties, JVM parameters, environment variables, and default values.
• Priority-based lookup. The default lookup order is properties -> JVM parameters -> environment variables -> default values. You can adjust the priority order. By default, properties has the highest priority.
• Configuration isolation. Except for global configuration sources, each NacosClientProperties object is isolated from the others.

1.3. Usage

1.3.1. Priority

The default priority is properties. You can adjust it in either of the following ways:

- (JVM parameter) -Dnacos.env.first=PROPERTIES|JVM|ENV
- (environment variable) NACOS_ENV_FIRST=PROPERTIES|JVM|ENV

The default behavior is equivalent to -Dnacos.env.first=PROPERTIES.

If both methods are configured, the client first reads the priority setting from the JVM parameter. If the JVM parameter is not found, it reads the setting from the environment variable. If neither method specifies a priority, the default priority is properties.

Default priority:

Priority: PROPERTIES

Priority: JVM

Priority: ENV

1.3.2. Lookup

NacosClientProperties searches configuration by the specified priority. Using the default priority (PROPERTIES) as an example, if you want to obtain the value of a key named key1, the lookup order is as follows:

NacosClientProperties searches in the order shown above until it finds a value.

1.3.3. Configuration Isolation

To support scenarios with multiple registries or multiple config centers, NacosClientProperties introduces configuration isolation. NacosClientProperties has four value sources: user-defined properties, JVM parameters, environment variables, and default values. Among them, JVM parameters, environment variables, and default values are shared globally and cannot be isolated. Therefore, only the user-defined Properties object can be isolated. Each NacosClientProperties object contains a different Properties object, so configurations do not affect each other.

Note: Globally shared configuration, including JVM parameters, environment variables, and default values, cannot be changed after initialization. The setProperty method cannot modify them. setProperty only modifies values in the Properties object contained by the current NacosClientProperties object.

1.3.4. Configuration Derivation

Configuration derivation is introduced on top of configuration isolation so that configuration can be inherited. All NacosClientProperties objects are derived from the NacosClientProperties.PROTOTYPE object. There is no other way to create a NacosClientProperties object.

// global properties
NacosClientProperties.PROTOTYPE.setProperty("global-key1","global-value1");

// properties1
NacosClientProperties properties1 = NacosClientProperties.PROTOTYPE.derive();
properties1.

setProperty("properties1-key1","properties1-value1");

// properties2
NacosClientProperties properties2 = properties1.derive();
properties2.

setProperty("properties2-key1","properties2-value1");

The preceding code is shown in the following diagram:

How does lookup work in this case? Using the default priority (PROPERTIES) as an example:

// value == global-value1
String value = properties2.getProperty("global-key1");

1.3.5. API

2. Java SDK Configuration Parameter List

2.1. Common Parameters

Common parameters take effect when initializing both the registry NamingService and the config center ConfigServie:

2.2. Config Center Parameters

The following parameters take effect only when initializing the config center ConfigServie:

2.3. Registry Parameters

The following parameters take effect only when initializing the registry NamingServie:

2.4. Connection Parameters

When the Nacos Java SDK connects to Nacos Server, you can configure a set of parameters to improve fault tolerance during network jitter.

2.5. Other Parameters

Some parameters in the Nacos Java SDK have little impact at runtime and must remain globally consistent. Therefore, these parameters currently need to be set through JVM parameters (-D) or environment variables. In most cases, use the default values and configure them only for special scenarios.