Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: add missing @deprecated and @since to javadoc #210

Merged
merged 5 commits into from
Mar 21, 2025
+248 −64
Merged

fix: add missing @deprecated and @since to javadoc #210

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
72aea80
fix: add missing `@deprecated` and `@since` to javadoc
dwalluck Mar 19, 2025
328ee7f
Merge remote-tracking branch 'upstream/master' into deprecated-and-since
dwalluck Mar 20, 2025
18818fe
fix: remove redundant `@since` on methods
dwalluck Mar 20, 2025
b4d3429
Change groupid to groupId in javadoc
dwalluck Mar 20, 2025
0b3b2b6
Merge remote-tracking branch 'upstream/master' into deprecated-and-since
dwalluck Mar 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 196 additions & 34 deletions src/main/java/com/github/packageurl/PackageURL.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,9 @@
* </pre>
* <p>
* 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,
* 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.
* like a host, but its interpretation is specific to a type.
* </p>
* <p>SPEC: <a href="https://github.com/package-url/purl-spec">https://github.com/package-url/purl-spec</a></p>
*
Expand Down Expand Up @@ -82,14 +82,14 @@ public PackageURL(final String purl) throws MalformedPackageURLException {
* @since 1.0.0
*/
public PackageURL(final String type, final String name) throws MalformedPackageURLException {
this(type, null, name, null, null, null);
this(type, null, name, null, (Map<String, String>) null, null);
}

/**
* Constructs a new PackageURL object.
*
* @param type the type of package (i.e. maven, npm, gem, etc), not {@code null}
* @param namespace the name prefix (i.e. group, owner, organization)
* @param type the type of package (i.e., maven, npm, gem, etc.), not {@code null}
* @param namespace the name prefix (i.e., group, owner, organization)
* @param name the name of the package, not {@code null}
* @param version the version of the package
* @param qualifiers an array of key/value pair qualifiers
Expand All @@ -108,20 +108,14 @@ public PackageURL(
final @Nullable TreeMap<String, String> qualifiers,
final @Nullable String subpath)
throws MalformedPackageURLException {
this.type = toLowerCase(validateType(requireNonNull(type, "type")));
this.namespace = validateNamespace(namespace);
this.name = validateName(requireNonNull(name, "name"));
this.version = validateVersion(type, version);
this.qualifiers = parseQualifiers(qualifiers);
this.subpath = validateSubpath(subpath);
verifyTypeConstraints(this.type, this.namespace, this.name);
this(type, namespace, name, version, qualifiers != null ? (Map<String, String>) qualifiers : null, subpath);
}

/**
* Constructs a new PackageURL object.
*
* @param type the type of package (i.e. maven, npm, gem, etc)
* @param namespace the name prefix (i.e. group, owner, organization)
* @param namespace the name prefix (i.e., group, owner, organization)
* @param name the name of the package
* @param version the version of the package
* @param qualifiers an array of key/value pair qualifiers
Expand All @@ -135,10 +129,16 @@ public PackageURL(
final @Nullable String namespace,
final String name,
final @Nullable String version,
final @Nullable Map<String, @Nullable String> qualifiers,
final @Nullable Map<String, String> qualifiers,
final @Nullable String subpath)
throws MalformedPackageURLException {
this(type, namespace, name, version, (qualifiers != null) ? new TreeMap<>(qualifiers) : null, subpath);
this.type = toLowerCase(validateType(requireNonNull(type, "type")));
this.namespace = validateNamespace(namespace);
this.name = validateName(requireNonNull(name, "name"));
this.version = validateVersion(type, version);
this.qualifiers = parseQualifiers(qualifiers);
this.subpath = validateSubpath(subpath);
verifyTypeConstraints(this.type, this.namespace, this.name);
}

/**
Expand Down Expand Up @@ -191,16 +191,12 @@ public PackageURL(
* Converts this {@link PackageURL} to a {@link PackageURLBuilder}.
*
* @return the builder
* @deprecated Use {@link PackageURLBuilder#aPackageURL(PackageURL)} or {@link PackageURLBuilder#aPackageURL(String)}
* @since 1.5.0
* @deprecated use {@link PackageURLBuilder#aPackageURL(PackageURL)} or {@link PackageURLBuilder#aPackageURL(String)}
*/
@Deprecated
public PackageURLBuilder toBuilder() {
return PackageURLBuilder.aPackageURL()
.withType(getType())
.withNamespace(getNamespace())
.withName(getName())
.withVersion(getVersion())
.withQualifiers(getQualifiers())
.withSubpath(getSubpath());
return PackageURLBuilder.aPackageURL(this);
}

/**
Expand Down Expand Up @@ -632,7 +628,7 @@ private static byte percentDecode(final byte[] bytes, final int start) {
return ((byte) ((c1 << 4) + c2));
}

public static String percentDecode(final String source) {
static String percentDecode(final String source) {
if (source.isEmpty()) {
return source;
}
Expand Down Expand Up @@ -674,8 +670,16 @@ public static String percentDecode(final String source) {
return new String(buffer.array(), 0, buffer.position(), StandardCharsets.UTF_8);
}

/**
* URI decodes the given string.
*
* @param source the encoded string
* @return the decoded string
* @since 1.4.2
* @deprecated this method was made public in error in version 1.4.2 and will be removed without a replacement
*/
@Deprecated
public String uriDecode(final String source) {
public @Nullable String uriDecode(final @Nullable String source) {
return source != null ? percentDecode(source) : null;
}

Expand All @@ -689,7 +693,7 @@ private static byte[] percentEncode(byte b) {
return new byte[] {(byte) PERCENT_CHAR, b1, b2};
}

public static String percentEncode(final String source) {
static String percentEncode(final String source) {
if (source.isEmpty()) {
return source;
}
Expand Down Expand Up @@ -889,10 +893,11 @@ private String encodePath(final String path) {

/**
* 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.
* @deprecated
* This method is no longer recommended and will be removed from a future release.
* the qualifier (querystring).
* This includes equivalence of the scheme, type, namespace, name, and version, but excludes qualifier and subpath
* from evaluation.
*
* @deprecated This method is no longer recommended and will be removed from a future release.
* <p> Use {@link PackageURL#isCoordinatesEquals} instead.</p>
*
* @param purl the Package URL to evaluate
Expand All @@ -907,8 +912,9 @@ public boolean isBaseEquals(final 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.
* the qualifier (querystring).
* This includes equivalence of the scheme, type, namespace, name, and version, but excludes qualifier and subpath
* from evaluation.
*
* @param purl the Package URL to evaluate, not {@code null}
* @return true if equivalence passes, false if not
Expand Down Expand Up @@ -973,43 +979,199 @@ public int hashCode() {
* @since 1.0.0
*/
public static final class StandardTypes {
/**
* Arch Linux and other users of the libalpm/pacman package manager.
*
* @since 1.6.0
*/
public static final String ALPM = "alpm";
/**
* APK-based packages.
*
* @since 1.6.0
*/
public static final String APK = "apk";
/**
* Bitbucket-based packages.
*/
public static final String BITBUCKET = "bitbucket";
/**
* Bitnami-based packages.
*
* @since 1.6.0
*/
public static final String BITNAMI = "bitnami";
/**
* Rust.
*
* @since 1.2.0
*/
public static final String CARGO = "cargo";
/**
* CocoaPods.
*
* @since 1.6.0
*/
public static final String COCOAPODS = "cocoapods";
/**
* Composer PHP packages.
*/
public static final String COMPOSER = "composer";
/**
* Conan C/C++ packages.
*
* @since 1.6.0
*/
public static final String CONAN = "conan";
/**
* Conda packages.
*
* @since 1.6.0
*/
public static final String CONDA = "conda";
/**
* CPAN Perl packages.
*
* @since 1.6.0
*/
public static final String CPAN = "cpan";
/**
* CRAN R packages.
*
* @since 1.6.0
*/
public static final String CRAN = "cran";
/**
* Debian, Debian derivatives, and Ubuntu packages.
*
* @since 1.6.0
*/
public static final String DEB = "deb";
/**
* Docker images.
*/
public static final String DOCKER = "docker";
/**
* RubyGems.
*/
public static final String GEM = "gem";
/**
* Plain, generic packages that do not fit anywhere else, such as for "upstream-from-distro" packages.
*/
public static final String GENERIC = "generic";
/**
* GitHub-based packages.
*/
public static final String GITHUB = "github";
/**
* Go packages.
*/
public static final String GOLANG = "golang";
/**
* Haskell packages.
*/
public static final String HACKAGE = "hackage";
/**
* Hex packages.
*
* @since 1.6.0
*/
public static final String HEX = "hex";
/**
* Hugging Face ML models.
*
* @since 1.6.0
*/
public static final String HUGGINGFACE = "huggingface";
/**
* Lua packages installed with LuaRocks.
*
* @since 1.6.0
*/
public static final String LUAROCKS = "luarocks";
/**
* Maven JARs and related artifacts.
*
* @since 1.0.0
*/
public static final String MAVEN = "maven";
/**
* MLflow ML models (Azure ML, Databricks, etc.).
*
* @since 1.6.0
*/
public static final String MLFLOW = "mlflow";
/**
* Nixos packages
*
* @since 1.6.0
*/
public static final String NIX = "nix";
/**
* Node NPM packages.
*
* @since 1.0.0
*/
public static final String NPM = "npm";
/**
* NuGet .NET packages.
*
* @since 1.0.0
*/
public static final String NUGET = "nuget";
/**
* All artifacts stored in registries that conform to the
* <a href="https://github.com/opencontainers/distribution-spec">OCI Distribution Specification</a>, including
* container images built by Docker and others.
*
* @since 1.6.0
*/
public static final String OCI = "oci";
/**
* Dart and Flutter packages.
*
* @since 1.6.0
*/
public static final String PUB = "pub";
/**
* Python packages.
*/
public static final String PYPI = "pypi";
/**
* QNX packages.
*
* @since 1.6.0
*/
public static final String QPKG = "qpkg";
/**
* RPMs.
*/
public static final String RPM = "rpm";
/**
* ISO-IEC 19770-2 Software Identification (SWID) tags.
*
* @since 1.6.0
*/
public static final String SWID = "swid";
/**
* Swift packages.
*
* @since 1.6.0
*/
public static final String SWIFT = "swift";

/**
* Debian, Debian derivatives, and Ubuntu packages.
*
* @deprecated use {@link #DEB} instead
*/
@Deprecated
public static final String DEBIAN = "deb";

/**
* Nixos packages.
*
* @since 1.1.0
* @deprecated use {@link #NIX} instead
*/
@Deprecated
public static final String NIXPKGS = "nix";

Expand Down
Loading