Summary

The jdk.zipfs module should document how to use the Zip file system to create or access a Zip or JAR file.

Problem

The Zip file system was included in JDK 7 as an example of how to create a custom file system provider. JDK 7 and JDK 8 provided a tech note on how to use the Zip file system:

https://docs.oracle.com/javase/8/docs/technotes/guides/io/fsp/zipfilesystemprovider.html

Unfortunately, the tech note was not carried forward to JDK 9 and beyond.

Starting with JDK 9, the Zip file system provider became an officially supported file system provider. The JDK implementation is contained in the jdk.zipfs module.

Solution

Update the module summary for the jdk.zipfs module to include the information that was provided in the previous Zip file system provider tech note.

Specification

The following additions will be made to the module summary for the jdk.zipfs module:

$ hg diff
diff -r 213a2377b792 src/jdk.zipfs/share/classes/module-info.java
--- a/src/jdk.zipfs/share/classes/module-info.java  Mon Feb 04 11:00:12 2019 +0100
+++ b/src/jdk.zipfs/share/classes/module-info.java  Fri Feb 08 12:36:50 2019 -0500
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -24,14 +24,89 @@
  */

 /**
- * Provides the implementation of the zip file system provider.
+ * Provides the implementation of the Zip file system provider.
+ * The Zip file system provider treats the contents of a Zip or JAR file as a file system.
+ * <p>
  *
- * <p> The zip file system provider treats a zip or JAR file as a file system
- * and provides the ability to manipulate the contents of the file.
- * The zip file system provider can be created by
- * {@link java.nio.file.FileSystems#newFileSystem
- * FileSystems.newFileSystem} if installed.
+ * <h3>Accessing a Zip File System</h3>
  *
+ * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem}
+ * static factory methods can be used to:
+ * <ul>
+ *     <li>Create a Zip file system</li>
+ *     <li>Open an existing file as a Zip file system</li>
+ * </ul>
+ *
+ * <h3>URI Scheme Used to Identify the Zip File System</h3>
+ *
+ * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}.
+ *
+ * <h3>Zip File System Properties</h3>
+ *
+ * The following properties may be specified when creating a Zip
+ * file system:
+ * <p>
+ * <table class="striped">
+ * <caption style="display:none">
+ *     Configurable properties that may be specified when creating
+ *     a new Zip file system
+ * </caption>
+ * <thead>
+ * <tr>
+ * <th scope="col">Property Name</th>
+ * <th scope="col">Data Type</th>
+ * <th scope="col">Default Value</th>
+ * <th scope="col">Description</th>
+ * </tr>
+ * </thead>
+ *
+ * <tbody>
+ * <tr>
+ *   <td scope="row">create</td>
+ *   <td>java.lang.String</td>
+ *   <td>false</td>
+ *   <td>
+ *       If the value is {@code true}, the Zip file system provider
+ *       creates a new Zip or JAR file if it does not exist.
+ *   </td>
+ * </tr>
+ * <tr>
+ *   <td scope="row">encoding</td>
+ *   <td>java.lang.String</td>
+ *   <td>UTF-8</td>
+ *   <td>
+ *       The value indicates the encoding scheme for the
+ *       names of the entries in the Zip or JAR file.
+ *   </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ *
+ * <h3>Examples:</h3>
+ *
+ * Construct a new Zip file system that is identified by a URI.  If the Zip file does not exist,
+ * it will be created:
+ * <pre>
+ * {@code
+ *
+ *     URI uri = URI.create("jar:file:/home/luckydog/tennisTeam.zip");
+ *     Map<String, String> env = Map.of("create", "true");
+ *     FileSystem zipfs = FileSystems.newFileSystem(uri, env);
+ * }
+ * </pre>
+ *
+ * Construct a new Zip file system that is identified by specifying a path
+ * and using automatic file type detection. Iterate from the root of the JAR displaying each
+ * found entry:
+ * <pre>
+ * {@code
+ *
+ *     FileSystem zipfs = FileSystems.newFileSystem(Path.of("helloworld.jar"), null);
+ *     Path rootDir = zipfs.getPath("/");
+ *     Files.walk(rootDir)
+ *            .forEach(System.out::println);
+ * }
+ * </pre>
  * @provides java.nio.file.spi.FileSystemProvider
  * @moduleGraph
  * @since 9
$