Summary

java.util.jar.JarEntry.getCodeSigners() and JarEntry.getCertificates() have been updated to specify that they return a new array each time these methods are invoked when a non-null value is returned.

Problem

The implementation of JarEntry.getCodeSigners() and getCertificates() both return a copy of the original array. However, the current API documentation does not specify this behavior. This prevents subclasses and applications from relying on the behavior, and has resulted in redundant cloning in some subclasses.

Solution

Clarify the API specification of both methods to state explicitly that they return a new array each time they are invoked when a non-null value is returned. This ensures callers understand that modifying the returned array does not modify the internal state of the JarEntry.

Specification

diff --git a/src/java.base/share/classes/java/util/jar/JarEntry.java b/src/java.base/share/classes/java/util/jar/JarEntry.java
index ff0750a3342a3..33c8781043581 100644
--- a/src/java.base/share/classes/java/util/jar/JarEntry.java
+++ b/src/java.base/share/classes/java/util/jar/JarEntry.java

@@ -115,7 +115,8 @@ public Attributes getAttributes() throws IOException {
      * to trust the entry signed by the signers.
      *
      * @return the {@code Certificate} objects for this entry, or
-     * {@code null} if none.
+     * {@code null} if none. If non-null, returns a new array
+     * each time it is invoked.
      *
      */
     public Certificate[] getCertificates() {
@@ -140,7 +141,8 @@ public Certificate[] getCertificates() {
      * to trust the entry signed by the signers.
      *
      * @return the {@code CodeSigner} objects for this entry, or
-     * {@code null} if none.
+     * {@code null} if none. If non-null, returns a new array
+     * each time it is invoked.
      *
      * @since 1.5
      */