GH-188: Implement package type providers

This uses the Java Service Provider Interface via `ServiceLoader` to
register new types, where each type gets its own class.

Author: dwalluck

src/main/java/com/github/packageurl/PackageURL.java

@@ -23,6 +23,7 @@
 
 import static java.util.Objects.requireNonNull;
 
+import com.github.packageurl.type.PackageTypeFactory;
 import java.io.Serializable;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -77,34 +78,34 @@ public final class PackageURL implements Serializable {
     private final String type;
 
     /**
-     * The name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
+     * The name prefix such as a Maven groupId, a Docker image owner, a GitHub user or organization.
      * Optional and type-specific.
      */
-    private final @Nullable String namespace;
+    private @Nullable String namespace;
 
     /**
      * The name of the package.
      * Required.
      */
-    private final String name;
+    private String name;
 
     /**
      * The version of the package.
      * Optional.
      */
-    private final @Nullable String version;
+    private @Nullable String version;
 
     /**
      * Extra qualifying data for a package such as an OS, architecture, a distro, etc.
      * Optional and type-specific.
      */
-    private final @Nullable Map<String, String> qualifiers;
+    private @Nullable Map<String, String> qualifiers;
 
     /**
      * Extra subpath within a package, relative to the package root.
      * Optional.
      */
-    private final @Nullable String subpath;
+    private @Nullable String subpath;
 
     /**
      * Constructs a new PackageURL object by parsing the specified string.
@@ -194,7 +195,6 @@ public PackageURL(final String purl) throws MalformedPackageURLException {
                 remainder = remainder.substring(0, index);
                 this.namespace = validateNamespace(this.type, parsePath(remainder.substring(start), false));
             }
-            verifyTypeConstraints(this.type, this.namespace, this.name);
         } catch (URISyntaxException e) {
             throw new MalformedPackageURLException("Invalid purl: " + e.getMessage(), e);
         }
@@ -264,7 +264,6 @@ public PackageURL(
         this.version = validateVersion(this.type, version);
         this.qualifiers = parseQualifiers(qualifiers);
         this.subpath = validateSubpath(subpath);
-        verifyTypeConstraints(this.type, this.namespace, this.name);
     }
 
     /**
@@ -360,11 +359,11 @@ private static String validateType(final String value) throws MalformedPackageUR
         return value;
     }
 
-    private static boolean isValidCharForType(int c) {
+    public static boolean isValidCharForType(int c) {
         return (isAlphaNumeric(c) || c == '.' || c == '+' || c == '-');
     }
 
-    private static boolean isValidCharForKey(int c) {
+    public static boolean isValidCharForKey(int c) {
         return (isAlphaNumeric(c) || c == '.' || c == '_' || c == '-');
     }
 
@@ -538,6 +537,12 @@ private static void validateValue(final String key, final @Nullable String value
         }
     }
 
+    public PackageURL normalize() throws MalformedPackageURLException {
+        PackageTypeFactory.getInstance().validateComponents(type, namespace, name, version, qualifiers, subpath);
+        return PackageTypeFactory.getInstance()
+                .normalizeComponents(type, namespace, name, version, qualifiers, subpath);
+    }
+
     /**
      * Returns the canonicalized representation of the purl.
      *
@@ -565,6 +570,17 @@ public String canonicalize() {
      * @since 1.3.2
      */
     private String canonicalize(boolean coordinatesOnly) {
+        try {
+            PackageURL packageURL = normalize();
+            namespace = packageURL.getNamespace();
+            name = packageURL.getName();
+            version = packageURL.getVersion();
+            qualifiers = packageURL.getQualifiers();
+            subpath = packageURL.getSubpath();
+        } catch (MalformedPackageURLException e) {
+            throw new ValidationException("Normalization failed", e);
+        }
+
         final StringBuilder purl = new StringBuilder();
         purl.append(SCHEME_PART).append(type).append('/');
         if (namespace != null) {
@@ -577,7 +593,7 @@ private String canonicalize(boolean coordinatesOnly) {
         }
 
         if (!coordinatesOnly) {
-            if (qualifiers != null) {
+            if (!qualifiers.isEmpty()) {
                 purl.append('?');
                 Set<Map.Entry<String, String>> entries = qualifiers.entrySet();
                 boolean separator = false;
@@ -606,18 +622,22 @@ private static boolean shouldEncode(int c) {
         return !isUnreserved(c);
     }
 
-    private static boolean isAlpha(int c) {
+    public static boolean isAlpha(int c) {
         return (isLowerCase(c) || isUpperCase(c));
     }
 
     private static boolean isDigit(int c) {
         return (c >= '0' && c <= '9');
     }
 
-    private static boolean isAlphaNumeric(int c) {
+    public static boolean isAlphaNumeric(int c) {
         return (isDigit(c) || isAlpha(c));
     }
 
+    public static boolean isWhitespace(int c) {
+        return (c == ' ' || c == '\t' || c == '\r' || c == '\n');
+    }
+
     private static boolean isUpperCase(int c) {
         return (c >= 'A' && c <= 'Z');
     }
@@ -642,7 +662,7 @@ private static int toLowerCase(int c) {
         return isUpperCase(c) ? (c ^ 0x20) : c;
     }
 
-    static String toLowerCase(String s) {
+    public static String toLowerCase(String s) {
         int pos = indexOfFirstUpperCaseChar(s);
 
         if (pos == -1) {
@@ -770,22 +790,6 @@ static String percentEncode(final String source) {
         return changed ? new String(buffer.array(), 0, buffer.position(), StandardCharsets.UTF_8) : source;
     }
 
-    /**
-     * Some purl types may have specific constraints. This method attempts to verify them.
-     * @param type the purl type
-     * @param namespace the purl namespace
-     * @throws MalformedPackageURLException if constraints are not met
-     */
-    private static void verifyTypeConstraints(String type, @Nullable String namespace, @Nullable String name)
-            throws MalformedPackageURLException {
-        if (StandardTypes.MAVEN.equals(type)) {
-            if (isEmpty(namespace) || isEmpty(name)) {
-                throw new MalformedPackageURLException(
-                        "The PackageURL specified is invalid. Maven requires both a namespace and name.");
-            }
-        }
-    }
-
     private static @Nullable Map<String, String> parseQualifiers(final @Nullable Map<String, String> qualifiers)
             throws MalformedPackageURLException {
         if (qualifiers == null || qualifiers.isEmpty()) {
@@ -1107,15 +1111,15 @@ public static final class StandardTypes {
          * @deprecated use {@link #DEB} instead
          */
         @Deprecated
-        public static final String DEBIAN = "deb";
+        public static final String DEBIAN = DEB;
         /**
          * Nixos packages.
          *
          * @since 1.1.0
          * @deprecated use {@link #NIX} instead
          */
         @Deprecated
-        public static final String NIXPKGS = "nix";
+        public static final String NIXPKGS = NIX;
 
         private StandardTypes() {}
     }

src/main/java/com/github/packageurl/ValidationException.java

@@ -38,4 +38,8 @@ class ValidationException extends RuntimeException {
     ValidationException(String msg) {
         super(msg);
     }
+
+    ValidationException(String msg, Throwable cause) {
+        super(msg, cause);
+    }
 }

src/main/java/com/github/packageurl/type/ApkPackageTypeProvider.java

@@ -0,0 +1,24 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+public class ApkPackageTypeProvider extends LowercaseNamespaceAndNameTypeProvider {}

src/main/java/com/github/packageurl/type/BitbucketPackageTypeProvider.java

@@ -0,0 +1,24 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+public class BitbucketPackageTypeProvider extends LowercaseNamespaceAndNameTypeProvider {}

src/main/java/com/github/packageurl/type/BitnamiPackageTypeProvider.java

@@ -0,0 +1,24 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+public class BitnamiPackageTypeProvider extends LowercaseNamespacePackageTypeProvider {}

src/main/java/com/github/packageurl/type/CocoapodsPackageTypeProvider.java

@@ -0,0 +1,48 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+import com.github.packageurl.MalformedPackageURLException;
+import com.github.packageurl.PackageURL;
+import java.util.Map;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+public class CocoapodsPackageTypeProvider implements PackageTypeProvider {
+    @Override
+    public void validateComponents(
+            @NonNull String type,
+            @Nullable String namespace,
+            @NonNull String name,
+            @Nullable String version,
+            @Nullable Map<String, String> qualifiers,
+            @Nullable String subpath)
+            throws MalformedPackageURLException {
+        if (namespace != null && !namespace.isEmpty()) {
+            throw new MalformedPackageURLException("invalid cocoapods purl cannot have a namespace");
+        }
+
+        if (name.chars().anyMatch(PackageURL::isWhitespace) || name.startsWith(".") || name.contains("+")) {
+            throw new MalformedPackageURLException("invalid cocoapods purl invalid name");
+        }
+    }
+}

src/main/java/com/github/packageurl/type/ComposerPackageTypeProvider.java

@@ -0,0 +1,24 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+public class ComposerPackageTypeProvider extends LowercaseNamespaceAndNameTypeProvider {}

src/main/java/com/github/packageurl/type/ConanPackageTypeProvider.java

@@ -0,0 +1,47 @@
+/*
+ * MIT License
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.github.packageurl.type;
+
+import com.github.packageurl.MalformedPackageURLException;
+import java.util.Map;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+public class ConanPackageTypeProvider implements PackageTypeProvider {
+    @Override
+    public void validateComponents(
+            @NonNull String type,
+            @Nullable String namespace,
+            @NonNull String name,
+            @Nullable String version,
+            @Nullable Map<String, String> qualifiers,
+            @Nullable String subpath)
+            throws MalformedPackageURLException {
+        boolean hasChannel = (qualifiers != null && !qualifiers.isEmpty());
+
+        if ((namespace != null && !namespace.isEmpty()) && !hasChannel) {
+            throw new MalformedPackageURLException("invalid conan purl only namespace");
+        } else if ((namespace == null || namespace.isEmpty()) && hasChannel) {
+            throw new MalformedPackageURLException("invalid conan purl only channel qualifier");
+        }
+    }
+}