Class PackageURL


  • public final class PackageURL
    extends Object

    Package-URL (aka purl) is a "mostly universal" URL to describe a package. A purl is a URL composed of seven components:

     scheme:type/namespace/name@version?qualifiers#subpath
     

    Components are separated by a specific character for unambiguous parsing. A purl must NOT contain a URL Authority i.e. there is no support for username, password, host and port components. A namespace segment may sometimes look like a host but its interpretation is specific to a type.

    SPEC: https://github.com/package-url/purl-spec

    • Method Detail

      • type

        public String type()
        Returns the package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.
        Returns:
        the type
      • namespace

        public Optional<String> namespace()
        Returns the name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
        Returns:
        the namespace
      • name

        public String name()
        Returns the name of the package.
        Returns:
        the name of the package
      • version

        public Optional<String> version()
        Returns the version of the package.
        Returns:
        the version of the package
      • qualifiers

        public Optional<Map<String,​String>> qualifiers()
        Returns extra qualifying data for a package such as an OS, architecture, a distro, etc. This method returns an UnmodifiableMap.
        Returns:
        qualifiers
      • subpath

        public Optional<String> subpath()
        Returns extra subpath within a package, relative to the package root.
        Returns:
        the subpath
      • toString

        public String toString()
        Returns the canonicalized representation of the purl.
        Overrides:
        toString in class Object
        Returns:
        the canonicalized representation of the purl
      • canonicalize

        public String canonicalize()
        Returns the canonicalized representation of the purl.
        Returns:
        the canonicalized representation of the purl
      • toURI

        public URI toURI()
        Create a URI from the canonical PackageURL.
        Returns:
        package url as uri
      • isCoordinatesEquals

        public boolean isCoordinatesEquals​(PackageURL 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.
        Parameters:
        purl - the Package URL to evaluate
        Returns:
        true if equivalence passes, false if not
        Since:
        1.4.0
      • isCanonicalEquals

        public boolean isCanonicalEquals​(PackageURL purl)
        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 canonical values. Canonical equivalence is especially useful for qualifiers, which can be in any order, but have a predictable order in canonicalized form.
        Parameters:
        purl - the Package URL to evaluate
        Returns:
        true if equivalence passes, false if not
        Since:
        1.2.0
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • parse

        public static PackageURL parse​(String purl)
        Parse a PackageURL from the given String.
        Parameters:
        purl - the purl string to parse
        Throws:
        IllegalArgumentException - if an exception occurs when parsing
      • builder

        public static PackageURL.Builder builder()
        Get a builder for creating a PackageURL from elements.
        Returns:
        builder