tessl/maven-org-springframework-cloud--spring-cloud-commons
Spring Cloud Commons provides foundational abstractions and utilities for service discovery, load balancing, circuit breakers, and cloud-native application development.
—
Pending
service-registration.mddocs/
Service Registration
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.
Capabilities
Service Registry Interface
Main interface for service registry operations.
/**
* Main interface for service registry operations
*/
public interface ServiceRegistry<R extends Registration> {
/**
* Register the registration
* @param registration The registration to register
*/
void register(R registration);
/**
* Deregister the registration
* @param registration The registration to deregister
*/
void deregister(R registration);
/**
* Close the ServiceRegistry
*/
void close();
/**
* Set the status of the registration
* @param registration The registration
* @param status The status to set
*/
void setStatus(R registration, String status);
/**
* Get the status of the registration
* @param registration The registration
* @return The status
*/
<T> T getStatus(R registration);
}Usage Examples:
@Service
public class CustomRegistrationService {
@Autowired
private ServiceRegistry<Registration> serviceRegistry;
public void registerCustomService() {
Registration registration = createCustomRegistration();
serviceRegistry.register(registration);
}
public void updateServiceStatus(Registration registration, String status) {
serviceRegistry.setStatus(registration, status);
}
public void unregisterService(Registration registration) {
serviceRegistry.deregister(registration);
}
private Registration createCustomRegistration() {
return new DefaultServiceInstance(
"custom-instance-1",
"custom-service",
"localhost",
8080,
false
);
}
}Registration Interface
Marker interface for service registrations.
/**
* Marker interface extending ServiceInstance for registry operations
*/
public interface Registration extends ServiceInstance {
// Inherits all ServiceInstance methods
}Auto Service Registration
Interface for automatic service registration lifecycle management.
/**
* Interface for automatic service registration lifecycle
*/
public interface AutoServiceRegistration {
/**
* Start the auto registration process
*/
void start();
/**
* Stop the auto registration process
*/
void stop();
/**
* Check if auto registration is running
* @return true if running, false otherwise
*/
boolean isRunning();
}Abstract Auto Service Registration
Base implementation for auto service registration.
/**
* Base implementation for auto service registration
*/
public abstract class AbstractAutoServiceRegistration<R extends Registration>
implements AutoServiceRegistration, SmartLifecycle, Ordered {
/**
* Create auto service registration
* @param serviceRegistry The service registry
* @param autoServiceRegistrationProperties Configuration properties
* @param registration The registration
*/
protected AbstractAutoServiceRegistration(ServiceRegistry<R> serviceRegistry,
AutoServiceRegistrationProperties autoServiceRegistrationProperties,
R registration);
/**
* Get the management registration
* @return The management registration or null
*/
protected abstract R getManagementRegistration();
/**
* Register the service
*/
protected void register();
/**
* Register management service if enabled
*/
protected void registerManagement();
/**
* Deregister the service
*/
protected void deregister();
/**
* Deregister management service
*/
protected void deregisterManagement();
/**
* Check if auto registration is enabled
* @return true if enabled
*/
protected boolean isEnabled();
/**
* Get the service ID
* @return The service ID
*/
protected String getAppName();
}Auto Service Registration Properties
Configuration properties for auto service registration.
/**
* Configuration properties for auto service registration
*/
@ConfigurationProperties("spring.cloud.service-registry.auto-registration")
public class AutoServiceRegistrationProperties {
/**
* Whether auto registration is enabled
*/
private boolean enabled = true;
/**
* Whether to register management endpoints
*/
private boolean registerManagement = true;
/**
* Whether to fail fast if registration fails
*/
private boolean failFast = false;
// getters and setters
public boolean isEnabled() { return enabled; }
public void setEnabled(boolean enabled) { this.enabled = enabled; }
public boolean isRegisterManagement() { return registerManagement; }
public void setRegisterManagement(boolean registerManagement) {
this.registerManagement = registerManagement;
}
public boolean isFailFast() { return failFast; }
public void setFailFast(boolean failFast) { this.failFast = failFast; }
}Service Registry Endpoint
Actuator endpoint for service registry operations.
/**
* Actuator endpoint for service registry operations
*/
@Endpoint(id = "service-registry")
public class ServiceRegistryEndpoint {
/**
* Create service registry endpoint
* @param serviceRegistry The service registry
*/
public ServiceRegistryEndpoint(ServiceRegistry serviceRegistry);
/**
* Get the status of the registration
* @return The current status
*/
@ReadOperation
public ResponseEntity<?> getStatus();
/**
* Set the status of the registration
* @param status The status to set
* @return Response entity indicating success or failure
*/
@WriteOperation
public ResponseEntity<?> setStatus(String status);
}Usage Examples:
// Access the endpoint programmatically
@RestController
public class RegistrationController {
@Autowired
private ServiceRegistryEndpoint serviceRegistryEndpoint;
@GetMapping("/registration/status")
public ResponseEntity<?> getRegistrationStatus() {
return serviceRegistryEndpoint.getStatus();
}
@PostMapping("/registration/status")
public ResponseEntity<?> setRegistrationStatus(@RequestParam String status) {
return serviceRegistryEndpoint.setStatus(status);
}
}Configuration Properties
# Auto registration configuration
spring.cloud.service-registry.auto-registration.enabled=true
spring.cloud.service-registry.auto-registration.register-management=true
spring.cloud.service-registry.auto-registration.fail-fast=false
# Instance configuration (varies by registry implementation)
spring.cloud.service-registry.instance.hostname=localhost
spring.cloud.service-registry.instance.port=8080
spring.cloud.service-registry.instance.prefer-ip-address=false
spring.cloud.service-registry.instance.instance-id=${spring.application.name}:${server.port}Advanced Usage Examples
Custom Registration Implementation:
@Component
public class CustomRegistration implements Registration {
private final String instanceId;
private final String serviceId;
private final String host;
private final int port;
private final boolean secure;
private final Map<String, String> metadata;
public CustomRegistration(String instanceId, String serviceId,
String host, int port, boolean secure) {
this.instanceId = instanceId;
this.serviceId = serviceId;
this.host = host;
this.port = port;
this.secure = secure;
this.metadata = new HashMap<>();
// Add custom metadata
this.metadata.put("version", "1.0.0");
this.metadata.put("zone", "us-east-1");
}
@Override
public String getInstanceId() {
return instanceId;
}
@Override
public String getServiceId() {
return serviceId;
}
@Override
public String getHost() {
return host;
}
@Override
public int getPort() {
return port;
}
@Override
public boolean isSecure() {
return secure;
}
@Override
public URI getUri() {
String scheme = isSecure() ? "https" : "http";
return URI.create(scheme + "://" + host + ":" + port);
}
@Override
public Map<String, String> getMetadata() {
return metadata;
}
}Custom Auto Service Registration:
@Component
public class CustomAutoServiceRegistration extends AbstractAutoServiceRegistration<CustomRegistration> {
private final CustomRegistration registration;
private final CustomServiceRegistry serviceRegistry;
public CustomAutoServiceRegistration(CustomServiceRegistry serviceRegistry,
AutoServiceRegistrationProperties properties,
CustomRegistration registration) {
super(serviceRegistry, properties, registration);
this.serviceRegistry = serviceRegistry;
this.registration = registration;
}
@Override
protected CustomRegistration getRegistration() {
return registration;
}
@Override
protected CustomRegistration getManagementRegistration() {
// Return management registration if management endpoints should be registered
if (getAutoServiceRegistrationProperties().isRegisterManagement()) {
return new CustomRegistration(
registration.getInstanceId() + "-management",
registration.getServiceId() + "-management",
registration.getHost(),
getManagementPort(),
registration.isSecure()
);
}
return null;
}
@Override
protected void register() {
if (!isEnabled()) {
return;
}
super.register();
// Custom registration logic
updateHealthStatus("UP");
}
@Override
protected void deregister() {
super.deregister();
// Custom deregistration logic
updateHealthStatus("DOWN");
}
private void updateHealthStatus(String status) {
serviceRegistry.setStatus(registration, status);
}
private int getManagementPort() {
// Logic to determine management port
return 8081;
}
}Service Registry Event Handling:
@Component
public class ServiceRegistryEventHandler {
private static final Logger log = LoggerFactory.getLogger(ServiceRegistryEventHandler.class);
@EventListener
public void handleInstanceRegistered(InstanceRegisteredEvent<?> event) {
log.info("Service instance registered: {}", event.getConfig());
// Custom logic after registration
notifyServiceDiscovery(event);
}
@EventListener
public void handleInstancePreRegistered(InstancePreRegisteredEvent event) {
log.info("Service instance about to register: {}", event.getRegistration());
// Custom logic before registration
validateRegistration(event.getRegistration());
}
private void notifyServiceDiscovery(InstanceRegisteredEvent<?> event) {
// Custom notification logic
}
private void validateRegistration(Registration registration) {
// Custom validation logic
if (registration.getHost() == null || registration.getHost().isEmpty()) {
throw new IllegalArgumentException("Host cannot be null or empty");
}
}
}Health Check Integration:
@Component
public class ServiceRegistryHealthIndicator implements HealthIndicator {
private final ServiceRegistry<Registration> serviceRegistry;
private final Registration registration;
public ServiceRegistryHealthIndicator(ServiceRegistry<Registration> serviceRegistry,
Registration registration) {
this.serviceRegistry = serviceRegistry;
this.registration = registration;
}
@Override
public Health health() {
try {
Object status = serviceRegistry.getStatus(registration);
return Health.up()
.withDetail("status", status)
.withDetail("serviceId", registration.getServiceId())
.withDetail("instanceId", registration.getInstanceId())
.build();
} catch (Exception e) {
return Health.down()
.withDetail("error", e.getMessage())
.build();
}
}
}Install with Tessl CLI
npx tessl i tessl/maven-org-springframework-cloud--spring-cloud-commons