Package com.github.packageurl

Class PackageURL

java.lang.Object

com.github.packageurl.PackageURL

All Implemented Interfaces:

Serializable

public final class PackageURL
extends Object
implements Serializable

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

Since:

1.0.0

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PackageURL.StandardTypes	Convenience constants that defines common Package-URL 'type's.

Field Summary

Fields

Modifier and Type	Field	Description
private String	name	The name of the package.
private String	namespace	The name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
private static final Pattern	PATH_SPLITTER
private Map<String,String>	qualifiers	Extra qualifying data for a package such as an OS, architecture, a distro, etc.
private String	scheme	The PackageURL scheme constant
private static final long	serialVersionUID
private String	subpath	Extra subpath within a package, relative to the package root.
private String	type	The package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.
private String	version	The version of the package.

Constructor Summary

Constructors

Constructor	Description
PackageURL(String purl)	Constructs a new PackageURL object by parsing the specified string.
PackageURL(String type, String name)	Constructs a new PackageURL object by specifying only the required parameters necessary to create a valid PackageURL.
PackageURL(String type, String namespace, String name, String version, TreeMap<String,String> qualifiers, String subpath)	Constructs a new PackageURL object.

Method Summary

Modifier and Type	Method	Description
String	canonicalize()	Returns the canonicalized representation of the purl.
private String	canonicalize(boolean coordinatesOnly)	Returns the canonicalized representation of the purl.
private String	encodePath(String path)
boolean	equals(Object o)
String	getCoordinates()	Returns only the canonicalized coordinates of the Package URL which includes the type, namespace, name, and version, and which omits the qualifier and subpath.
String	getName()	Returns the name of the package.
String	getNamespace()	Returns the name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
Map<String,String>	getQualifiers()	Returns extra qualifying data for a package such as an OS, architecture, a distro, etc.
String	getScheme()	Returns the package url scheme.
String	getSubpath()	Returns extra subpath within a package, relative to the package root.
String	getType()	Returns the package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.
String	getVersion()	Returns the version of the package.
int	hashCode()
private static boolean	isAlpha(int c)
boolean	isBaseEquals(PackageURL purl)	Deprecated. This method is no longer recommended and will be removed from a future release.
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).
private static boolean	isDigit(int c)
private static boolean	isUnreserved(int c)
private void	parse(String purl)	Given a specified PackageURL, this method will parse the purl and populate this classes instance fields so that the corresponding getters may be called to retrieve the individual pieces of the purl.
private String[]	parsePath(String value, boolean isSubpath)
private Map<String,String>	parseQualifiers(String encodedString)
private String	percentDecode(String input)	Optionally decodes a String, if it's encoded.
private String	percentEncode(String input)	Encodes the input in conformance with RFC 3986.
PackageURLBuilder	toBuilder()
String	toString()	Returns the canonicalized representation of the purl.
static String	uriDecode(String source)
private static String	uriEncode(String source, Charset charset)
private String	validateKey(String value)
private String	validateName(String value)
private String	validateNamespace(String value)
private String	validateNamespace(String[] values)
private String	validatePath(String[] segments, boolean isSubpath)
private String	validatePath(String value, boolean isSubpath)
private Map<String,String>	validateQualifiers(Map<String,String> values)
private String	validateScheme(String value)
private String	validateType(String value)
private String	validateVersion(String value)
private void	verifyTypeConstraints(String type, String namespace, String name)	Some purl types may have specific constraints.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

serialVersionUID

private static final long serialVersionUID

See Also:

• Constant Field Values

PATH_SPLITTER

private static final Pattern PATH_SPLITTER

scheme

private String scheme

The PackageURL scheme constant

type

private String type

The package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc. Required.

namespace

private String namespace

The name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization. Optional and type-specific.

name

private String name

The name of the package. Required.

version

private String version

The version of the package. Optional.

qualifiers

private Map<String,String> qualifiers

Extra qualifying data for a package such as an OS, architecture, a distro, etc. Optional and type-specific.

subpath

private String subpath

Extra subpath within a package, relative to the package root. Optional.

Constructor Details

PackageURL

public PackageURL(String purl)
           throws MalformedPackageURLException

Constructs a new PackageURL object by parsing the specified string.

Parameters:

purl - a valid package URL string to parse

Throws:

MalformedPackageURLException - if parsing fails

Since:

1.0.0

PackageURL

public PackageURL(String type,
 String name)
           throws MalformedPackageURLException

Constructs a new PackageURL object by specifying only the required parameters necessary to create a valid PackageURL.

Parameters:

type - the type of package (i.e. maven, npm, gem, etc)

name - the name of the package

Throws:

MalformedPackageURLException - if parsing fails

Since:

1.0.0

PackageURL

public PackageURL(String type,
 String namespace,
 String name,
 String version,
 TreeMap<String,String> qualifiers,
 String subpath)
           throws MalformedPackageURLException

Constructs a new PackageURL object.

Parameters:

type - the type of package (i.e. maven, npm, gem, etc)

namespace - the name prefix (i.e. group, owner, organization)

name - the name of the package

version - the version of the package

qualifiers - an array of key/value pair qualifiers

subpath - the subpath string

Throws:

MalformedPackageURLException - if parsing fails

Since:

1.0.0

Method Details

toBuilder

public PackageURLBuilder toBuilder()

getScheme

public String getScheme()

Returns the package url scheme.

Returns:

the scheme

Since:

1.0.0

getType

public String getType()

Returns the package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.

Returns:

the type

Since:

1.0.0

getNamespace

public String getNamespace()

Returns the name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.

Returns:

the namespace

Since:

1.0.0

getName

public String getName()

Returns the name of the package.

Returns:

the name of the package

Since:

1.0.0

getVersion

public String getVersion()

Returns the version of the package.

Returns:

the version of the package

Since:

1.0.0

getQualifiers

public Map<String,String> getQualifiers()

Returns extra qualifying data for a package such as an OS, architecture, a distro, etc. This method returns an UnmodifiableMap.

Returns:

qualifiers

Since:

1.0.0

getSubpath

public String getSubpath()

Returns extra subpath within a package, relative to the package root.

Returns:

the subpath

Since:

1.0.0

validateScheme

private String validateScheme(String value)
                       throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateType

private String validateType(String value)
                     throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateNamespace

private String validateNamespace(String value)
                          throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateNamespace

private String validateNamespace(String[] values)
                          throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateName

private String validateName(String value)
                     throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateVersion

private String validateVersion(String value)

validateQualifiers

private Map<String,String> validateQualifiers(Map<String,String> values)
                                       throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validateKey

private String validateKey(String value)
                    throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validatePath

private String validatePath(String value,
 boolean isSubpath)
                     throws MalformedPackageURLException

Throws:

MalformedPackageURLException

validatePath

private String validatePath(String[] segments,
 boolean isSubpath)
                     throws MalformedPackageURLException

Throws:

MalformedPackageURLException

toString

public String toString()

Returns the canonicalized representation of the purl.

Overrides:

toString in class Object

Returns:

the canonicalized representation of the purl

Since:

1.1.0

canonicalize

public String canonicalize()

Returns the canonicalized representation of the purl.

Returns:

the canonicalized representation of the purl

Since:

1.0.0

canonicalize

private String canonicalize(boolean coordinatesOnly)

Returns the canonicalized representation of the purl.

Returns:

the canonicalized representation of the purl

Since:

1.3.2

percentEncode

private String percentEncode(String input)

Encodes the input in conformance with RFC 3986.

Parameters:

input - the String to encode

Returns:

an encoded String

uriEncode

private static String uriEncode(String source,
 Charset charset)

isUnreserved

private static boolean isUnreserved(int c)

isAlpha

private static boolean isAlpha(int c)

isDigit

private static boolean isDigit(int c)

percentDecode

private String percentDecode(String input)

Optionally decodes a String, if it's encoded. If String is not encoded, method will return the original input value.

Parameters:

input - the value String to decode

Returns:

a decoded String

uriDecode

public static String uriDecode(String source)

parse

private void parse(String purl)
            throws MalformedPackageURLException

Given a specified PackageURL, this method will parse the purl and populate this classes instance fields so that the corresponding getters may be called to retrieve the individual pieces of the purl.

Parameters:

purl - the purl string to parse

Throws:

MalformedPackageURLException - if an exception occurs when parsing

verifyTypeConstraints

private void verifyTypeConstraints(String type,
 String namespace,
 String name)
                            throws MalformedPackageURLException

Some purl types may have specific constraints. This method attempts to verify them.

Parameters:

type - the purl type

namespace - the purl namespace

name - the purl name

Throws:

MalformedPackageURLException - if constraints are not met

parseQualifiers

private Map<String,String> parseQualifiers(String encodedString)
                                    throws MalformedPackageURLException

Throws:

MalformedPackageURLException

parsePath

private String[] parsePath(String value,
 boolean isSubpath)
                    throws MalformedPackageURLException

Throws:

MalformedPackageURLException

encodePath

private String encodePath(String path)

isBaseEquals

@Deprecated
public boolean isBaseEquals(PackageURL purl)

Deprecated.

This method is no longer recommended and will be removed from a future release.

Use isCoordinatesEquals(com.github.packageurl.PackageURL) instead.

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.2.0

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

getCoordinates

public String getCoordinates()

Returns only the canonicalized coordinates of the Package URL which includes the type, namespace, name, and version, and which omits the qualifier and subpath.

Returns:

A canonicalized PackageURL String excluding the qualifier and subpath.

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