feat: allow creating a builder from a pre-existing purl (package-url#168)

* Allow creating a builder from a pre-existing purl

This is useful if you have an existing purl and need to modify one or
more of its components.

This differs from `PackageURL::toBuilder` in that it doesn't require
the direct use of the `PackageURL` constructor which conflicts with the
builder pattern.

* Fix some missing javadoc

Author: dwalluck

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

@@ -166,8 +166,13 @@ public PackageURL(final String type, final String namespace, final String name,
      */
     private String subpath;
 
+    /**
+     * Converts this {@link PackageURL} to a {@link PackageURLBuilder}.
+     *
+     * @return the builder
+     * @deprecated Use {@link PackageURLBuilder#aPackageURL(PackageURL)} or {@link PackageURLBuilder#aPackageURL(String)}
+     */
     public PackageURLBuilder toBuilder() {
-
         PackageURLBuilder builder = PackageURLBuilder.aPackageURL()
                 .withType(getType())
                 .withNamespace(getNamespace())
@@ -180,7 +185,6 @@ public PackageURLBuilder toBuilder() {
         }
 
         return builder;
-
     }
 
     /**

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

@@ -43,14 +43,35 @@ private PackageURLBuilder() {
     }
 
     /**
-     * Obtain a reference to a new builder object.
+     * Obtains a reference to a new builder object.
      *
-     * @return a new builder object.
+     * @return a new builder object
      */
     public static PackageURLBuilder aPackageURL() {
         return new PackageURLBuilder();
     }
 
+    /**
+     * Obtains a reference to a new builder object initialized with the existing {@link PackageURL} object.
+     *
+     * @param packageURL the existing Package URL object
+     * @return a new builder object
+     */
+    public static PackageURLBuilder aPackageURL(final PackageURL packageURL) {
+        return packageURL.toBuilder();
+    }
+
+    /**
+     * Obtain a reference to a new builder object initialized with the existing Package URL string.
+     *
+     * @param purl the existing Package URL string
+     * @return a new builder object
+     * @throws MalformedPackageURLException if an error occurs while parsing the input
+     */
+    public static PackageURLBuilder aPackageURL(final String purl) throws MalformedPackageURLException {
+        return new PackageURL(purl).toBuilder();
+    }
+
     /**
      * Adds the package URL type.
      *
@@ -150,6 +171,7 @@ public PackageURLBuilder withQualifiers(final Map<String, String> qualifiers) {
 
     /**
      * Removes a package qualifier. This is a no-op if the qualifier is not present.
+     *
      * @param key the package qualifier key to remove
      * @return a reference to the builder
      */
@@ -190,6 +212,7 @@ public PackageURLBuilder withoutQualifiers() {
 
     /**
      * Removes all qualifiers, if any.
+     *
      * @return a reference to this builder.
      */
     public PackageURLBuilder withNoQualifiers() {
@@ -199,6 +222,7 @@ public PackageURLBuilder withNoQualifiers() {
 
     /**
      * Returns current type value set in the builder.
+     *
      * @return type set in this builder
      */
     public String getType() {
@@ -207,6 +231,7 @@ public String getType() {
 
     /**
      * Returns current namespace value set in the builder.
+     *
      * @return namespace set in this builder
      */
     public String getNamespace() {
@@ -215,6 +240,7 @@ public String getNamespace() {
 
     /**
      * Returns current name value set in the builder.
+     *
      * @return name set in this builder
      */
     public String getName() {
@@ -223,6 +249,7 @@ public String getName() {
 
     /**
      * Returns current version value set in the builder.
+     *
      * @return version set in this builder
      */
     public String getVersion() {
@@ -231,6 +258,7 @@ public String getVersion() {
 
     /**
      * Returns current subpath value set in the builder.
+     *
      * @return subpath set in this builder
      */
     public String getSubpath() {
@@ -239,8 +267,9 @@ public String getSubpath() {
 
     /**
      * Returns sorted map containing all qualifiers set in this builder.
-     * An empty map is returned if no qualifiers is set.
-     * @return all qualifiers set in this builder, or an empty map if none are set.
+     * An empty map is returned if no qualifiers are set
+     *
+     * @return all qualifiers set in this builder, or an empty map if none are set
      */
     public Map<String, String> getQualifiers() {
         if (qualifiers == null) {
@@ -251,8 +280,9 @@ public Map<String, String> getQualifiers() {
 
     /**
      * Returns a currently set qualifier value set in the builder for the specified key.
+     *s
      * @param key qualifier key
-     * @return qualifier value or {@code null} if one is not set.
+     * @return qualifier value or {@code null} if one is not set
      */
     public String getQualifier(String key) {
         if (qualifiers == null) {

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

@@ -214,6 +214,16 @@ public void testQualifiers() throws MalformedPackageURLException {
         assertEquals("pkg:generic/name@version?key=value&key2=value2&key3=value3&next=value", purl.toString());
     }
 
+    @Test
+    public void testFromExistingPurl() throws MalformedPackageURLException {
+        String purl = "pkg:generic/namespace/name@1.0.0?k=v#s";
+        PackageURL p = new PackageURL(purl);
+        PackageURL purl2 = PackageURLBuilder.aPackageURL(p).build();
+        PackageURL purl3 = PackageURLBuilder.aPackageURL(purl).build();
+        assertEquals(p, purl2);
+        assertEquals(purl2, purl3);
+    }
+
     private void assertBuilderMatch(PackageURL expected, PackageURLBuilder actual) throws MalformedPackageURLException {
 
         Assert.assertEquals(expected.toString(), actual.build().toString());