Java SDK
Overview
Maven coordinates
Note: Since version 2.0, the Nacos Java SDK introduced gRPC, and use shaded technology to directly encapsulate some dependencies into nacos-client in order to avoid conflicts caused by different versions of gRPC introduced by users, which resulting in a larger nacos-client. If the users don’t introduce gRPC or confirms that there is no conflict between the versions, and wants to use the pure version of nacos-client to reduce dependencies, users can use the classifier to specify the pure version.
Configuration Management
Get configuration
Description
Get configuration from Nacos when a service starts.
Request parameters
Name
|
Type
|
Description
|
dataId
|
string
|
Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
|
group
|
string
|
Configuration group. To ensure uniqueness, format such as product name: module name (for example, Nacos:Test) is preferred. Use alphabetical letters and these four special characters (".", ":", "-",
"_") only. Up to 128 characters are allowed.
|
timeout
|
long
|
Length of configuration read time-out (in ms). Recommended value: 3000.
|
Return values
Type | Description |
---|---|
string | configuration value |
Request example
Exception specification
A ConfigException is thrown in case of a configuration read time-out or a network error.
Listen configuration
Description
Use dynamic configuration listening API to enable Nacos to send configuration change notifications.
Request parameters
Name
|
Type
|
Description
|
dataId
|
string
|
Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
|
group
|
string
|
Configuration group. To ensure uniqueness, format such as product name: module name (for example, Nacos:Test) is preferred. Use alphabetical letters and these four special characters (".", ":", "-",
"_") only. Up to 128 characters are allowed.
|
listener
|
Config Change Listener
|
Listener. Configuration changes go into the callback function of the listener.
|
Return values
Type | Description |
---|---|
string | Configuration value. This value is returned through the callback function during initialization or configuration modification. |
Request example
Delete Listening
Description
Cancel listen configuration. No more notification after cancellation.
Request parameters
Name
|
Type
|
Description
|
dataId
|
string
|
Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
|
group
|
string
|
Configuration group
|
listener
|
ConfigChangeListenerAdapter
|
Listener. Configuration changes go into the callback function of the listener.
|
Request example
Publish configuration
Description
Publish Nacos configurations automatically to reduce the operation and maintenance cost.
Note: It uses the same publishing interface to create or modify a configuration. If the specified configuration doesn’t exist, it will create a configuration. If the specified configuration exists, it will update the configuration.
Request parameters
Name | Type | Description |
---|---|---|
dataId | string | Configuration ID. Naming rule is similar to package.class (com.taobao.tc.refund.log.level) is used to ensure the global uniqueness We recommend that you define class by business meaning. All characters must be in lower case. Use alphabetical letters and these four special characters (”.”, ”:”, ”-”, ”_”) only. Up to 256 characters are allowed. |
group | string | Configuration group. We recommend that you use product name: module name (for example Nacos) to ensure the uniqueness. Use alphabetical letters and these four special characters (”.”, ”:”, ”-”, ”_”) only. Up to 128 characters are allowed. |
content | string | Configuration content. No more than 100K bytes. |
type | string | @Since 1.4.1. Configuration type. See com.alibaba.nacos.api.config.ConfigType, default as TEXT. |
Response parameters
Type | Description |
---|---|
boolean | If the publishing is successful |
Request example
Exceptions
In case of reading configuration timeout or network issues, ConfigException exception is thrown.
Delete configuration
Description
It deletes Nacos configurations automatically with program to reduce operation and maintenance costs with automation.
Note: If the specified configuration exists, then it deletes the configuration. If the specified configuration doesn’t exist, then it returns a successful message.
Request parameters
Parameter name | Parameter type | Description |
---|---|---|
dataId | String | Configuration ID |
group | String | Configuration group |
Response parameters
Parameter type | Description |
---|---|
boolean | If the deletion is successful |
Request example
Exceptions
In case of reading configuration timeout or network issues, ConfigException exception is thrown.
Service Discovery SDK
Register Instance
Description
Register an instance to service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
ip | String | instance ip |
port | int | instance port |
clusterName | String | cluster name |
instance | Refer to Java docs | instance properties |
Response
void
Request Example
Deregister Instance
Description
Remove instance from service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
ip | String | instance ip |
port | int | instance port |
clusterName | String | cluster name |
Response
None
Request Example
Get all instances of service
Description
Get all instances of service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
clusters | List | cluster list |
Response
List<Instance> instance list。
Request Example
Get filtered list of instance
Description
Get healthy or unhealthy instances of service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
clusters | List | cluster list |
healthy | boolean | healthy or not |
Response
List<Instance> instance list.
Request Example
Get one healthy instance
Description
Get one healthy instance selected by load-balance strategy.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
clusters | List | cluster list |
Response
Instance
Request Example
Listen Service
Description
Listen for changes of instances under a service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
clusters | List | cluster list |
listener | EventListener | event listener |
Response
void
Request Example
Unlisten Service
Description
Cancel listening service.
Request Parameters
Name | Type | Description |
---|---|---|
serviceName | String | service name |
clusters | List | cluster list |
listener | EventListener | event listener |
Response
void