0
# Nacos Client
1

2
Nacos client library for dynamic service discovery and configuration management in cloud native applications and microservices platforms. Nacos (Dynamic Naming and Configuration Service) provides essential infrastructure capabilities for building scalable, resilient distributed systems with centralized service management and configuration control.
3

4
## Package Information
5

6
- **Package Name**: nacos-client
7
- **Language**: Java  
8
- **Package Manager**: Maven
9
- **Group ID**: com.alibaba.nacos
10
- **Artifact ID**: nacos-client
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
      <groupId>com.alibaba.nacos</groupId>
15
      <artifactId>nacos-client</artifactId>
16
      <version>3.0.2</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import com.alibaba.nacos.api.NacosFactory;
24
import com.alibaba.nacos.api.config.ConfigService;
25
import com.alibaba.nacos.api.naming.NamingService;
26
import com.alibaba.nacos.api.exception.NacosException;
27
```
28

29
Specialized services:
30
```java
31
import com.alibaba.nacos.api.config.ConfigFactory;
32
import com.alibaba.nacos.api.naming.NamingFactory;
33
import com.alibaba.nacos.api.lock.NacosLockFactory;
34
import com.alibaba.nacos.api.lock.LockService;
35
```
36

37
## Basic Usage
38

39
```java
40
import com.alibaba.nacos.api.NacosFactory;
41
import com.alibaba.nacos.api.config.ConfigService;
42
import com.alibaba.nacos.api.naming.NamingService;
43
import com.alibaba.nacos.api.naming.pojo.Instance;
44
import com.alibaba.nacos.api.exception.NacosException;
45

46
import java.util.List;
47
import java.util.Properties;
48

49
public class NacosClientExample {
50
    public static void main(String[] args) throws NacosException {
51
        // Configure connection properties
52
        Properties properties = new Properties();
53
        properties.setProperty("serverAddr", "localhost:8848");
54
        properties.setProperty("namespace", "public");
55
        
56
        // Configuration Management
57
        ConfigService configService = NacosFactory.createConfigService(properties);
58
        
59
        // Get configuration
60
        String config = configService.getConfig("example.properties", "DEFAULT_GROUP", 5000);
61
        System.out.println("Configuration: " + config);
62
        
63
        // Publish configuration
64
        boolean published = configService.publishConfig("example.properties", "DEFAULT_GROUP", "key=value");
65
        
66
        // Service Discovery
67
        NamingService namingService = NacosFactory.createNamingService(properties);
68
        
69
        // Register service instance
70
        Instance instance = new Instance();
71
        instance.setIp("192.168.1.100");
72
        instance.setPort(8080);
73
        instance.setWeight(1.0);
74
        namingService.registerInstance("user-service", instance);
75
        
76
        // Discover service instances
77
        List<Instance> instances = namingService.getAllInstances("user-service");
78
        System.out.println("Found " + instances.size() + " instances");
79
    }
80
}
81
```
82

83
## Architecture
84

85
Nacos client provides a multi-service architecture with clear separation of concerns:
86

87
- **Configuration Service**: Centralized configuration management with real-time updates, change listeners, and atomic operations
88
- **Naming Service**: Service registration, discovery, and health monitoring with support for clusters and load balancing
89
- **Lock Service**: Distributed locking for coordination across microservices
90
- **Event System**: Reactive listeners for configuration changes and service instance updates
91

92
The client uses a factory pattern for service creation, supports multiple server addresses for high availability, and provides extensive customization through properties configuration. All services support namespace isolation for multi-tenant environments.
93

94
## Capabilities
95

96
### Configuration Management
97

98
Centralized configuration management with real-time updates, change listeners, atomic CAS operations, and fuzzy pattern-based watching. Supports multiple configuration formats and provides filtering mechanisms for request/response processing.
99

100
```java { .api }
101
public interface ConfigService {
102
    String getConfig(String dataId, String group, long timeoutMs) throws NacosException;
103
    boolean publishConfig(String dataId, String group, String content) throws NacosException;
104
    boolean removeConfig(String dataId, String group) throws NacosException;
105
    void addListener(String dataId, String group, Listener listener) throws NacosException;
106
    void removeListener(String dataId, String group, Listener listener);
107
}
108
```
109

110
[Configuration Management](./configuration.md)
111

112
### Service Discovery and Registration  
113

114
Service registration, discovery, and health monitoring with support for weighted load balancing, cluster management, and real-time instance updates. Includes batch operations and event-driven programming model.
115

116
```java { .api }
117
public interface NamingService {
118
    void registerInstance(String serviceName, Instance instance) throws NacosException;
119
    void deregisterInstance(String serviceName, Instance instance) throws NacosException;
120
    List<Instance> getAllInstances(String serviceName) throws NacosException;
121
    List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
122
    Instance selectOneHealthyInstance(String serviceName) throws NacosException;
123
    void subscribe(String serviceName, EventListener listener) throws NacosException;
124
    List<ServiceInfo> getSubscribeServices() throws NacosException;
125
}
126
```
127

128
[Service Discovery](./service-discovery.md)
129

130
### Distributed Locking
131

132
Distributed locking capabilities for coordination and synchronization across microservices. Supports lock expiration, try-lock operations, and remote lock management.
133

134
```java { .api }
135
public interface LockService {
136
    Boolean lock(LockInstance instance) throws NacosException;
137
    Boolean unLock(LockInstance instance) throws NacosException;
138
    Boolean remoteTryLock(LockInstance instance) throws NacosException;
139
    Boolean remoteReleaseLock(LockInstance instance) throws NacosException;
140
    void shutdown() throws NacosException;
141
}
142
```
143

144
[Distributed Locking](./distributed-locking.md)
145

146
### Factory and Utilities
147

148
Service factory methods, utility classes, annotation support, and comprehensive exception handling. Includes capability management and extensive configuration options.
149

150
```java { .api }
151
public class NacosFactory {
152
    public static ConfigService createConfigService(Properties properties) throws NacosException;
153
    public static NamingService createNamingService(Properties properties) throws NacosException;
154
    public static LockService createLockService(Properties properties) throws NacosException;
155
}
156
```
157

158
[Factory and Utilities](./factory-utilities.md)
159

160
## Types
161

162
### Core Data Models
163

164
```java { .api }
165
public class Instance {
166
    private String instanceId;
167
    private String ip;
168
    private int port;
169
    private double weight;
170
    private boolean healthy;
171
    private boolean enabled;
172
    private boolean ephemeral;
173
    private String clusterName;
174
    private String serviceName;
175
    private Map<String, String> metadata;
176
    
177
    // Constructor and getter/setter methods
178
    public Instance();
179
    public String getIp();
180
    public void setIp(String ip);
181
    public int getPort();
182
    public void setPort(int port);
183
    public double getWeight();
184
    public void setWeight(double weight);
185
    public boolean isHealthy();
186
    public void setHealthy(boolean healthy);
187
    public Map<String, String> getMetadata();
188
    public void setMetadata(Map<String, String> metadata);
189
}
190

191
public class ServiceInfo {
192
    private String name;
193
    private String groupName;
194
    private String clusters;
195
    private List<Instance> hosts;
196
    private long cacheMillis;
197
    private long lastRefTime;
198
    
199
    // Constructor and getter/setter methods
200
    public String getName();
201
    public void setName(String name);
202
    public List<Instance> getHosts();
203
    public void setHosts(List<Instance> hosts);
204
}
205

206
public class NacosException extends Exception {
207
    public static final int CLIENT_INVALID_PARAM = 400;
208
    public static final int CLIENT_OVER_THRESHOLD = 503;
209
    public static final int SERVER_ERROR = 500;
210
    public static final int BAD_GATEWAY = 502;
211
    public static final int RESOURCE_NOT_FOUND = 404;
212
    
213
    public NacosException(int errCode, String errMsg);
214
    public int getErrCode();
215
    public String getErrMsg();
216
}
217
```
218

219
### Configuration Events
220

221
```java { .api }
222
public class ConfigChangeEvent {
223
    private String dataId;
224
    private String group;
225
    private String namespace;
226
    private String content;
227
    private String oldContent;
228
    private PropertyChangeType changeType;
229
    
230
    public String getDataId();
231
    public String getGroup(); 
232
    public String getContent();
233
    public PropertyChangeType getChangeType();
234
}
235

236
public interface Listener {
237
    void receiveConfigInfo(String configInfo);
238
    Executor getExecutor();
239
}
240
```
241

242
### Constants and Enums
243

244
```java { .api }
245
public enum ConfigType {
246
    PROPERTIES, XML, JSON, TEXT, HTML, YAML, TOML, UNSET
247
}
248

249
public enum PropertyChangeType {
250
    ADDED, MODIFIED, DELETED
251
}
252

253
public class PropertyKeyConst {
254
    public static final String SERVER_ADDR = "serverAddr";
255
    public static final String NAMESPACE = "namespace";
256
    public static final String USERNAME = "username";
257
    public static final String PASSWORD = "password";
258
    public static final String CLUSTER_NAME = "clusterName";
259
    public static final String ENCODE = "encode";
260
}
261
```