Add deprecation documentation to Archive.iterator

See gh-16655

Author: philwebb

spring-boot-project/spring-boot-tools/spring-boot-loader/src/main/java/org/springframework/boot/loader/archive/Archive.java

@@ -79,6 +79,13 @@ default List<Archive> getNestedArchives(EntryFilter filter) throws IOException {
 		throw new IllegalStateException("Unexpected call to getNestedArchives(filter)");
 	}
 
+	/**
+	 * Return a new iterator for the archive entries.
+	 * @see java.lang.Iterable#iterator()
+	 * @deprecated since 2.3.0 in favor of using
+	 * {@link org.springframework.boot.loader.jar.JarFile} to access entries and
+	 * {@link #getNestedArchives(EntryFilter, EntryFilter)} for accessing nested archives.
+	 */
 	@Deprecated
 	@Override
 	Iterator<Entry> iterator();

spring-boot-project/spring-boot-tools/spring-boot-loader/src/test/java/org/springframework/boot/loader/archive/JarFileArchiveTests.java

@@ -36,6 +36,7 @@
 
 import org.springframework.boot.loader.TestJarCreator;
 import org.springframework.boot.loader.archive.Archive.Entry;
+import org.springframework.boot.loader.jar.JarFile;
 import org.springframework.util.FileCopyUtils;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -171,13 +172,13 @@ void nestedZip64ArchivesAreHandledGracefully() throws Exception {
 			output.write(zip64JarData);
 			output.closeEntry();
 		}
-		try (JarFileArchive jarFileArchive = new JarFileArchive(file);
-				Archive nestedArchive = jarFileArchive
-						.getNestedArchive(getEntriesMap(jarFileArchive).get("nested/zip64.jar"))) {
-			Iterator<Entry> it = nestedArchive.iterator();
+		try (JarFile jarFile = new JarFile(file)) {
+			ZipEntry nestedEntry = jarFile.getEntry("nested/zip64.jar");
+			JarFile nestedJarFile = jarFile.getNestedJarFile(nestedEntry);
+			Iterator<JarEntry> iterator = nestedJarFile.iterator();
 			for (int i = 0; i < 65537; i++) {
-				assertThat(it.hasNext()).as(i + "nth file is present").isTrue();
-				it.next();
+				assertThat(iterator.hasNext()).as(i + "nth file is present").isTrue();
+				iterator.next();
 			}
 		}
 	}