Merge pull request #16015 from aloubyansky/registry-config-javadoc

Registry config javadoc

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/ExtensionCatalogResolver.java

@@ -148,6 +148,10 @@ private RegistryClientFactory getClientFactory(RegistryConfig config) {
                 ClassLoader providerCl = new URLClassLoader(new URL[] { providerJar.toURI().toURL() }, originalCl);
                 final Iterator<RegistryClientFactoryProvider> i = ServiceLoader
                         .load(RegistryClientFactoryProvider.class, providerCl).iterator();
+                if (!i.hasNext()) {
+                    throw new Exception("Failed to locate an implementation of " + RegistryClientFactoryProvider.class.getName()
+                            + " service provider");
+                }
                 final RegistryClientFactoryProvider provider = i.next();
                 if (i.hasNext()) {
                     final StringBuilder buf = new StringBuilder();

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistriesConfig.java

@@ -2,9 +2,23 @@
 
 import java.util.List;
 
+/**
+ * Registry client configuration. Consists of a list of registry configurations that will be
+ * providing platform and extension information to the client.
+ */
 public interface RegistriesConfig {
 
+    /**
+     * Enables or disables registry client debug mode.
+     *
+     * @return true if the debug mode should be enabled, otherwise - false
+     */
     boolean isDebug();
 
+    /**
+     * A list of registries that should queried when generating catalogs of platforms and extensions.
+     *
+     * @return list of registries that should queried when generating catalogs of platforms and extensions
+     */
     List<RegistryConfig> getRegistries();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistriesConfigLocator.java

@@ -19,11 +19,32 @@
 import java.nio.file.Paths;
 import java.util.Objects;
 
+/**
+ * A helper class with utility methods to locate the registry client configuration file
+ * in the default locations (e.g. user home <code>.quarkus</code> dir, or the project dir) or in
+ * at the location specified by the caller.
+ * Also includes methods to parse the registry client configuration file.
+ */
 public class RegistriesConfigLocator {
 
     public static final String CONFIG_RELATIVE_PATH = ".quarkus/config.yaml";
     public static final String CONFIG_FILE_PATH_PROPERTY = "qer.config";
 
+    /**
+     * Locate the registry client configuration file and deserialize it.
+     * The method will be looking for the file in the following locations in this order:
+     * <ol>
+     * <li>if <code>qer.config</code> system property is set, its value will be used as the location of the configuration
+     * file</li>
+     * <li>current user directory (which usually would be the project dir)</li>
+     * <li><code>.quarkus/config.yaml</code> in the user home directory
+     * </ol>
+     *
+     * Given that the presence of the configuration file is optional, if the configuration file couldn't be located,
+     * an empty configuration would be returned to the caller.
+     *
+     * @return registry client configuration, never null
+     */
     public static RegistriesConfig resolveConfig() {
         final Path configYaml = locateConfigYaml();
         if (configYaml == null) {
@@ -32,6 +53,12 @@ public static RegistriesConfig resolveConfig() {
         return load(configYaml);
     }
 
+    /**
+     * Deserializes a given configuration file.
+     *
+     * @param configYaml configuration file
+     * @return deserialized registry client configuration
+     */
     public static RegistriesConfig load(Path configYaml) {
         try {
             return completeRequiredConfig(RegistriesConfigMapperHelper.deserialize(configYaml, JsonRegistriesConfig.class));
@@ -40,6 +67,12 @@ public static RegistriesConfig load(Path configYaml) {
         }
     }
 
+    /**
+     * Deserializes registry client configuration from an input stream.
+     *
+     * @param configYaml input stream
+     * @return deserialized registry client configuration
+     */
     public static RegistriesConfig load(InputStream configYaml) {
         try {
             return completeRequiredConfig(RegistriesConfigMapperHelper.deserializeYaml(configYaml, JsonRegistriesConfig.class));
@@ -172,6 +205,12 @@ private static boolean hasRequiredConfig(RegistryMavenConfig maven) {
         return true;
     }
 
+    /**
+     * Returns the default registry client configuration which should be used in case
+     * no configuration file was found in the user's environment.
+     *
+     * @return default registry client configuration
+     */
     public static RegistryConfig getDefaultRegistry() {
         final JsonRegistryConfig qer = new JsonRegistryConfig();
         qer.setId(Constants.DEFAULT_REGISTRY_ID);

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryArtifactConfig.java

@@ -2,9 +2,22 @@
 
 import io.quarkus.maven.ArtifactCoords;
 
+/**
+ * Base registry catalog artifact configuration
+ */
 public interface RegistryArtifactConfig {
 
+    /**
+     * Whether this catalog artifact is not supported by the registry or should simply be disabled on the client side.
+     *
+     * @return true, if the catalog represented by this artifact should be excluded from processing
+     */
     boolean isDisabled();
 
+    /**
+     * Catalog artifact coordinates in the registry.
+     *
+     * @return catalog artifact coordinates in the registry
+     */
     ArtifactCoords getArtifact();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryConfig.java

@@ -2,23 +2,80 @@
 
 import java.util.Map;
 
+/**
+ * Client side registry configuration containing information how to
+ * communicate and resolve various catalogs from the registry.
+ */
 public interface RegistryConfig {
 
+    /**
+     * Registry ID. Mainly used in the logging and error messages to refer to a specific registry.
+     *
+     * @return registry id, never null
+     */
     String getId();
 
+    /**
+     * Whether this registry should be excluded from the active registry list, in which case
+     * the client won't be sending any requests to the registry.
+     *
+     * @return true, if the registry should be disabled, otherwise - false
+     */
     boolean isDisabled();
 
+    /**
+     * How often (if ever) the locally cached catalogs provided by the registry
+     * should be refreshed. The value returned by the method should currently be
+     * <code>always</code>, <code>daily</code> (default), <code>interval:XXX</code>
+     * (in minutes) or <code>never</code> (only if it doesn't exist locally).
+     *
+     * @return update policy
+     */
     String getUpdatePolicy();
 
+    /**
+     * How to get the descriptor from the registry. A registry descriptor is the default
+     * client configuration for the registry that can be customized on the client side, if necessary.
+     *
+     * @return registry descriptor related configuration
+     */
     RegistryDescriptorConfig getDescriptor();
 
+    /**
+     * How get platform catalogs from the registry.
+     *
+     * @return platform catalog related configuration
+     */
     RegistryPlatformsConfig getPlatforms();
 
+    /**
+     * How to get catalogs of non-platform extensions from the registry.
+     *
+     * @return non-platform extension catalog related configuration
+     */
     RegistryNonPlatformExtensionsConfig getNonPlatformExtensions();
 
+    /**
+     * Registry client Maven related configuration, such as repository URL, etc.
+     *
+     * @return registry client Maven related configuration
+     */
     RegistryMavenConfig getMaven();
 
+    /**
+     * Registry specific Quarkus version filtering configuration. For example,
+     * a given registry may provide platform and extension information that are based
+     * on specific versions of Quarkus core. Properly configured configured may
+     * reduce the amount of unnecessary remote registry requests.
+     *
+     * @return Quarkus version filtering configuration
+     */
     RegistryQuarkusVersionsConfig getQuarkusVersions();
 
+    /**
+     * Custom registry client configuration.
+     *
+     * @return custom registry client configuration
+     */
     Map<String, Object> getExtra();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryDescriptorConfig.java

@@ -2,7 +2,17 @@
 
 import io.quarkus.maven.ArtifactCoords;
 
+/**
+ * Configuration related to resolution of the registry descriptor.
+ * Registry descriptor represents the default client configuration to communicate with the registry
+ * that can be customized, if necessary, on the client side.
+ */
 public interface RegistryDescriptorConfig {
 
+    /**
+     * Coordinates of the registry descriptor artifact in the registry.
+     *
+     * @return coordinates of the registry descriptor artifact in the registry
+     */
     ArtifactCoords getArtifact();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryMavenConfig.java

@@ -1,6 +1,15 @@
 package io.quarkus.registry.config;
 
+/**
+ * Registry Maven related configuration the client should use
+ * to communicate with the registry.
+ */
 public interface RegistryMavenConfig {
 
+    /**
+     * Registry Maven repository configuration.
+     *
+     * @return registry Maven repository configuration
+     */
     RegistryMavenRepoConfig getRepository();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryMavenRepoConfig.java

@@ -1,8 +1,21 @@
 package io.quarkus.registry.config;
 
+/**
+ * Registry Maven repository configuration.
+ */
 public interface RegistryMavenRepoConfig {
 
+    /**
+     * Default registry Maven repository ID.
+     *
+     * @return default registry Maven repository ID
+     */
     String getId();
 
+    /**
+     * Registry Maven repository URL
+     *
+     * @return registry Maven repository URL
+     */
     String getUrl();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryNonPlatformExtensionsConfig.java

@@ -1,5 +1,8 @@
 package io.quarkus.registry.config;
 
+/**
+ * Configuration related to the resolution of catalogs of non-platform extensions.
+ */
 public interface RegistryNonPlatformExtensionsConfig extends RegistryArtifactConfig {
 
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryPlatformsConfig.java

@@ -1,6 +1,17 @@
 package io.quarkus.registry.config;
 
+/**
+ * Configuration related to the resolution of catalogs of available platforms.
+ */
 public interface RegistryPlatformsConfig extends RegistryArtifactConfig {
 
+    /**
+     * Whether the client should send requests to resolve the platform extension catalogs (platform descriptors)
+     * to the registry or resolve them from Maven Central directly instead.
+     * Returning <code>null</code> from this method will be equivalent to returning <code>false</code>, in which case
+     * the client will not send requests to resolve platform extension catalogs to the registry.
+     *
+     * @return true if the registry will be able to handle platform descriptor requests, otherwise - false
+     */
     Boolean getExtensionCatalogsIncluded();
 }

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/config/RegistryQuarkusVersionsConfig.java

@@ -1,8 +1,28 @@
 package io.quarkus.registry.config;
 
+/**
+ * A registry may be configured to accept requests only for the Quarkus versions
+ * it recognizes. This may avoid unnecessary remote registry requests from the client.
+ */
 public interface RegistryQuarkusVersionsConfig {
 
+    /**
+     * An expression that will be evaluated on the client side before sending
+     * a request to the registry that will indicate whether the registry recognizes
+     * a given Quarkus version or not.
+     *
+     * @return Quarkus version filtering expression or null
+     */
     String getRecognizedVersionsExpression();
 
+    /**
+     * If the Quarkus version expression is provided, this method may also enforce that
+     * Quarkus versions matching the provided expressions are expected to be provided
+     * by this registry exclusively. This may further reduce the amount of the remote requests
+     * a client will be sending in case multiple registries have been configured.
+     *
+     * @return whether the registry is an exclusive provider of the Quarkus versions matching
+     *         the expression configured in {@link getRecognizedVersionsExpression}
+     */
     boolean isExclusiveProvider();
 }