#24 - Added methods for obtaining purl strings containing coordinates only. Deprecated isBaseEquals(). Version bump.

Author: stevespringett

pom.xml

@@ -4,7 +4,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.github.package-url</groupId>
     <artifactId>packageurl-java</artifactId>
-    <version>1.3.2-SNAPSHOT</version>
+    <version>1.4.0-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>Package URL</name>

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

@@ -378,6 +378,16 @@ public String toString() {
      * @since 1.0.0
      */
     public String canonicalize() {
+        return canonicalize(false);
+    }
+
+    /**
+     * Returns the canonicalized representation of the purl.
+     *
+     * @return the canonicalized representation of the purl
+     * @since 1.3.2
+     */
+    private String canonicalize(boolean coordinatesOnly) {
         if (canonicalizedForm != null) {
             return canonicalizedForm;
         }
@@ -397,18 +407,20 @@ public String canonicalize() {
         if (version != null) {
             purl.append("@").append(percentEncode(version));
         }
-        if (qualifiers != null && qualifiers.size() > 0) {
-            purl.append("?");
-            qualifiers.entrySet().stream().forEachOrdered((entry) -> {
-                purl.append(entry.getKey().toLowerCase());
-                purl.append("=");
-                purl.append(percentEncode(entry.getValue()));
-                purl.append("&");
-            });
-            purl.setLength(purl.length() - 1);
-        }
-        if (subpath != null) {
-            purl.append("#").append(encodePath(subpath));
+        if (! coordinatesOnly) {
+            if (qualifiers != null && qualifiers.size() > 0) {
+                purl.append("?");
+                qualifiers.entrySet().stream().forEachOrdered((entry) -> {
+                    purl.append(entry.getKey().toLowerCase());
+                    purl.append("=");
+                    purl.append(percentEncode(entry.getValue()));
+                    purl.append("&");
+                });
+                purl.setLength(purl.length() - 1);
+            }
+            if (subpath != null) {
+                purl.append("#").append(encodePath(subpath));
+            }
         }
         canonicalizedForm = purl.toString();
         return canonicalizedForm;
@@ -594,19 +606,47 @@ private String encodePath(final String path) {
      * Evaluates if the specified Package URL has the same values up to, but excluding
      * the qualifier (querystring). This includes equivalence of: scheme, type, namespace,
      * name, and version, but excludes qualifier and subpath from evaluation.
+     * @deprecated
+     * This method is no longer recommended and will be removed from a future release.
+     * <p> Use {@link PackageURL#isCoordinatesEquals} instead.</p>
      *
      * @param purl the Package URL to evaluate
      * @return true if equivalence passes, false if not
      * @since 1.2.0
      */
+    //@Deprecated(since = "1.4.0", forRemoval = true)
+    @Deprecated
     public boolean isBaseEquals(final PackageURL purl) {
+        return isCoordinatesEquals(purl);
+    }
+
+    /**
+     * Evaluates if the specified Package URL has the same values up to, but excluding
+     * the qualifier (querystring). This includes equivalence of: scheme, type, namespace,
+     * name, and version, but excludes qualifier and subpath from evaluation.
+     *
+     * @param purl the Package URL to evaluate
+     * @return true if equivalence passes, false if not
+     * @since 1.4.0
+     */
+    public boolean isCoordinatesEquals(final PackageURL purl) {
         return Objects.equals(scheme, purl.scheme) &&
                 Objects.equals(type, purl.type) &&
                 Objects.equals(namespace, purl.namespace) &&
                 Objects.equals(name, purl.name) &&
                 Objects.equals(version, purl.version);
     }
 
+    /**
+     * Returns only the canonicalized coordinates of the Package URL which includes the type, namespace, name,
+     * and version, and which omits the qualifier and subpath.
+     * @return A canonicalized PackageURL String excluding the qualifier and subpath.
+     * @since 1.4.0
+     */
+    public String getCoordinates() {
+        return canonicalize(true);
+    }
+
     /**
      * Evaluates if the specified Package URL has the same canonical value. This method
      * canonicalizes the Package URLs being evaluated and performs an equivalence on the

src/test/java/com/github/packageurl/PackageURLTest.java

@@ -297,4 +297,10 @@ public void testCanonicalEquals() throws Exception {
         PackageURL p2 = new PackageURL("pkg:generic/acme/example-component@1.0.0?key2=value2&key1=value1");
         Assert.assertTrue(p1.isCanonicalEquals(p2));
     }
+
+    @Test
+    public void testGetCoordinates() throws Exception {
+        PackageURL purl = new PackageURL("pkg:generic/acme/example-component@1.0.0?key1=value1&key2=value2");
+        Assert.assertEquals("pkg:generic/acme/example-component@1.0.0", purl.getCoordinates());
+    }
 }