From 61199a151c87f2a87c3da2152461260ed6ce97db Mon Sep 17 00:00:00 2001 From: Spencer Gibb Date: Mon, 3 Apr 2017 19:14:45 -0600 Subject: [PATCH] Adds ServiceRegistry documentation. fixes gh-170 fixes gh-196 --- .../main/asciidoc/spring-cloud-commons.adoc | 27 ++++++++++++++ .../client/discovery/DiscoveryClient.java | 2 +- .../client/serviceregistry/Registration.java | 3 ++ .../serviceregistry/ServiceRegistry.java | 37 +++++++++++++++++-- 4 files changed, 64 insertions(+), 5 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-commons.adoc b/docs/src/main/asciidoc/spring-cloud-commons.adoc index 0b151145..38fdab00 100644 --- a/docs/src/main/asciidoc/spring-cloud-commons.adoc +++ b/docs/src/main/asciidoc/spring-cloud-commons.adoc @@ -321,6 +321,33 @@ By default, implementations of `DiscoveryClient` will auto-register the local Sp Commons now provides a `ServiceRegistry` interface which provides methods like `register(Registration)` and `deregister(Registration)` which allow you to provide custom registered services. `Registration` is a marker interface. +[source,java,indent=0] +---- +@Configuration +@EnableDiscoveryClient(autoRegister=false) +public class MyConfiguration { + private ServiceRegistry registry; + + public MyConfiguration(ServiceRegistry registry) { + this.registry = registry; + } + + // called via some external process, such as an event or a custom actuator endpoint + public void register() { + Registration registration = constructRegistration(); + this.registry.register(registration); + } +} +---- + +Each `ServiceRegistry` implementation has its own `Registry` implementation. + + +==== ServiceRegistry Auto-Registration + +By default, the `ServiceRegistry` implementation will auto-register the running service. To disable that behavior, there are two methods. You can set `@EnableDiscoveryClient(autoRegister=false)` to permanently disable auto-registration. You can also set `spring.cloud.service-registry.auto-registration.enabled=false` to disable the behavior via configuration. + + ==== Service Registry Actuator Endpoint A `/service-registry` actuator endpoint is provided by Commons. This endpoint relys on a `Registration` bean in the Spring Application Context. Calling `/service-registry/instance-status` via a GET will return the status of the `Registration`. A POST to the same endpoint with a `String` body will change the status of the current `Registration` to the new value. Please see the documentation of the `ServiceRegistry` implementation you are using for the allowed values for updating the status and the values retured for the status. diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java index 41f429e4..c2d553d9 100644 --- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java +++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java @@ -21,7 +21,7 @@ import java.util.List; import org.springframework.cloud.client.ServiceInstance; /** - * DiscoveryClient represents operations commonly available to Discovery service such as + * DiscoveryClient represents read operations commonly available to Discovery service such as * Netflix Eureka or consul.io * @author Spencer Gibb */ diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/Registration.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/Registration.java index f9e31df1..9f3e7022 100644 --- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/Registration.java +++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/Registration.java @@ -1,7 +1,10 @@ package org.springframework.cloud.client.serviceregistry; /** + * A marker interface used by a {@link ServiceRegistry}. + * * @author Spencer Gibb + * @since 1.2.0 */ public interface Registration { diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/ServiceRegistry.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/ServiceRegistry.java index eb3d73ee..bcd695e8 100644 --- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/ServiceRegistry.java +++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/ServiceRegistry.java @@ -1,19 +1,48 @@ package org.springframework.cloud.client.serviceregistry; /** - * TODO: write javadoc + * Contract to register and deregister instances with a Service Registry. + * * @author Spencer Gibb + * @since 1.2.0 */ public interface ServiceRegistry { + + /** + * Register the registration. Registrations typically have information about + * instances such as: hostname and port. + * @param registration the registraion + */ void register(R registration); + /** + * Deregister the registration. + * @param registration + */ void deregister(R registration); + /** + * Close the ServiceRegistry. This a lifecycle method. + */ void close(); - // TODO: return value for success? + /** + * Sets the status of the registration. The status values are determined + * by the individual implementations. + * + * @see org.springframework.cloud.client.serviceregistry.endpoint.ServiceRegistryEndpoint + * @param registration the registration to update + * @param status the status to set + */ void setStatus(R registration, String status); - // TODO: concrete return value? Interface? - Object getStatus(R registration); + /** + * Gets the status of a particular registration. + * + * @see org.springframework.cloud.client.serviceregistry.endpoint.ServiceRegistryEndpoint + * @param registration the registration to query + * @param the type of the status + * @return the status of the registration + */ + T getStatus(R registration); }