Add javadoc and fix one null issue

Author: dwalluck

src/main/java/com/github/packageurl/internal/PackageTypeFactory.java

@@ -40,19 +40,29 @@
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * The PackageTypeFactory is a singleton that provides a way to normalize and validate package URLs.
+ * It uses the ServiceLoader mechanism to load available PackageTypeProvider implementations.
+ * This class is not intended to be instantiated directly.
+ */
 @ServiceConsumer(
         value = PackageTypeProvider.class,
         resolution = Resolution.MANDATORY,
         cardinality = Cardinality.MULTIPLE)
 public final class PackageTypeFactory implements PackageTypeProvider {
     private static final @NonNull PackageTypeFactory INSTANCE = new PackageTypeFactory();
 
-    public static final @NonNull String TYPE = "__packagetypefactory__";
+    private static final @NonNull String TYPE = "__packagetypefactory__";
 
     private @Nullable Map<@NonNull String, @NonNull PackageTypeProvider> packageTypeProviders;
 
     private PackageTypeFactory() {}
 
+    /**
+     * Returns the singleton instance of PackageTypeFactory.
+     *
+     * @return the singleton instance of PackageTypeFactory
+     */
     public static @NonNull PackageTypeFactory getInstance() {
         return INSTANCE;
     }
@@ -116,6 +126,13 @@ private static void validateQualifiers(@Nullable Map<String, String> qualifiers)
         }
     }
 
+    /**
+     * Validates the type of the package URL. The type must start with an alphabetic character and
+     * can only contain alphanumeric characters, underscores, and hyphens.
+     *
+     * @param type the type of the package URL
+     * @throws MalformedPackageURLException if the type is invalid
+     */
     public static void validateType(@NonNull String type) throws MalformedPackageURLException {
         if (type.isEmpty()) {
             throw new MalformedPackageURLException("a type is always required");
@@ -207,6 +224,12 @@ public void validateComponents(
         });
     }
 
+    /**
+     * Returns a map of available package type providers. The map is unmodifiable and contains the
+     * package type as the key and the corresponding PackageTypeProvider as the value.
+     *
+     * @return a map of available package type providers
+     */
     public @NonNull Map<String, PackageTypeProvider> getPackageTypeProviders() {
         if (packageTypeProviders == null) {
             packageTypeProviders = findAvailablePackageTypeProviders();

src/main/java/com/github/packageurl/internal/PackageTypeProviders.java

@@ -32,18 +32,35 @@
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * This class provides a set of package type providers for different package types.
+ * Each provider implements the PackageTypeProvider interface and provides its own
+ * validation and normalization logic for the components of a package URL.
+ */
 public final class PackageTypeProviders {
     private PackageTypeProviders() {}
 
+    /**
+     * This class provides a package type provider for the "apk" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Apk extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "bitbucket" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Bitbucket extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "bitnami" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Bitnami extends LowercaseNamespacePackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "cocoapods" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Cocoapods implements PackageTypeProvider {
         @Override
@@ -65,9 +82,15 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "composer" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Composer extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "conan" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Conan implements PackageTypeProvider {
         @Override
@@ -89,6 +112,9 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "cpan" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Cpan implements PackageTypeProvider {
         @Override
@@ -108,6 +134,9 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "cran" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Cran implements PackageTypeProvider {
         @Override
@@ -125,18 +154,33 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "deb" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Deb extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "generic" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Generic implements PackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "github" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Github extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "golang" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Golang extends LowercaseNamespacePackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "hackage" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Hackage implements PackageTypeProvider {
         @Override
@@ -154,15 +198,27 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "hex" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Hex extends LowercaseNamespaceAndNameTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "huggingface" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Huggingface extends LowercaseVersionPackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "luarocks" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Luarocks extends LowercaseVersionPackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "maven" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Maven implements PackageTypeProvider {
         @Override
@@ -180,9 +236,12 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "mlflow" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Mlflow implements PackageTypeProvider {
-        private static @Nullable String normalizeName(@Nullable String name, @Nullable Map<String, String> qualifiers)
+        private static @NonNull String normalizeName(@NonNull String name, @Nullable Map<String, String> qualifiers)
                 throws MalformedPackageURLException {
             if (qualifiers != null) {
                 String repositoryUrl = qualifiers.get("repository_url");
@@ -194,7 +253,7 @@ public static class Mlflow implements PackageTypeProvider {
                         URI url = new URI(repositoryUrl);
                         host = url.getHost();
 
-                        if (name != null && host.matches(".*[.]?azuredatabricks.net$")) {
+                        if (host.matches(".*[.]?azuredatabricks.net$")) {
                             return StringUtil.toLowerCase(name);
                         }
                     } catch (URISyntaxException e) {
@@ -234,6 +293,9 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "oci" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Oci extends LowercaseNameAndVersionPackageTypeProvider {
         @Override
@@ -251,9 +313,15 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a package type provider for the "pub" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Pub extends LowercaseNamePackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "pypi" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Pypi implements PackageTypeProvider {
         @Override
@@ -270,12 +338,21 @@ public static class Pypi implements PackageTypeProvider {
         }
     }
 
+    /**
+     * This class provides a package type provider for the "qpkg" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Qpkg extends LowercaseNamespacePackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "rpm" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Rpm extends LowercaseNamespacePackageTypeProvider {}
 
+    /**
+     * This class provides a package type provider for the "swift" package type.
+     */
     @ServiceProvider(value = PackageTypeProvider.class, resolution = Resolution.MANDATORY)
     public static class Swift implements PackageTypeProvider {
         @Override
@@ -297,6 +374,9 @@ public void validateComponents(
         }
     }
 
+    /**
+     * This class provides a common interface for the lowercase name and version package types.
+     */
     public static class LowercaseNameAndVersionPackageTypeProvider implements PackageTypeProvider {
         @Override
         public @NonNull PackageURL normalizeComponents(
@@ -317,6 +397,9 @@ public static class LowercaseNameAndVersionPackageTypeProvider implements Packag
         }
     }
 
+    /**
+     * This class provides a common interface for the lowercase name package types.
+     */
     public static class LowercaseNamePackageTypeProvider implements PackageTypeProvider {
         @Override
         public @NonNull PackageURL normalizeComponents(
@@ -331,6 +414,9 @@ public static class LowercaseNamePackageTypeProvider implements PackageTypeProvi
         }
     }
 
+    /**
+     * This class provides a common interface for the lowercase namespace and name package types.
+     */
     public static class LowercaseNamespaceAndNameTypeProvider implements PackageTypeProvider {
         @Override
         public @NonNull PackageURL normalizeComponents(
@@ -351,6 +437,9 @@ public static class LowercaseNamespaceAndNameTypeProvider implements PackageType
         }
     }
 
+    /**
+     * This class provides a common interface for the lowercase namespace package types.
+     */
     public static class LowercaseNamespacePackageTypeProvider implements PackageTypeProvider {
         @Override
         public @NonNull PackageURL normalizeComponents(
@@ -371,6 +460,9 @@ public static class LowercaseNamespacePackageTypeProvider implements PackageType
         }
     }
 
+    /**
+     * This class provides a common interface for the lowercase version package types.
+     */
     public static class LowercaseVersionPackageTypeProvider implements PackageTypeProvider {
         @Override
         public @NonNull PackageURL normalizeComponents(

src/main/java/com/github/packageurl/internal/StringUtil.java

@@ -77,8 +77,6 @@ private StringUtil() {
      *
      * @param s the string to convert to lower case
      * @return the lower case version of the string
-     *
-     * @since 2.0.0
      */
     public static @NonNull String toLowerCase(@NonNull String s) {
         int pos = indexOfFirstUpperCaseChar(s);
@@ -101,8 +99,6 @@ private StringUtil() {
      *
      * @param source the string to decode
      * @return the percent decoded string
-     *
-     * @since 2.0.0
      */
     public static @NonNull String percentDecode(@NonNull final String source) {
         if (source.indexOf(PERCENT_CHAR) == -1) {
@@ -132,8 +128,6 @@ private StringUtil() {
      *
      * @param source the string to encode
      * @return the percent encoded string
-     *
-     * @since 2.0.0
      */
     public static @NonNull String percentEncode(@NonNull final String source) {
         if (!shouldEncode(source)) {
@@ -162,8 +156,6 @@ private StringUtil() {
      *
      * @param c the character to check
      * @return true if the character is a digit; otherwise, false
-     *
-     * @since 2.0.0
      */
     public static boolean isDigit(int c) {
         return (c >= '0' && c <= '9');
@@ -174,8 +166,6 @@ public static boolean isDigit(int c) {
      *
      * @param c the character to check
      * @return true if the character is valid for the package-url type; otherwise, false
-     *
-     * @since 2.0.0
      */
     public static boolean isValidCharForType(int c) {
         return (isAlphaNumeric(c) || c == '.' || c == '+' || c == '-');
@@ -186,8 +176,6 @@ public static boolean isValidCharForType(int c) {
      *
      * @param c the character to check
      * @return true if the character is valid for the package-url qualifier key; otherwise, false
-     *
-     * @since 2.0.0
      */
     public static boolean isValidCharForKey(int c) {
         return (isAlphaNumeric(c) || c == '.' || c == '_' || c == '-');
@@ -225,6 +213,12 @@ private static boolean shouldEncode(String s) {
         return false;
     }
 
+    /**
+     * Determines if the character is an ASCII alphabetic character, i.e., a lowercase or uppercase ASCII character.
+     *
+     * @param c the character to check
+     * @return whether the character is an ASCII alphabetic character
+     */
     public static boolean isAlpha(int c) {
         return (isLowerCase(c) || isUpperCase(c));
     }
@@ -241,6 +235,13 @@ private static boolean isLowerCase(int c) {
         return (c >= 'a' && c <= 'z');
     }
 
+    /**
+     * Determines if the character is an ASCII whitespace character, i.e.,
+     * one of {@code ['\f', '\t', '\n', '\r', '\v', ' ']}.
+     *
+     * @param c the character to check
+     * @return whether the character is an ASCII whitespace character
+     */
     public static boolean isWhitespace(int c) {
         if (c < 0 || c >= NBITS) {
             return false;