Hi Lance, That looks ok; editorial suggestions below: On 02/04/2019 12:40 PM, Lance Andersen wrote:
Hi all
Please review the fix for https://bugs.openjdk.java.net/browse/JDK-8182117 <https://bugs.openjdk.java.net/browse/JDK-8182117> which addresses the need to document the Zip File System properties and is also replacing the documentation that used to exist in the tech note: https://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/zipfilesystemp....
The updated documentation can be seen below followed by the diff of the changes.
——————— Module jdk.zipfs
<>Provides the implementation of the Zip file system provider. The Zip file system provider treats a Zip or JAR file as a file system providing the ability to manipulate the contents of the file.
Accessing a Zip File System
You can use the FileSystems <applewebdata://0B307EB5-DECC-44DF-8927-3891049153F4/java.base/java/nio/file/FileSystems.html> newFileSystem static factory methods to create a new Zip file system or to obtain a reference to an existing Zip file system. URI Scheme Used to Identity the Zip File System
The URI scheme <applewebdata://0B307EB5-DECC-44DF-8927-3891049153F4/java.base/java/net/URI.html#getScheme()> that identifies the ZIP file system is jar. Zip File System Properties
The following properties may be specified when creating a Zip file system:
Property Name Data Type Default Value Description create java.lang.String false If the value is true, the Zip file system provider creates a new Zip or JAR file if it does not exist. encoding java.lang.String UTF-8 The value indicates the encoding scheme for the names of the entries in the Zip or JAR file. Examples:
Construct a new Zip file system that is identified by a URI. If the Zip file does not exist, it will be created:
URI uri = URI.create("jar:file:/home/luckydog/tennisTeam.zip"); Map<String, String> env = Map.of("create", "true"); FileSystem zipfs = FileSystems.newFileSystem(uri, env);
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:
FileSystem zipfs = FileSystems.newFileSystem( Paths.get("tennisteam.jar"), null); Files.walk(zipfs.getPath("/")) .forEach(System.out::println);
Since: 9
——————————
Here is the actual diff:
——————— $ hg diff diff -r cd310319fead src/jdk.zipfs/share/classes/module-info.java --- a/src/jdk.zipfs/share/classes/module-info.java Sun Jan 27 14:55:57 2019 -0500 +++ b/src/jdk.zipfs/share/classes/module-info.java Mon Feb 04 12:30: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,87 @@ */
/** - * Provides the implementation of the zip file system provider. + * Provides the implementation of the Zip file system provider. + * The Zip file system provider treats a Zip or JAR file as a file system + * providing the ability to manipulate the contents of the file. Remove " of the file" so it reads: "providing the ability to manipulate the contents. " + * <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> * + * You can use the {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem} Third person seems more appropriate:
+ * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem}
+ * static factory methods ^^ to create a new Zip file system or to obtain a reference to an can be used + * existing Zip file system. + * + * <h3>URI Scheme Used to Identity 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( + * Paths.get("tennisteam.jar"), null); + * Files.walk(zipfs.getPath("/")) + * .forEach(System.out::println); + * } + * </pre> * @provides java.nio.file.spi.FileSystemProvider * @moduleGraph * @since 9 $ -------------------- <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 Lance.Andersen@oracle.com <mailto:Lance.Andersen@oracle.com>