0
# Service Discovery and Registration
1

2
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.
3

4
## Capabilities
5

6
### Service Registration
7

8
Register and deregister service instances with comprehensive metadata support.
9

10
```java { .api }
11
public interface NamingService {
12
    // Register instance with service name, IP, and port
13
    void registerInstance(String serviceName, String ip, int port) throws NacosException;
14
    
15
    // Register instance with group specification
16
    void registerInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
17
    
18
    // Register instance object with full configuration
19
    void registerInstance(String serviceName, Instance instance) throws NacosException;
20
    
21
    // Register instance with group and instance object
22
    void registerInstance(String serviceName, String groupName, Instance instance) throws NacosException;
23
    
24
    // Batch register multiple instances
25
    void batchRegisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
26
    
27
    // Deregister instance by IP and port
28
    void deregisterInstance(String serviceName, String ip, int port) throws NacosException;
29
    
30
    // Deregister instance with group specification
31
    void deregisterInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
32
    
33
    // Deregister instance object
34
    void deregisterInstance(String serviceName, Instance instance) throws NacosException;
35
    
36
    // Deregister instance with group and instance object
37
    void deregisterInstance(String serviceName, String groupName, Instance instance) throws NacosException;
38
    
39
    // Batch deregister multiple instances
40
    void batchDeregisterInstance(String serviceName, String groupName, List<Instance> instances) throws NacosException;
41
}
42
```
43

44
#### Usage Examples
45

46
```java
47
import com.alibaba.nacos.api.naming.NamingService;
48
import com.alibaba.nacos.api.naming.NamingFactory;
49
import com.alibaba.nacos.api.naming.pojo.Instance;
50

51
// Create naming service
52
Properties props = new Properties();
53
props.setProperty("serverAddr", "localhost:8848");
54
NamingService namingService = NamingFactory.createNamingService(props);
55

56
// Simple registration
57
namingService.registerInstance("user-service", "192.168.1.100", 8080);
58

59
// Register with metadata
60
Instance instance = new Instance();
61
instance.setIp("192.168.1.100");
62
instance.setPort(8080);
63
instance.setWeight(2.0);
64
instance.setClusterName("beijing");
65
instance.setHealthy(true);
66
instance.setEnabled(true);
67
instance.setEphemeral(true);
68

69
// Add custom metadata
70
Map<String, String> metadata = new HashMap<>();
71
metadata.put("version", "1.0.0");
72
metadata.put("region", "us-west");
73
instance.setMetadata(metadata);
74

75
namingService.registerInstance("user-service", "PROD_GROUP", instance);
76

77
// Batch registration
78
List<Instance> instances = Arrays.asList(instance1, instance2, instance3);
79
namingService.batchRegisterInstance("user-service", "PROD_GROUP", instances);
80

81
// Batch deregistration
82
namingService.batchDeregisterInstance("user-service", "PROD_GROUP", instances);
83
```
84

85
### Service Discovery
86

87
Discover service instances with filtering and selection capabilities.
88

89
```java { .api }
90
public interface NamingService {
91
    // Get all instances of a service
92
    List<Instance> getAllInstances(String serviceName) throws NacosException;
93
    
94
    // Get all instances with group specification
95
    List<Instance> getAllInstances(String serviceName, String groupName) throws NacosException;
96
    
97
    // Get healthy or unhealthy instances
98
    List<Instance> getAllInstances(String serviceName, boolean healthy) throws NacosException;
99
    
100
    // Get instances from specific clusters
101
    List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;
102
    
103
    // Get all instances with full options
104
    List<Instance> getAllInstances(String serviceName, String groupName, List<String> clusters, boolean subscribe) throws NacosException;
105
    
106
    // Select healthy instances only
107
    List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
108
    
109
    // Select instances with group and health filter
110
    List<Instance> selectInstances(String serviceName, String groupName, boolean healthy) throws NacosException;
111
    
112
    // Select instances with cluster filter
113
    List<Instance> selectInstances(String serviceName, String groupName, List<String> clusters, boolean healthy) throws NacosException;
114
    
115
    // Select one healthy instance (load balancing)
116
    Instance selectOneHealthyInstance(String serviceName) throws NacosException;
117
    
118
    // Select one healthy instance with group
119
    Instance selectOneHealthyInstance(String serviceName, String groupName) throws NacosException;
120
    
121
    // Select one healthy instance from specific clusters
122
    Instance selectOneHealthyInstance(String serviceName, String groupName, List<String> clusters) throws NacosException;
123
}
124
```
125

126
#### Usage Examples
127

128
```java
129
// Get all instances
130
List<Instance> allInstances = namingService.getAllInstances("user-service");
131

132
// Get healthy instances only
133
List<Instance> healthyInstances = namingService.selectInstances("user-service", true);
134

135
// Get instances from specific clusters
136
List<String> clusters = Arrays.asList("beijing", "shanghai");
137
List<Instance> clusterInstances = namingService.getAllInstances("user-service", clusters);
138

139
// Load balancing - select one healthy instance
140
Instance instance = namingService.selectOneHealthyInstance("user-service");
141
if (instance != null) {
142
    String serviceUrl = "http://" + instance.getIp() + ":" + instance.getPort();
143
    // Make HTTP call to service
144
}
145

146
// Advanced filtering with group and clusters
147
List<Instance> prodInstances = namingService.selectInstances(
148
    "user-service", 
149
    "PROD_GROUP", 
150
    Arrays.asList("us-west", "us-east"),
151
    true  // healthy only
152
);
153
```
154

155
### Service Event Subscription
156

157
Real-time notifications of service instance changes through event listeners.
158

159
```java { .api }
160
public interface NamingService {
161
    // Subscribe to service instance changes
162
    void subscribe(String serviceName, EventListener listener) throws NacosException;
163
    
164
    // Subscribe with group specification
165
    void subscribe(String serviceName, String groupName, EventListener listener) throws NacosException;
166
    
167
    // Subscribe with cluster filter
168
    void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
169
    
170
    // Subscribe with full options
171
    void subscribe(String serviceName, String groupName, List<String> clusters, EventListener listener) throws NacosException;
172
    
173
    // Unsubscribe from service changes
174
    void unsubscribe(String serviceName, EventListener listener) throws NacosException;
175
    
176
    // Unsubscribe with group
177
    void unsubscribe(String serviceName, String groupName, EventListener listener) throws NacosException;
178
    
179
    // Unsubscribe with clusters
180
    void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;
181
    
182
    // Unsubscribe with full options
183
    void unsubscribe(String serviceName, String groupName, List<String> clusters, EventListener listener) throws NacosException;
184
}
185

186
// Event listener interface
187
public interface EventListener {
188
    void onEvent(Event event);
189
}
190

191
// Naming event containing service changes
192
public class NamingEvent extends Event {
193
    private String serviceName;
194
    private String groupName;
195
    private String clusters;
196
    private List<Instance> instances;
197
    
198
    public String getServiceName();
199
    public String getGroupName();
200
    public String getClusters();
201
    public List<Instance> getInstances();
202
}
203
```
204

205
#### Usage Examples
206

207
```java
208
import com.alibaba.nacos.api.naming.listener.EventListener;
209
import com.alibaba.nacos.api.naming.listener.NamingEvent;
210

211
// Create event listener
212
EventListener listener = new EventListener() {
213
    @Override
214
    public void onEvent(Event event) {
215
        if (event instanceof NamingEvent) {
216
            NamingEvent namingEvent = (NamingEvent) event;
217
            System.out.println("Service changed: " + namingEvent.getServiceName());
218
            
219
            List<Instance> instances = namingEvent.getInstances();
220
            System.out.println("Current instances: " + instances.size());
221
            
222
            // Update local service registry
223
            updateLocalRegistry(namingEvent.getServiceName(), instances);
224
        }
225
    }
226
};
227

228
// Subscribe to service changes
229
namingService.subscribe("user-service", listener);
230

231
// Subscribe with cluster filter
232
namingService.subscribe("user-service", "PROD_GROUP", 
233
                       Arrays.asList("beijing", "shanghai"), listener);
234
```
235

236
### Fuzzy Watching
237

238
Pattern-based service watching for monitoring multiple services with wildcards.
239

240
```java { .api }
241
public interface NamingService {
242
    // Start fuzzy watching with group pattern only
243
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
244
    
245
    // Start fuzzy watching with both service and group patterns
246
    void fuzzyWatch(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
247
    
248
    // Start fuzzy watching and return matching service keys
249
    Future<ListView<String>> fuzzyWatchWithServiceKeys(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
250
    
251
    // Cancel fuzzy watching
252
    void cancelFuzzyWatch(String serviceNamePattern, String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
253
}
254

255
// Fuzzy watch event watcher interface
256
public interface FuzzyWatchEventWatcher {
257
    // Handle set of naming events
258
    void onEvent(Set<NamingEvent> events);
259
}
260
```
261

262
#### Usage Examples
263

264
```java
265
import com.alibaba.nacos.api.naming.listener.FuzzyWatchEventWatcher;
266

267
// Watch all microservices with pattern
268
FuzzyWatchEventWatcher watcher = new FuzzyWatchEventWatcher() {
269
    @Override
270
    public void onEvent(Set<NamingEvent> events) {
271
        for (NamingEvent event : events) {
272
            System.out.println("Service changed: " + event.getServiceName());
273
            updateServiceRegistry(event.getServiceName(), event.getInstances());
274
        }
275
    }
276
};
277

278
// Watch all services ending with "-service" in DEFAULT_GROUP
279
namingService.fuzzyWatch("*-service", "DEFAULT_GROUP", watcher);
280

281
// Watch all services in production group (group pattern only)
282
namingService.fuzzyWatch("PROD_GROUP", watcher);
283

284
// Watch all services in groups matching pattern
285
namingService.fuzzyWatch("*", "PROD_*", watcher);
286
```
287

288
### Service Management
289

290
Service listing and metadata management operations.
291

292
```java { .api }
293
public interface NamingService {
294
    // Get paginated list of services
295
    ListView<String> getServicesOfServer(int pageNo, int pageSize) throws NacosException;
296
    
297
    // Get services with group filter
298
    ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName) throws NacosException;
299
    
300
    // Get services with selector
301
    ListView<String> getServicesOfServer(int pageNo, int pageSize, AbstractSelector selector) throws NacosException;
302
    
303
    // Get services with full options
304
    ListView<String> getServicesOfServer(int pageNo, int pageSize, String groupName, AbstractSelector selector) throws NacosException;
305
    
306
    // Get all subscribed services of current client
307
    List<ServiceInfo> getSubscribeServices() throws NacosException;
308
    
309
    // Get server status
310
    String getServerStatus();
311
    
312
    // Shutdown service
313
    void shutDown() throws NacosException;
314
}
315
```
316

317
## Types
318

319
### Service Instance Model
320

321
```java { .api }
322
public class Instance {
323
    private String instanceId;
324
    private String ip;
325
    private int port;
326
    private double weight;
327
    private boolean healthy;
328
    private boolean enabled;
329
    private boolean ephemeral;
330
    private String clusterName;
331
    private String serviceName;
332
    private Map<String, String> metadata;
333
    
334
    // Constructors
335
    public Instance();
336
    
337
    // Core properties
338
    public String getInstanceId();
339
    public void setInstanceId(String instanceId);
340
    
341
    public String getIp();
342
    public void setIp(String ip);
343
    
344
    public int getPort();
345
    public void setPort(int port);
346
    
347
    // Load balancing weight
348
    public double getWeight();
349
    public void setWeight(double weight);
350
    
351
    // Health and availability
352
    public boolean isHealthy();
353
    public void setHealthy(boolean healthy);
354
    
355
    public boolean isEnabled();
356
    public void setEnabled(boolean enabled);
357
    
358
    // Persistence mode
359
    public boolean isEphemeral();
360
    public void setEphemeral(boolean ephemeral);
361
    
362
    // Cluster assignment
363
    public String getClusterName();
364
    public void setClusterName(String clusterName);
365
    
366
    // Service association
367
    public String getServiceName();
368
    public void setServiceName(String serviceName);
369
    
370
    // Custom attributes
371
    public Map<String, String> getMetadata();
372
    public void setMetadata(Map<String, String> metadata);
373
    
374
    // Utility methods
375
    public String toInetAddr();
376
    public boolean containsMetadata(String key, String value);
377
}
378
```
379

380
### Service Information
381

382
```java { .api }
383
public class ServiceInfo {
384
    private String name;
385
    private String groupName;
386
    private String clusters;
387
    private List<Instance> hosts;
388
    private long cacheMillis;
389
    private long lastRefTime;
390
    private String checksum;
391
    private boolean allIPs;
392
    private boolean reachProtectionThreshold;
393
    
394
    // Service identification
395
    public String getName();
396
    public void setName(String name);
397
    
398
    public String getGroupName();
399
    public void setGroupName(String groupName);
400
    
401
    // Cluster information
402
    public String getClusters();
403
    public void setClusters(String clusters);
404
    
405
    // Instance list
406
    public List<Instance> getHosts();
407
    public void setHosts(List<Instance> hosts);
408
    
409
    // Caching and refresh
410
    public long getCacheMillis();
411
    public void setCacheMillis(long cacheMillis);
412
    
413
    public long getLastRefTime();
414
    public void setLastRefTime(long lastRefTime);
415
    
416
    // Validation and protection
417
    public String getChecksum();
418
    public boolean isReachProtectionThreshold();
419
    
420
    // Utility methods
421
    public String getKey();
422
    public String getKeyEncoded();
423
    public boolean validate();
424
}
425
```
426

427
### Service and Cluster Models
428

429
```java { .api }
430
public class Service {
431
    private String name;
432
    private String groupName;
433
    private String appName;
434
    private float protectThreshold;
435
    private Map<String, String> metadata;
436
    
437
    public String getName();
438
    public void setName(String name);
439
    
440
    public String getGroupName();
441
    public void setGroupName(String groupName);
442
    
443
    public String getAppName();
444
    public void setAppName(String appName);
445
    
446
    public float getProtectThreshold();
447
    public void setProtectThreshold(float protectThreshold);
448
    
449
    public Map<String, String> getMetadata();
450
    public void setMetadata(Map<String, String> metadata);
451
}
452

453
public class Cluster {
454
    private String name;
455
    private AbstractHealthChecker healthChecker;
456
    private int defaultPort;
457
    private int defaultCheckPort;
458
    private boolean useIPPort4Check;
459
    private Map<String, String> metadata;
460
    
461
    public String getName();
462
    public void setName(String name);
463
    
464
    public AbstractHealthChecker getHealthChecker();
465
    public void setHealthChecker(AbstractHealthChecker healthChecker);
466
    
467
    public int getDefaultPort();
468
    public void setDefaultPort(int defaultPort);
469
    
470
    public Map<String, String> getMetadata();
471
    public void setMetadata(Map<String, String> metadata);
472
}
473
```
474

475
### Pagination and Selection
476

477
```java { .api }
478
public class ListView<T> {
479
    private int count;
480
    private List<T> data;
481
    
482
    public int getCount();
483
    public void setCount(int count);
484
    
485
    public List<T> getData();
486
    public void setData(List<T> data);
487
}
488

489
// Abstract selector for filtering
490
public abstract class AbstractSelector {
491
    private String type;
492
    
493
    public String getType();
494
    public void setType(String type);
495
    
496
    public abstract String toJsonString();
497
}
498

499
// Expression-based selector
500
public class ExpressionSelector extends AbstractSelector {
501
    private String expression;
502
    
503
    public String getExpression();
504
    public void setExpression(String expression);
505
    
506
    @Override
507
    public String toJsonString();
508
}
509
```
510

511
### Naming Utilities
512

513
```java { .api }
514
public class NamingUtils {
515
    public static final String NAMING_INSTANCE_ID_SPLITTER = "#";
516
    public static final String DEFAULT_GROUP = "DEFAULT_GROUP";
517
    
518
    // Service name parsing
519
    public static String getServiceName(String serviceNameWithGroup);
520
    public static String getGroupName(String serviceNameWithGroup);
521
    public static String getGroupedName(String serviceName, String groupName);
522
    
523
    // Instance utilities
524
    public static String getInstanceId(Instance instance);
525
    
526
    // Validation
527
    public static void checkServiceName(String serviceName);
528
    public static void checkInstanceIsLegal(Instance instance);
529
}
530
```