Add PackageURL#getCoordinates method

[rgmz]

Description

To my knowledge, the current PackageURL.java implementation does not provide a simple way to retrieve the package's 'coordinates' (purl without subpath or qualifiers).

The package coordinates are useful for generic component information: pkg:deb/debian/curl@7.50.3-1 = cURL version 7.50.3-1.
Whereas the full purl is useful for specific component information: pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie&repository=... = cURL version 7.50.3-1 installed on Debian Jessie, i386 architecture, installed from this specific repository...

Proposed Solution

A PackageURL#getCoordinates method which returns pkg:type/namespace:name@version (no qualifiers or subpath).

For example, in Dependency-Track (a project you may have know about 😉), components have separate purl and purlCoordinates fields.

[stevespringett]

Thoughts?

/**
 * 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.3.2
 */
public String getCoordinates() {
    // TODO
}

[stevespringett]

BTW, Dependency-Track relies on its own PurlUtil.java which produces a new PackageURL object without the qualifiers or subpath. So a little different approach used in DT than what is proposed here.

[stevespringett]

I'll also likely deprecate isBaseEquals(PackageURL purl) and rename it to isCoordinatesEquals(final PackageURL purl) so there is consistency.

[rgmz]

Thanks, Steve.

Thoughts?

Looks good! I believe "coordinates" is a better descriptor than "base"; however, there may be a better term.

BTW, Dependency-Track relies on its own PurlUtil.java which produces a new PackageURL object without the qualifiers or subpath. So a little different approach used in DT than what is proposed here.

This is an interesting distinction.

My main use case is storing the purl in the database (getCoordinates) and comparing packages based on their base/coordinates (isCoordinatesEqual). Therefore, being able to say that pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie&repository=... is also pkg:deb/debian/curl@7.50.3-1 (and get that representation) is quite useful.

Although DTrack's PurlUtil.java creates a new object, is the actual usage different from what's described above? For example, in ComponentIdentity#toJSON(), do the purls get rendered as a String:

{
    # other fields
    "purlCoordinates": "pkg:type/namespace:name@version"
}

or as an object:

{
    # other fields
    "purlCoordinates": {
        "type": "type",
        "namespace": "namespace",
        # etc...
    }
}

(i.e., would the proposed change also benefit DTrack/others?)

[stevespringett]

Shouldn't be any different. If you're storing in a database, then there are typically two ways to do this.

1. Use a String object as what is proposed here. This will typically be persisted as a varchar in a relational database.
2. Use a PackageURL object and let the JDO/JPA layer persist it as a string/varchar but when interacting with the field, you'll be using a PackageURL object rather than a String.. However, when using this approach with JSON, it will create individual properties for each purl field (type, namespace, name, etc) which is probably what you don't want. To work around that you'd have to create a custom serializer for PackageURL objects. It's a lot of overhead with this approach.

You can also combine these two approaches which is what DT does. The field is defined as a String, but uses the @com.github.packageurl.validator.PackageURL annotation which validates the field, then the method signatures on the getters/setters use PackageURL objects rather than String. When JSON serializes/deserializes, it uses the fields (String) so all is good.

https://github.com/DependencyTrack/dependency-track/blob/master/src/main/java/org/dependencytrack/model/Component.java

[rgmz]

Apologies for letting this stagnate; I think the proposed implementation looks good.

Would you like me to open a PR for this, or do you have an existing branch?

[stevespringett]

I have something ready to go. I'll get it pushed today.

[stevespringett]

Fixed in v1.4.0