- 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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
PackageURL.Builder
A builder construct for Package-URL objects.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static PackageURL.Builder
builder()
Get a builder for creating a PackageURL from elements.String
canonicalize()
Returns the canonicalized representation of the purl.boolean
equals(Object o)
static PackageURL
from(URI uri)
Convert the provided URI to a PackageURL.int
hashCode()
boolean
isCanonicalEquals(PackageURL purl)
Evaluates if the specified Package URL has the same canonical value.boolean
isCoordinatesEquals(PackageURL purl)
Evaluates if the specified Package URL has the same values up to, but excluding the qualifier (querystring).String
name()
Returns the name of the package.Optional<String>
namespace()
Returns the name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.static PackageURL
parse(String purl)
Parse a PackageURL from the given String.Optional<Map<String,String>>
qualifiers()
Returns extra qualifying data for a package such as an OS, architecture, a distro, etc.Optional<String>
subpath()
Returns extra subpath within a package, relative to the package root.String
toString()
Returns the canonicalized representation of the purl.URI
toURI()
Create a URI from the canonical PackageURL.String
type()
Returns the package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.Optional<String>
version()
Returns the version of the package.
-
-
-
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.
-
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
-
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
-
-