0
# Service Registration
1

2
Service registration enables applications to automatically register themselves with service registries and manage their lifecycle, including health monitoring and graceful shutdown. Spring Cloud Commons provides abstractions for various service registry implementations.
3

4
## Capabilities
5

6
### Service Registry Interface
7

8
Main interface for service registry operations.
9

10
```java { .api }
11
/**
12
 * Main interface for service registry operations
13
 */
14
public interface ServiceRegistry<R extends Registration> {
15
    /**
16
     * Register the registration
17
     * @param registration The registration to register
18
     */
19
    void register(R registration);
20
    
21
    /**
22
     * Deregister the registration
23
     * @param registration The registration to deregister
24
     */
25
    void deregister(R registration);
26
    
27
    /**
28
     * Close the ServiceRegistry
29
     */
30
    void close();
31
    
32
    /**
33
     * Set the status of the registration
34
     * @param registration The registration
35
     * @param status The status to set
36
     */
37
    void setStatus(R registration, String status);
38
    
39
    /**
40
     * Get the status of the registration
41
     * @param registration The registration
42
     * @return The status
43
     */
44
    <T> T getStatus(R registration);
45
}
46
```
47

48
**Usage Examples:**
49

50
```java
51
@Service
52
public class CustomRegistrationService {
53
    
54
    @Autowired
55
    private ServiceRegistry<Registration> serviceRegistry;
56
    
57
    public void registerCustomService() {
58
        Registration registration = createCustomRegistration();
59
        serviceRegistry.register(registration);
60
    }
61
    
62
    public void updateServiceStatus(Registration registration, String status) {
63
        serviceRegistry.setStatus(registration, status);
64
    }
65
    
66
    public void unregisterService(Registration registration) {
67
        serviceRegistry.deregister(registration);
68
    }
69
    
70
    private Registration createCustomRegistration() {
71
        return new DefaultServiceInstance(
72
            "custom-instance-1",
73
            "custom-service", 
74
            "localhost",
75
            8080,
76
            false
77
        );
78
    }
79
}
80
```
81

82
### Registration Interface
83

84
Marker interface for service registrations.
85

86
```java { .api }
87
/**
88
 * Marker interface extending ServiceInstance for registry operations
89
 */
90
public interface Registration extends ServiceInstance {
91
    // Inherits all ServiceInstance methods
92
}
93
```
94

95
### Auto Service Registration
96

97
Interface for automatic service registration lifecycle management.
98

99
```java { .api }
100
/**
101
 * Interface for automatic service registration lifecycle
102
 */
103
public interface AutoServiceRegistration {
104
    /**
105
     * Start the auto registration process
106
     */
107
    void start();
108
    
109
    /**
110
     * Stop the auto registration process
111
     */
112
    void stop();
113
    
114
    /**
115
     * Check if auto registration is running
116
     * @return true if running, false otherwise
117
     */
118
    boolean isRunning();
119
}
120
```
121

122
### Abstract Auto Service Registration
123

124
Base implementation for auto service registration.
125

126
```java { .api }
127
/**
128
 * Base implementation for auto service registration
129
 */
130
public abstract class AbstractAutoServiceRegistration<R extends Registration> 
131
    implements AutoServiceRegistration, SmartLifecycle, Ordered {
132
    
133
    /**
134
     * Create auto service registration
135
     * @param serviceRegistry The service registry
136
     * @param autoServiceRegistrationProperties Configuration properties
137
     * @param registration The registration
138
     */
139
    protected AbstractAutoServiceRegistration(ServiceRegistry<R> serviceRegistry,
140
                                            AutoServiceRegistrationProperties autoServiceRegistrationProperties,
141
                                            R registration);
142
    
143
    /**
144
     * Get the management registration
145
     * @return The management registration or null
146
     */
147
    protected abstract R getManagementRegistration();
148
    
149
    /**
150
     * Register the service
151
     */
152
    protected void register();
153
    
154
    /**
155
     * Register management service if enabled
156
     */
157
    protected void registerManagement();
158
    
159
    /**
160
     * Deregister the service
161
     */
162
    protected void deregister();
163
    
164
    /**
165
     * Deregister management service
166
     */
167
    protected void deregisterManagement();
168
    
169
    /**
170
     * Check if auto registration is enabled
171
     * @return true if enabled
172
     */
173
    protected boolean isEnabled();
174
    
175
    /**
176
     * Get the service ID
177
     * @return The service ID
178
     */
179
    protected String getAppName();
180
}
181
```
182

183
### Auto Service Registration Properties
184

185
Configuration properties for auto service registration.
186

187
```java { .api }
188
/**
189
 * Configuration properties for auto service registration
190
 */
191
@ConfigurationProperties("spring.cloud.service-registry.auto-registration")
192
public class AutoServiceRegistrationProperties {
193
    /**
194
     * Whether auto registration is enabled
195
     */
196
    private boolean enabled = true;
197
    
198
    /**
199
     * Whether to register management endpoints
200
     */
201
    private boolean registerManagement = true;
202
    
203
    /**
204
     * Whether to fail fast if registration fails
205
     */
206
    private boolean failFast = false;
207
    
208
    // getters and setters
209
    public boolean isEnabled() { return enabled; }
210
    public void setEnabled(boolean enabled) { this.enabled = enabled; }
211
    
212
    public boolean isRegisterManagement() { return registerManagement; }
213
    public void setRegisterManagement(boolean registerManagement) { 
214
        this.registerManagement = registerManagement; 
215
    }
216
    
217
    public boolean isFailFast() { return failFast; }
218
    public void setFailFast(boolean failFast) { this.failFast = failFast; }
219
}
220
```
221

222
### Service Registry Endpoint
223

224
Actuator endpoint for service registry operations.
225

226
```java { .api }
227
/**
228
 * Actuator endpoint for service registry operations
229
 */
230
@Endpoint(id = "service-registry")
231
public class ServiceRegistryEndpoint {
232
    /**
233
     * Create service registry endpoint
234
     * @param serviceRegistry The service registry
235
     */
236
    public ServiceRegistryEndpoint(ServiceRegistry serviceRegistry);
237
    
238
    /**
239
     * Get the status of the registration
240
     * @return The current status
241
     */
242
    @ReadOperation
243
    public ResponseEntity<?> getStatus();
244
    
245
    /**
246
     * Set the status of the registration
247
     * @param status The status to set
248
     * @return Response entity indicating success or failure
249
     */
250
    @WriteOperation
251
    public ResponseEntity<?> setStatus(String status);
252
}
253
```
254

255
**Usage Examples:**
256

257
```java
258
// Access the endpoint programmatically
259
@RestController
260
public class RegistrationController {
261
    
262
    @Autowired
263
    private ServiceRegistryEndpoint serviceRegistryEndpoint;
264
    
265
    @GetMapping("/registration/status")
266
    public ResponseEntity<?> getRegistrationStatus() {
267
        return serviceRegistryEndpoint.getStatus();
268
    }
269
    
270
    @PostMapping("/registration/status")
271
    public ResponseEntity<?> setRegistrationStatus(@RequestParam String status) {
272
        return serviceRegistryEndpoint.setStatus(status);
273
    }
274
}
275
```
276

277
## Configuration Properties
278

279
```properties
280
# Auto registration configuration
281
spring.cloud.service-registry.auto-registration.enabled=true
282
spring.cloud.service-registry.auto-registration.register-management=true
283
spring.cloud.service-registry.auto-registration.fail-fast=false
284

285
# Instance configuration (varies by registry implementation)
286
spring.cloud.service-registry.instance.hostname=localhost
287
spring.cloud.service-registry.instance.port=8080
288
spring.cloud.service-registry.instance.prefer-ip-address=false
289
spring.cloud.service-registry.instance.instance-id=${spring.application.name}:${server.port}
290
```
291

292
## Advanced Usage Examples
293

294
**Custom Registration Implementation:**
295

296
```java
297
@Component
298
public class CustomRegistration implements Registration {
299
    
300
    private final String instanceId;
301
    private final String serviceId;
302
    private final String host;
303
    private final int port;
304
    private final boolean secure;
305
    private final Map<String, String> metadata;
306
    
307
    public CustomRegistration(String instanceId, String serviceId, 
308
                            String host, int port, boolean secure) {
309
        this.instanceId = instanceId;
310
        this.serviceId = serviceId;
311
        this.host = host;
312
        this.port = port;
313
        this.secure = secure;
314
        this.metadata = new HashMap<>();
315
        
316
        // Add custom metadata
317
        this.metadata.put("version", "1.0.0");
318
        this.metadata.put("zone", "us-east-1");
319
    }
320
    
321
    @Override
322
    public String getInstanceId() {
323
        return instanceId;
324
    }
325
    
326
    @Override
327
    public String getServiceId() {
328
        return serviceId;
329
    }
330
    
331
    @Override
332
    public String getHost() {
333
        return host;
334
    }
335
    
336
    @Override
337
    public int getPort() {
338
        return port;
339
    }
340
    
341
    @Override
342
    public boolean isSecure() {
343
        return secure;
344
    }
345
    
346
    @Override
347
    public URI getUri() {
348
        String scheme = isSecure() ? "https" : "http";
349
        return URI.create(scheme + "://" + host + ":" + port);
350
    }
351
    
352
    @Override
353
    public Map<String, String> getMetadata() {
354
        return metadata;
355
    }
356
}
357
```
358

359
**Custom Auto Service Registration:**
360

361
```java
362
@Component
363
public class CustomAutoServiceRegistration extends AbstractAutoServiceRegistration<CustomRegistration> {
364
    
365
    private final CustomRegistration registration;
366
    private final CustomServiceRegistry serviceRegistry;
367
    
368
    public CustomAutoServiceRegistration(CustomServiceRegistry serviceRegistry,
369
                                       AutoServiceRegistrationProperties properties,
370
                                       CustomRegistration registration) {
371
        super(serviceRegistry, properties, registration);
372
        this.serviceRegistry = serviceRegistry;
373
        this.registration = registration;
374
    }
375
    
376
    @Override
377
    protected CustomRegistration getRegistration() {
378
        return registration;
379
    }
380
    
381
    @Override
382
    protected CustomRegistration getManagementRegistration() {
383
        // Return management registration if management endpoints should be registered
384
        if (getAutoServiceRegistrationProperties().isRegisterManagement()) {
385
            return new CustomRegistration(
386
                registration.getInstanceId() + "-management",
387
                registration.getServiceId() + "-management",
388
                registration.getHost(),
389
                getManagementPort(),
390
                registration.isSecure()
391
            );
392
        }
393
        return null;
394
    }
395
    
396
    @Override
397
    protected void register() {
398
        if (!isEnabled()) {
399
            return;
400
        }
401
        
402
        super.register();
403
        
404
        // Custom registration logic
405
        updateHealthStatus("UP");
406
    }
407
    
408
    @Override
409
    protected void deregister() {
410
        super.deregister();
411
        
412
        // Custom deregistration logic
413
        updateHealthStatus("DOWN");
414
    }
415
    
416
    private void updateHealthStatus(String status) {
417
        serviceRegistry.setStatus(registration, status);
418
    }
419
    
420
    private int getManagementPort() {
421
        // Logic to determine management port
422
        return 8081;
423
    }
424
}
425
```
426

427
**Service Registry Event Handling:**
428

429
```java
430
@Component
431
public class ServiceRegistryEventHandler {
432
    
433
    private static final Logger log = LoggerFactory.getLogger(ServiceRegistryEventHandler.class);
434
    
435
    @EventListener
436
    public void handleInstanceRegistered(InstanceRegisteredEvent<?> event) {
437
        log.info("Service instance registered: {}", event.getConfig());
438
        
439
        // Custom logic after registration
440
        notifyServiceDiscovery(event);
441
    }
442
    
443
    @EventListener
444
    public void handleInstancePreRegistered(InstancePreRegisteredEvent event) {
445
        log.info("Service instance about to register: {}", event.getRegistration());
446
        
447
        // Custom logic before registration
448
        validateRegistration(event.getRegistration());
449
    }
450
    
451
    private void notifyServiceDiscovery(InstanceRegisteredEvent<?> event) {
452
        // Custom notification logic
453
    }
454
    
455
    private void validateRegistration(Registration registration) {
456
        // Custom validation logic
457
        if (registration.getHost() == null || registration.getHost().isEmpty()) {
458
            throw new IllegalArgumentException("Host cannot be null or empty");
459
        }
460
    }
461
}
462
```
463

464
**Health Check Integration:**
465

466
```java
467
@Component
468
public class ServiceRegistryHealthIndicator implements HealthIndicator {
469
    
470
    private final ServiceRegistry<Registration> serviceRegistry;
471
    private final Registration registration;
472
    
473
    public ServiceRegistryHealthIndicator(ServiceRegistry<Registration> serviceRegistry,
474
                                        Registration registration) {
475
        this.serviceRegistry = serviceRegistry;
476
        this.registration = registration;
477
    }
478
    
479
    @Override
480
    public Health health() {
481
        try {
482
            Object status = serviceRegistry.getStatus(registration);
483
            return Health.up()
484
                .withDetail("status", status)
485
                .withDetail("serviceId", registration.getServiceId())
486
                .withDetail("instanceId", registration.getInstanceId())
487
                .build();
488
        } catch (Exception e) {
489
            return Health.down()
490
                .withDetail("error", e.getMessage())
491
                .build();
492
        }
493
    }
494
}
495
```