From 9d29064534d700c16d1fa5026a2a962b1f331364 Mon Sep 17 00:00:00 2001 From: Spencer Gibb Date: Fri, 13 Feb 2015 13:16:15 -0700 Subject: [PATCH] adds some javadocs --- .../cloud/client/DefaultServiceInstance.java | 5 +++ .../cloud/client/ServiceInstance.java | 13 +++++++ .../circuitbreaker/EnableCircuitBreaker.java | 2 ++ .../EnableCircuitBreakerImportSelector.java | 1 + .../discovery/AbstractDiscoveryLifecycle.java | 34 +++++++++++++++++++ .../client/discovery/DiscoveryClient.java | 10 +++--- .../discovery/EnableDiscoveryClient.java | 1 + .../discovery/ManagementServerPortUtils.java | 1 + .../discovery/event/HeartbeatEvent.java | 2 ++ .../DiscoveryCompositeHealthIndicator.java | 2 ++ .../health/DiscoveryHealthIndicator.java | 1 + .../discovery/noop/NoopDiscoveryClient.java | 6 +--- .../loadbalancer/LoadBalancerClient.java | 10 ++++++ .../loadbalancer/LoadBalancerRequest.java | 2 ++ 14 files changed, 81 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/springframework/cloud/client/DefaultServiceInstance.java b/src/main/java/org/springframework/cloud/client/DefaultServiceInstance.java index 24be1744..b9038ac8 100644 --- a/src/main/java/org/springframework/cloud/client/DefaultServiceInstance.java +++ b/src/main/java/org/springframework/cloud/client/DefaultServiceInstance.java @@ -41,6 +41,11 @@ public class DefaultServiceInstance implements ServiceInstance { return getUri(this); } + /** + * Create a uri from the given ServiceInstance's host:port + * @param instance + * @return URI of the form (secure)?https:http + "host:port" + */ public static URI getUri(ServiceInstance instance) { String scheme = (instance.isSecure()) ? "https" : "http"; String uri = String.format("%s://%s:%s", scheme, instance.getHost(), diff --git a/src/main/java/org/springframework/cloud/client/ServiceInstance.java b/src/main/java/org/springframework/cloud/client/ServiceInstance.java index 5c8e3c3a..7cd52f72 100644 --- a/src/main/java/org/springframework/cloud/client/ServiceInstance.java +++ b/src/main/java/org/springframework/cloud/client/ServiceInstance.java @@ -19,16 +19,29 @@ package org.springframework.cloud.client; import java.net.URI; /** + * Represents an instance of a Service in a Discovery System * @author Spencer Gibb */ public interface ServiceInstance { + /** + * @return the service id as register by the DiscoveryClient + */ public String getServiceId(); + /** + * @return the hostname of the registered ServiceInstance + */ public String getHost(); + /** + * @return the port of the registered ServiceInstance + */ public int getPort(); + /** + * @return ifthe port of the registered ServiceInstance is https or not + */ public boolean isSecure(); public URI getUri(); diff --git a/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreaker.java b/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreaker.java index d180b91f..29ec2e36 100644 --- a/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreaker.java +++ b/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreaker.java @@ -26,6 +26,8 @@ import java.lang.annotation.Target; import org.springframework.context.annotation.Import; /** + * Annotation to enable a CircuitBreaker implementation. + * http://martinfowler.com/bliki/CircuitBreaker.html * @author Spencer Gibb */ @Target(ElementType.TYPE) diff --git a/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreakerImportSelector.java b/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreakerImportSelector.java index 698fb51c..3bd9cf7a 100644 --- a/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreakerImportSelector.java +++ b/src/main/java/org/springframework/cloud/client/circuitbreaker/EnableCircuitBreakerImportSelector.java @@ -22,6 +22,7 @@ import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; /** + * Import a single circuit breaker implementation Configuration * @author Spencer Gibb */ @Order(Ordered.LOWEST_PRECEDENCE - 100) diff --git a/src/main/java/org/springframework/cloud/client/discovery/AbstractDiscoveryLifecycle.java b/src/main/java/org/springframework/cloud/client/discovery/AbstractDiscoveryLifecycle.java index afadd2a9..c81058a0 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/AbstractDiscoveryLifecycle.java +++ b/src/main/java/org/springframework/cloud/client/discovery/AbstractDiscoveryLifecycle.java @@ -27,6 +27,7 @@ import org.springframework.context.ApplicationContextAware; import org.springframework.core.env.Environment; /** + * Lifecycle methods that may be useful and common to various DiscoveryClient implementations. * @author Spencer Gibb */ public abstract class AbstractDiscoveryLifecycle implements DiscoveryLifecycle, @@ -83,36 +84,66 @@ public abstract class AbstractDiscoveryLifecycle implements DiscoveryLifecycle, this.running = true; } + /** + * @return if the management service should be registered with the DiscoveryService + */ protected boolean shouldRegisterManagement() { return getManagementServerProperties() != null && getManagementPort() != null && ManagementServerPortUtils.isDifferent(this.context); } + /** + * @return the object used to configure the DiscoveryClient + */ protected abstract Object getConfiguration(); + /** + * Register the local service with the DiscoveryClient + */ protected abstract void register(); + /** + * Register the local management service with the DiscoveryClient + */ protected void registerManagement() { } + /** + * De-register the local service with the DiscoveryClient + */ protected abstract void deregister(); + /** + * De-register the local management service with the DiscoveryClient + */ protected void deregisterManagement() { } + /** + * @return if the DiscoveryClient is enabled + */ protected abstract boolean isEnabled(); + /** + * @return the serviceId of the Management Service + */ protected String getManagementServiceId() { return this.context.getId() + ":management"; // TODO: configurable management suffix } + /** + * @return the service name of the Management Service + */ protected String getManagementServiceName() { return getAppName() + ":management"; // TODO: configurable management suffix } + /** + * @return the management server port + */ protected Integer getManagementPort() { return getManagementServerProperties().getPort(); } @@ -125,6 +156,9 @@ public abstract class AbstractDiscoveryLifecycle implements DiscoveryLifecycle, } } + /** + * @return the app name, currently the spring.application.name property + */ protected String getAppName() { return this.environment.getProperty("spring.application.name"); } diff --git a/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java b/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java index a5ea9756..0ad2bbfd 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java +++ b/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java @@ -21,12 +21,16 @@ import java.util.List; import org.springframework.cloud.client.ServiceInstance; /** + * DiscoveryClient represents operations commonly available to Discovery service + * such as Netflix Eureka or consul.io * @author Spencer Gibb */ public interface DiscoveryClient { - // TODO: merge with LoadBalancerClient? - + /** + * A human readable description of the implementation, used in HealthIndicator + * @return + */ public String description(); /** @@ -41,8 +45,6 @@ public interface DiscoveryClient { */ public List getInstances(String serviceId); - public List getAllInstances(); - /** * @return all known service id's */ diff --git a/src/main/java/org/springframework/cloud/client/discovery/EnableDiscoveryClient.java b/src/main/java/org/springframework/cloud/client/discovery/EnableDiscoveryClient.java index 2c503a2a..60b76d45 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/EnableDiscoveryClient.java +++ b/src/main/java/org/springframework/cloud/client/discovery/EnableDiscoveryClient.java @@ -26,6 +26,7 @@ import java.lang.annotation.Target; import org.springframework.context.annotation.Import; /** + * Annotation to enable a DiscoveryClient implementation. * @author Spencer Gibb */ @Target(ElementType.TYPE) diff --git a/src/main/java/org/springframework/cloud/client/discovery/ManagementServerPortUtils.java b/src/main/java/org/springframework/cloud/client/discovery/ManagementServerPortUtils.java index 9df63084..f9625597 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/ManagementServerPortUtils.java +++ b/src/main/java/org/springframework/cloud/client/discovery/ManagementServerPortUtils.java @@ -23,6 +23,7 @@ import org.springframework.boot.autoconfigure.web.ServerProperties; import org.springframework.web.context.WebApplicationContext; /** + * * @author Spencer Gibb */ public class ManagementServerPortUtils { diff --git a/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java b/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java index e6cc42e7..3e6e0c7a 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java +++ b/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java @@ -19,6 +19,8 @@ package org.springframework.cloud.client.discovery.event; import org.springframework.context.ApplicationEvent; /** + * Event DiscoveryClient implementation can broadcast if they support + * heartbeat's from the discovery server * @author Spencer Gibb */ @SuppressWarnings("serial") diff --git a/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryCompositeHealthIndicator.java b/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryCompositeHealthIndicator.java index a42320cc..f1dce429 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryCompositeHealthIndicator.java +++ b/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryCompositeHealthIndicator.java @@ -25,6 +25,8 @@ import org.springframework.boot.actuate.health.HealthAggregator; import org.springframework.boot.actuate.health.HealthIndicator; /** + * Gathers all DiscoveryHealthIndicator's from a DiscoveryClient implementation + * and aggregates the statuses. * @author Spencer Gibb */ public class DiscoveryCompositeHealthIndicator extends CompositeHealthIndicator { diff --git a/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryHealthIndicator.java b/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryHealthIndicator.java index 219a8556..43fca7d2 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryHealthIndicator.java +++ b/src/main/java/org/springframework/cloud/client/discovery/health/DiscoveryHealthIndicator.java @@ -19,6 +19,7 @@ package org.springframework.cloud.client.discovery.health; import org.springframework.boot.actuate.health.Health; /** + * A health indicator interface specific for a DiscoveryClient implementation * @author Spencer Gibb */ public interface DiscoveryHealthIndicator { diff --git a/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClient.java b/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClient.java index 4047ae91..6c6a9bc0 100644 --- a/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClient.java +++ b/src/main/java/org/springframework/cloud/client/discovery/noop/NoopDiscoveryClient.java @@ -23,6 +23,7 @@ import org.springframework.cloud.client.ServiceInstance; import org.springframework.cloud.client.discovery.DiscoveryClient; /** + * DiscoveryClient used when no implementations are found on the classpath * @author Dave Syer */ public class NoopDiscoveryClient implements DiscoveryClient { @@ -48,11 +49,6 @@ public class NoopDiscoveryClient implements DiscoveryClient { return Collections.emptyList(); } - @Override - public List getAllInstances() { - return Collections.emptyList(); - } - @Override public List getServices() { return Collections.emptyList(); diff --git a/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerClient.java b/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerClient.java index cf46fe6b..96e849bb 100644 --- a/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerClient.java +++ b/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerClient.java @@ -21,6 +21,7 @@ import java.net.URI; import org.springframework.cloud.client.ServiceInstance; /** + * Represents a client side load balancer * @author Spencer Gibb */ public interface LoadBalancerClient { @@ -42,6 +43,15 @@ public interface LoadBalancerClient { */ public T execute(String serviceId, LoadBalancerRequest request); + /** + * Create a proper URI with a real host and port for systems to utilize. + * Some systems use a URI with the logical serivce name as the host, + * such as http://myservice/path/to/service. This will replace the + * service name with the host:port from the ServiceInstance. + * @param instance + * @param original a URI with the host as a logical service name + * @return a reconstructed URI + */ public URI reconstructURI(ServiceInstance instance, URI original); } diff --git a/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerRequest.java b/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerRequest.java index 4d0b4c31..f085a450 100644 --- a/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerRequest.java +++ b/src/main/java/org/springframework/cloud/client/loadbalancer/LoadBalancerRequest.java @@ -19,6 +19,8 @@ package org.springframework.cloud.client.loadbalancer; import org.springframework.cloud.client.ServiceInstance; /** + * Simple interface used by LoadBalancerClient to apply metrics or pre and post + * actions around load balancer requests. * @author Spencer Gibb */ public interface LoadBalancerRequest {