You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by gn...@apache.org on 2026/09/30 13:06:46 UTC
(maven-archiver) branch master updated: docs: document null-value behaviour in manifest entry methods
This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-archiver.git
The following commit(s) were added to refs/heads/master by this push:
new e7aefb3 docs: document null-value behaviour in manifest entry methods
e7aefb3 is described below
commit e7aefb3badd8c5a5fe591b36a30136cc05c1c984
Author: Guillaume Nodet <gn...@gmail.com>
AuthorDate: Wed Sep 30 15:06:40 2026 +0200
docs: document null-value behaviour in manifest entry methods
- Document that null values passed to setManifestEntries,
addManifestEntry, addManifestEntries, and getManifestEntries are
accepted and converted to empty strings, and add @param/@return
Javadoc for those methods on both Manifest and ManifestSection
- Apply Javadoc style fixes: present tense ('produces' over 'will
produce'), periods instead of semicolons in @param sentences
Fixes #374
---
.../maven/shared/archiver/ManifestSection.java | 25 ++++++++++++----
.../shared/archiver/MavenArchiveConfiguration.java | 35 +++++++++++++++++-----
.../maven/shared/archiver/MavenArchiver.java | 13 ++++++++
3 files changed, 59 insertions(+), 14 deletions(-)
diff --git a/src/main/java/org/apache/maven/shared/archiver/ManifestSection.java b/src/main/java/org/apache/maven/shared/archiver/ManifestSection.java
index f4a98ff..cf24ae6 100644
--- a/src/main/java/org/apache/maven/shared/archiver/ManifestSection.java
+++ b/src/main/java/org/apache/maven/shared/archiver/ManifestSection.java
@@ -31,17 +31,25 @@ public class ManifestSection {
private final Map<String, String> manifestEntries = new LinkedHashMap<>();
/**
- * <p>addManifestEntry.</p>
+ * Adds a single manifest entry.
*
- * @param key the key of the manifest entry
- * @param value the appropriate value
+ * <p>A {@code null} value is accepted and produces an empty-string attribute in the manifest.
+ * This is intentional: it allows callers to explicitly request an empty manifest entry.
+ * Be careful not to pass {@code null} unintentionally (e.g., from an unguarded map lookup),
+ * as the resulting empty attribute will not indicate any error.</p>
+ *
+ * @param key the manifest attribute name
+ * @param value the manifest attribute value; {@code null} is treated as an empty string
*/
public void addManifestEntry(String key, String value) {
manifestEntries.put(key, value);
}
/**
- * <p>Getter for the field <code>manifestEntries</code>.</p>
+ * Returns the manifest entries map.
+ *
+ * <p>Values in the returned map may be {@code null}. Such entries are treated as empty strings
+ * when written to the manifest.</p>
*
* @return the entries
*/
@@ -68,9 +76,14 @@ public class ManifestSection {
}
/**
- * <p>addManifestEntries.</p>
+ * Adds all entries from the given map as manifest attributes.
+ *
+ * <p>A {@code null} value in the map is accepted and produces an empty-string attribute
+ * in the manifest. This is intentional: it allows callers to explicitly request an empty
+ * manifest entry. Be careful not to pass {@code null} values unintentionally, as they will
+ * not indicate any error.</p>
*
- * @param map the map to add
+ * @param map the manifest entries to add. Map values may be {@code null}, which are treated as empty strings
*/
public void addManifestEntries(Map<String, String> map) {
manifestEntries.putAll(map);
diff --git a/src/main/java/org/apache/maven/shared/archiver/MavenArchiveConfiguration.java b/src/main/java/org/apache/maven/shared/archiver/MavenArchiveConfiguration.java
index 70593fc..4f94f0e 100644
--- a/src/main/java/org/apache/maven/shared/archiver/MavenArchiveConfiguration.java
+++ b/src/main/java/org/apache/maven/shared/archiver/MavenArchiveConfiguration.java
@@ -152,19 +152,29 @@ public class MavenArchiveConfiguration {
}
/**
- * <p>addManifestEntry.</p>
+ * Adds a single manifest entry.
*
- * @param key the key of the entry
- * @param value the value of the entry
+ * <p>A {@code null} value is accepted and produces an empty-string attribute in the manifest.
+ * This is intentional: it allows callers to explicitly request an empty manifest entry.
+ * Be careful not to pass {@code null} unintentionally (e.g., from an unguarded map lookup),
+ * as the resulting empty attribute will not indicate any error.</p>
+ *
+ * @param key the manifest attribute name
+ * @param value the manifest attribute value; {@code null} is treated as an empty string
*/
public void addManifestEntry(String key, String value) {
manifestEntries.put(key, value);
}
/**
- * <p>addManifestEntries.</p>
+ * Adds all entries from the given map as manifest attributes.
+ *
+ * <p>A {@code null} value in the map is accepted and produces an empty-string attribute
+ * in the manifest. This is intentional: it allows callers to explicitly request an empty
+ * manifest entry. Be careful not to pass {@code null} values unintentionally, as they will
+ * not indicate any error.</p>
*
- * @param map the whole map which should be added
+ * @param map the manifest entries to add. Map values may be {@code null}, which are treated as empty strings
*/
public void addManifestEntries(Map<String, String> map) {
manifestEntries.putAll(map);
@@ -180,7 +190,10 @@ public class MavenArchiveConfiguration {
}
/**
- * <p>Getter for the field <code>manifestEntries</code>.</p>
+ * Returns the manifest entries map.
+ *
+ * <p>Values in the returned map may be {@code null}. Such entries are treated as empty strings
+ * when written to the manifest.</p>
*
* @return {@link #manifestEntries}
*/
@@ -189,9 +202,15 @@ public class MavenArchiveConfiguration {
}
/**
- * <p>Setter for the field <code>manifestEntries</code>.</p>
+ * Sets the manifest entries map, replacing any previously configured entries.
+ *
+ * <p>The map may contain {@code null} values. A {@code null} value is treated as an empty string
+ * when the manifest is written, producing an empty attribute for that key. This is intentional
+ * behaviour — but be careful not to pass {@code null} values unintentionally (e.g., from an
+ * unguarded map lookup), as they will be silently accepted and produce an empty manifest entry
+ * with no error.</p>
*
- * @param manifestEntries {@link #manifestEntries}
+ * @param manifestEntries the manifest entries. Map values may be {@code null}
*/
public void setManifestEntries(Map<String, String> manifestEntries) {
this.manifestEntries = manifestEntries;
diff --git a/src/main/java/org/apache/maven/shared/archiver/MavenArchiver.java b/src/main/java/org/apache/maven/shared/archiver/MavenArchiver.java
index c8ac2b2..6f97e1f 100644
--- a/src/main/java/org/apache/maven/shared/archiver/MavenArchiver.java
+++ b/src/main/java/org/apache/maven/shared/archiver/MavenArchiver.java
@@ -214,6 +214,19 @@ public class MavenArchiver {
manifest.addConfiguredAttribute(attr);
}
+ /**
+ * Sanitizes a manifest attribute value for safe inclusion in the manifest.
+ *
+ * <ul>
+ * <li>A {@code null} value is converted to an empty string. This is intentional and allows
+ * callers to produce empty manifest attributes explicitly.</li>
+ * <li>Embedded CR+LF, CR, or LF characters are replaced with spaces, as multi-line values
+ * are not valid in a manifest attribute.</li>
+ * </ul>
+ *
+ * @param value the raw attribute value; may be {@code null}
+ * @return the sanitized value, never {@code null}
+ */
private static String sanitizeManifestValue(String value) {
if (value == null) {
return "";