From 8dc570b6b558de48f3b9abbecc9d822d89ecb239 Mon Sep 17 00:00:00 2001 From: elandau Date: Mon, 23 Nov 2015 22:01:16 -0800 Subject: [PATCH] Fix javadoc. Add binding to command line arguments as @Arguments String[] --- .../java/com/netflix/karyon/AutoBinder.java | 4 +- .../main/java/com/netflix/karyon/Karyon.java | 78 +++++++++++++------ .../java/com/netflix/karyon/KaryonBinder.java | 5 +- .../com/netflix/karyon/PropertySource.java | 22 +++--- .../netflix/karyon/annotations/Arguments.java | 20 +++++ .../karyon/conditional/ConditionalBinder.java | 2 +- .../health/AbstractHealthIndicator.java | 23 ++---- .../karyon/health/HealthIndicator.java | 3 +- .../health/HealthIndicatorRegistry.java | 3 +- .../karyon/health/HealthIndicatorStatus.java | 4 +- 10 files changed, 103 insertions(+), 61 deletions(-) create mode 100644 karyon3-core/src/main/java/com/netflix/karyon/annotations/Arguments.java diff --git a/karyon3-core/src/main/java/com/netflix/karyon/AutoBinder.java b/karyon3-core/src/main/java/com/netflix/karyon/AutoBinder.java index 9dba3239..fd7ac0b0 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/AutoBinder.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/AutoBinder.java @@ -61,8 +61,8 @@ public interface AutoBinder { /** * Create a bindings for the specified type literal. * - * @param binder - * @param key + * @param binder Binder on which bindings may be created + * @param key Key for which no binding was found * * @return True if bindings was created or false if not. */ diff --git a/karyon3-core/src/main/java/com/netflix/karyon/Karyon.java b/karyon3-core/src/main/java/com/netflix/karyon/Karyon.java index f787828c..0572fe78 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/Karyon.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/Karyon.java @@ -34,6 +34,7 @@ import com.netflix.governator.ElementsEx; import com.netflix.governator.LifecycleInjector; import com.netflix.governator.LifecycleManager; +import com.netflix.karyon.annotations.Arguments; import com.netflix.karyon.annotations.Profiles; import com.netflix.karyon.conditional.ConditionalSupportModule; import com.netflix.karyon.spi.ModuleListTransformer; @@ -123,6 +124,7 @@ protected Karyon(String applicationName) { * * @param modules Guice modules to add. These modules my also implement KaryonModule to further * extend Karyon. + * @return this */ public Karyon addModules(Module ... modules) { if (modules != null) { @@ -136,6 +138,7 @@ public Karyon addModules(Module ... modules) { * * @param modules Guice modules to add. These modules my also implement KaryonModule to further * extend Karyon. + * @return this */ public Karyon addModules(List modules) { if (modules != null) { @@ -149,7 +152,9 @@ public Karyon addModules(List modules) { * conditionally loaded. This is useful for testing or when an application * absolutely needs to override a binding to fix a binding problem in the * code modules - * @param modules + * @param modules Modules that will be applied as overrides to modules add + * or installed via {@link Karyon#addModules(Module...)} + * @return this */ public Karyon addOverrideModules(Module ... modules) { if (modules != null) { @@ -163,7 +168,9 @@ public Karyon addOverrideModules(Module ... modules) { * conditionally loaded. This is useful for testing or when an application * absolutely needs to override a binding to fix a binding problem in the * code modules - * @param modules + * @param modules Modules that will be applied as overrides to modules add + * or installed via {@link Karyon#addModules(Module...)} + * @return this */ public Karyon addOverrideModules(List modules) { if (modules != null) { @@ -175,7 +182,8 @@ public Karyon addOverrideModules(List modules) { /** * Specify the Guice stage in which the application is running. By default Karyon * runs in Stage.DEVELOPMENT to achieve default lazy singleton behavior. - * @param stage + * @param stage Guice stage + * @return this */ public Karyon inStage(Stage stage) { this.stage = stage; @@ -187,6 +195,7 @@ public Karyon inStage(Stage stage) { * @param provider * * @deprecated Module auto loading no longer supported. Install modules directly and use {@literal @}ProvidesConditionally + * @return this */ @Deprecated public Karyon addAutoModuleListProvider(ModuleListProvider provider) { @@ -194,9 +203,11 @@ public Karyon addAutoModuleListProvider(ModuleListProvider provider) { } /** - * Add a runtime profile + * Add a runtime profile. Profiles are processed by the conditional binding {@literal @}ConditionalOnProfile and + * are injectable as {@literal @}Profiles Set{@literal <}String{@literal >}. * - * @param profile + * @param profile A profile + * @return this */ public Karyon addProfile(String profile) { if (profile != null) { @@ -206,11 +217,14 @@ public Karyon addProfile(String profile) { } /** - * Add a runtime profiles + * Add a runtime profiles. Profiles are processed by the conditional binding {@literal @}ConditionalOnProfile and + * are injectable as {@literal @}Profiles Set{@literal <}String{@literal >}. * - * @param profiles + * @param profiles Set of profiles + * @return this */ - public Karyon addProfiles(String... profiles) { + public Karyon addProfiles(String profile, String... profiles) { + this.profiles.add(profile); if (profiles != null) { this.profiles.addAll(Arrays.asList(profiles)); } @@ -218,9 +232,11 @@ public Karyon addProfiles(String... profiles) { } /** - * Add a runtime profiles + * Add a runtime profiles. Profiles are processed by the conditional binding {@literal @}ConditionalOnProfile and + * are injectable as {@literal @}Profiles Set{@literal <}String{@literal >}. * - * @param profiles + * @param profiles Set of profiles + * @return this */ public Karyon addProfiles(Collection profiles) { if (profiles != null) { @@ -231,7 +247,8 @@ public Karyon addProfiles(Collection profiles) { /** * Enable the specified feature - * @param feature + * @param feature Boolean feature to enable + * @return this */ public Karyon enableFeature(KaryonFeature feature) { return setFeature(feature, true); @@ -239,7 +256,8 @@ public Karyon enableFeature(KaryonFeature feature) { /** * Enable or disable the specified feature - * @param feature + * @param feature Boolean feature to disable + * @return this */ public Karyon enableFeature(KaryonFeature feature, boolean enabled) { return setFeature(feature, enabled); @@ -247,15 +265,17 @@ public Karyon enableFeature(KaryonFeature feature, boolean enabled) { /** * Disable the specified feature - * @param feature + * @param feature Boolean feature to enable/disable + * @return this */ public Karyon disableFeature(KaryonFeature feature) { return setFeature(feature, false); } /** - * Disable the specified feature - * @param feature + * Set a feature + * @param feature Feature to set + * @return this */ public Karyon setFeature(KaryonFeature feature, T value) { this.features.put(feature, value); @@ -267,7 +287,8 @@ public Karyon setFeature(KaryonFeature feature, T value) { * prior to creating the injectors. Multiple transformers may be added with each * transforming the result of the previous one. * - * @param transformer + * @param transformer A transformer + * @return this */ public Karyon addModuleListTransformer(ModuleListTransformer transformer) { if (transformer != null) { @@ -282,6 +303,7 @@ public Karyon addModuleListTransformer(ModuleListTransformer transformer) { * @param matcher Matcher to restrict the types for which the AutoBinder can be used. See {@link TypeLiteralMatchers} for * specifying common matchers. * @param autoBinder The auto binder + * @return this */ public > Karyon addAutoBinder(Matcher matcher, AutoBinder autoBinder) { this.autoBinders.add(new MatchingAutoBinder(matcher, autoBinder)); @@ -295,15 +317,19 @@ public Karyon apply(Module ... modules) { } /** - * + * Create the injector and call any LifecycleListeners + * @return the LifecycleInjector for this run */ public LifecycleInjector start() { return start(null); } /** + * Create the injector and call any LifecycleListeners + * @param args - Runtime parameter (from main) injectable as {@literal @}Arguments String[] + * @return the LifecycleInjector for this run */ - public LifecycleInjector start(String[] args) { + public LifecycleInjector start(final String[] args) { for (Module module : modules) { if (module instanceof KaryonModule) { ((KaryonModule)module).configure(new KaryonBinder() { @@ -345,6 +371,13 @@ protected void configure() { for (String profile : Karyon.this.profiles) { profiles.addBinding().toInstance(profile); } + + if (args != null) { + bind(String[].class).annotatedWith(Arguments.class).toInstance(args); + } + else { + bind(String[].class).annotatedWith(Arguments.class).toInstance(new String[]{}); + } } }) .build()) @@ -394,15 +427,14 @@ protected void configure() { } } + /** + * Construct a new Karyon instance + * @return Karyon instance + */ public static Karyon newBuilder() { return new Karyon(); } - /** - * Starting point for creating a Karyon application. - * - * @param applicationName - */ @Deprecated public static Karyon forApplication(String applicationName) { return new Karyon(applicationName); diff --git a/karyon3-core/src/main/java/com/netflix/karyon/KaryonBinder.java b/karyon3-core/src/main/java/com/netflix/karyon/KaryonBinder.java index d9091182..46bdf831 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/KaryonBinder.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/KaryonBinder.java @@ -10,8 +10,9 @@ public interface KaryonBinder { /** * Add an AutoBinder to be used when no binding is provided for a type matched by the matcher * - * @param matcher - * @param autoBinder + * @param matcher Logic for matching an unbound TypeLiteral. See {@link TypeLiteralMatchers} for + * pre-defined matchers. + * @param autoBinder AutoBinder that will created the bindings for any type matched by the matcher */ > void bindAutoBinder(Matcher matcher, AutoBinder autoBinder); } diff --git a/karyon3-core/src/main/java/com/netflix/karyon/PropertySource.java b/karyon3-core/src/main/java/com/netflix/karyon/PropertySource.java index 3bf69c65..3d48b8e2 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/PropertySource.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/PropertySource.java @@ -17,26 +17,26 @@ public interface PropertySource { /** * Get the value of a property or null if not found * - * @param key - * @return + * @param key Name of property to fetch + * @return Value or null if not found */ public String get(String key); /** * Get the value of a property or default if not found * - * @param key + * @param key Name of property to fetch * @param defaultValue - * @return + * @return Value or defaultValue if not found */ public String get(String key, String defaultValue); /** * Get a property value of a specific type * - * @param key - * @param type - * @return + * @param key Name of property to fetch + * @param type Type of value requested + * @return Value of the request type or null if not found */ public T get(String key, Class type); @@ -44,10 +44,10 @@ public interface PropertySource { * Get a property value of a specific type while returning a * default value if the property is not set. * - * @param key - * @param type - * @param defaultValue - * @return + * @param key Name of property to fetch + * @param type Type of value requested + * @param defaultValue Default value to return if key not found + * @return Value or defaultValue if not found */ public T get(String key, Class type, T defaultValue); } diff --git a/karyon3-core/src/main/java/com/netflix/karyon/annotations/Arguments.java b/karyon3-core/src/main/java/com/netflix/karyon/annotations/Arguments.java new file mode 100644 index 00000000..c6b29540 --- /dev/null +++ b/karyon3-core/src/main/java/com/netflix/karyon/annotations/Arguments.java @@ -0,0 +1,20 @@ +package com.netflix.karyon.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import javax.inject.Qualifier; + +/** + * Qualifier associated with String[] arguments passed to Karyon.start(args) + */ +@Target({ ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD }) +@Retention(RetentionPolicy.RUNTIME) +@Documented +@Qualifier +public @interface Arguments { + +} diff --git a/karyon3-core/src/main/java/com/netflix/karyon/conditional/ConditionalBinder.java b/karyon3-core/src/main/java/com/netflix/karyon/conditional/ConditionalBinder.java index 1832e324..84d8b609 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/conditional/ConditionalBinder.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/conditional/ConditionalBinder.java @@ -25,7 +25,7 @@ public class ConditionalBinder { /** * Used to generate unique bindings for conditional T keys that will not conflict * with annotated T - * @return + * @return Unique annotation */ public static IdQualifier newIdQualifier() { final int id = counter.incrementAndGet(); diff --git a/karyon3-core/src/main/java/com/netflix/karyon/health/AbstractHealthIndicator.java b/karyon3-core/src/main/java/com/netflix/karyon/health/AbstractHealthIndicator.java index f72819fc..2d367726 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/health/AbstractHealthIndicator.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/health/AbstractHealthIndicator.java @@ -7,10 +7,9 @@ public abstract class AbstractHealthIndicator implements HealthIndicator { private final String name; /** - * Creates an AbstractHealthIndicator with the specified name - * - * @param name name Name of this Health Indicator + * Creates an AbstractHealthIndicator with the specified name * + * @param name Name of this Health Indicator */ public AbstractHealthIndicator(String name) { this.name = name; @@ -18,7 +17,6 @@ public AbstractHealthIndicator(String name) { /** * Creates an AbstractHealthIndicator with a default name - * */ public AbstractHealthIndicator() { this.name = getClass().getSimpleName(); @@ -30,20 +28,16 @@ public String getName() { } /** - * * Create a healthy status * * @return a healthy status */ - protected final HealthIndicatorStatus healthy() { return HealthIndicatorStatuses.create(getName(), true, Collections. emptyMap(), null); } /** - * * Create a healthy status - * * @param attr Map of the attributes describing status * @return a healthy status */ @@ -52,9 +46,7 @@ protected final HealthIndicatorStatus healthy(Map attr) { } /** - * * Create an unhealthy status - * * @return a unhealthy status */ protected final HealthIndicatorStatus unhealthy() { @@ -62,9 +54,8 @@ protected final HealthIndicatorStatus unhealthy() { } /** - * * Create an unhealthy status - * + * @param attr Map of the attributes describing status * @return a unhealthy status */ protected final HealthIndicatorStatus unhealthy(Map attr) { @@ -72,9 +63,8 @@ protected final HealthIndicatorStatus unhealthy(Map attr) { } /** - * * Create an unhealthy status - * + * @param t Error that caused the unhealthy status * @return a unhealthy status */ protected final HealthIndicatorStatus unhealthy(Throwable t) { @@ -82,13 +72,12 @@ protected final HealthIndicatorStatus unhealthy(Throwable t) { } /** - * * Create an unhealthy status - * + * @param attr Map of the attributes describing status + * @param t Error that caused the unhealthy status * @return a unhealthy status */ protected final HealthIndicatorStatus unhealthy(Map attr, Throwable t) { return HealthIndicatorStatuses.create(getName(), false, attr, t); } - } diff --git a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicator.java b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicator.java index 552f4b9b..b154f7c3 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicator.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicator.java @@ -43,11 +43,12 @@ public interface HealthIndicator { /** * Perform the health check asynchronously. + * @return Future of health status result */ CompletableFuture check(); /** - * Return the name of the health indicator. Note that health indicators with duplicate names are allowed. + * @return Return the name of the health indicator. Note that health indicators with duplicate names are allowed. */ String getName(); } diff --git a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorRegistry.java b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorRegistry.java index b18b73e2..3d66b2fa 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorRegistry.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorRegistry.java @@ -26,8 +26,7 @@ @ImplementedBy(AllHealthIndicatorRegistry.class) public interface HealthIndicatorRegistry { /** - * Return a list of all active health checks - * @return + * @return Return a list of all active health checks */ List getHealthIndicators(); diff --git a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorStatus.java b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorStatus.java index aa2251af..6a148a99 100644 --- a/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorStatus.java +++ b/karyon3-core/src/main/java/com/netflix/karyon/health/HealthIndicatorStatus.java @@ -10,7 +10,7 @@ */ public interface HealthIndicatorStatus { /** - * Map of named attributes that provide additional information regarding the health. + * @return Map of named attributes that provide additional information regarding the health. * For example, a CPU health check may return Unhealthy with attribute "usage"="90%" */ public Map getAttributes(); @@ -21,7 +21,7 @@ public interface HealthIndicatorStatus { public boolean isHealthy(); /** - * Exception providing additional information regarding the failure state. This could be + * @return Exception providing additional information regarding the failure state. This could be * the last known exception. */ public String getError();