Package com.github.packageurl

Class PackageURL

  • All Implemented Interfaces:
    java.io.Serializable
    public final class PackageURL
extends java.lang.Object
implements java.io.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 java.lang.String name
      The name of the package.
      private java.lang.String namespace
      The name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
      private static java.util.regex.Pattern PATH_SPLITTER  
      private java.util.Map<java.lang.String,​java.lang.String> qualifiers
      Extra qualifying data for a package such as an OS, architecture, a distro, etc.
      private java.lang.String scheme
      The PackageURL scheme constant
      private static long serialVersionUID  
      private java.lang.String subpath
      Extra subpath within a package, relative to the package root.
      private java.lang.String type
      The package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.
      private java.lang.String version
      The version of the package.

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.String canonicalize()
      Returns the canonicalized representation of the purl.
      private java.lang.String canonicalize​(boolean coordinatesOnly)
      Returns the canonicalized representation of the purl.
      private java.lang.String encodePath​(java.lang.String path)  
      boolean equals​(java.lang.Object o)  
      java.lang.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.
      java.lang.String getName()
      Returns the name of the package.
      java.lang.String getNamespace()
      Returns the name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization.
      java.util.Map<java.lang.String,​java.lang.String> getQualifiers()
      Returns extra qualifying data for a package such as an OS, architecture, a distro, etc.
      java.lang.String getScheme()
      Returns the package url scheme.
      java.lang.String getSubpath()
      Returns extra subpath within a package, relative to the package root.
      java.lang.String getType()
      Returns the package "type" or package "protocol" such as maven, npm, nuget, gem, pypi, etc.
      java.lang.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​(java.lang.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 java.lang.String[] parsePath​(java.lang.String value, boolean isSubpath)  
      private java.util.Map<java.lang.String,​java.lang.String> parseQualifiers​(java.lang.String encodedString)  
      private java.lang.String percentDecode​(java.lang.String input)
      Optionally decodes a String, if it's encoded.
      private java.lang.String percentEncode​(java.lang.String input)
      Encodes the input in conformance with RFC 3986.
      PackageURLBuilder toBuilder()  
      java.lang.String toString()
      Returns the canonicalized representation of the purl.
      static java.lang.String uriDecode​(java.lang.String source)  
      private static java.lang.String uriEncode​(java.lang.String source, java.nio.charset.Charset charset)  
      private java.lang.String validateKey​(java.lang.String value)  
      private java.lang.String validateName​(java.lang.String value)  
      private java.lang.String validateNamespace​(java.lang.String value)  
      private java.lang.String validateNamespace​(java.lang.String[] values)  
      private java.lang.String validatePath​(java.lang.String[] segments, boolean isSubpath)  
      private java.lang.String validatePath​(java.lang.String value, boolean isSubpath)  
      private java.util.Map<java.lang.String,​java.lang.String> validateQualifiers​(java.util.Map<java.lang.String,​java.lang.String> values)  
      private java.lang.String validateScheme​(java.lang.String value)  
      private java.lang.String validateType​(java.lang.String value)  
      private java.lang.String validateVersion​(java.lang.String value)  
      private void verifyTypeConstraints​(java.lang.String type, java.lang.String namespace, java.lang.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 Detail

      • PATH_SPLITTER

        private static final java.util.regex.Pattern PATH_SPLITTER

      • scheme

        private java.lang.String scheme
        The PackageURL scheme constant

      • type

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

      • namespace

        private java.lang.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 java.lang.String name
        The name of the package. Required.

      • version

        private java.lang.String version
        The version of the package. Optional.

      • qualifiers

        private java.util.Map<java.lang.String,​java.lang.String> qualifiers
        Extra qualifying data for a package such as an OS, architecture, a distro, etc. Optional and type-specific.

      • subpath

        private java.lang.String subpath
        Extra subpath within a package, relative to the package root. Optional.

    • Constructor Detail

      • PackageURL

        public PackageURL​(java.lang.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​(java.lang.String type,
                  java.lang.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​(java.lang.String type,
                  java.lang.String namespace,
                  java.lang.String name,
                  java.lang.String version,
                  java.util.TreeMap<java.lang.String,​java.lang.String> qualifiers,
                  java.lang.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 Detail

      • getScheme

        public java.lang.String getScheme()
        Returns the package url scheme.
        Returns:
        the scheme
        Since:
        1.0.0

      • getType

        public java.lang.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 java.lang.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 java.lang.String getName()
        Returns the name of the package.
        Returns:
        the name of the package
        Since:
        1.0.0

      • getVersion

        public java.lang.String getVersion()
        Returns the version of the package.
        Returns:
        the version of the package
        Since:
        1.0.0

      • getQualifiers

        public java.util.Map<java.lang.String,​java.lang.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 java.lang.String getSubpath()
        Returns extra subpath within a package, relative to the package root.
        Returns:
        the subpath
        Since:
        1.0.0

      • validateVersion

        private java.lang.String validateVersion​(java.lang.String value)

      • toString

        public java.lang.String toString()
        Returns the canonicalized representation of the purl.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the canonicalized representation of the purl
        Since:
        1.1.0

      • canonicalize

        public java.lang.String canonicalize()
        Returns the canonicalized representation of the purl.
        Returns:
        the canonicalized representation of the purl
        Since:
        1.0.0

      • canonicalize

        private java.lang.String canonicalize​(boolean coordinatesOnly)
        Returns the canonicalized representation of the purl.
        Returns:
        the canonicalized representation of the purl
        Since:
        1.3.2

      • percentEncode

        private java.lang.String percentEncode​(java.lang.String input)
        Encodes the input in conformance with RFC 3986.
        Parameters:
        input - the String to encode
        Returns:
        an encoded String

      • uriEncode

        private static java.lang.String uriEncode​(java.lang.String source,
                                          java.nio.charset.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 java.lang.String percentDecode​(java.lang.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 java.lang.String uriDecode​(java.lang.String source)

      • parse

        private void parse​(java.lang.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​(java.lang.String type,
                                   java.lang.String namespace,
                                   java.lang.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

      • encodePath

        private java.lang.String encodePath​(java.lang.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 java.lang.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​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object