Module org.praxislive.purl
Package org.praxislive.purl

Class PackageURL

java.lang.Object
org.praxislive.purl.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 Details

    • 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

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • 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

    • from

      public static PackageURL from(URI uri) throws IllegalArgumentException
      Convert the provided URI to a PackageURL.
      Parameters:
      uri - the uri to convert
      Throws:
      IllegalArgumentException - if the uri is not a valid package url

    • builder

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