RFR 8182117 : Document Zip File System Properties
Lance Andersen
lance.andersen at oracle.com
Tue Feb 5 21:45:09 UTC 2019
Thank you for the feedback. Please see below
> On Feb 5, 2019, at 3:31 AM, Alan Bateman <Alan.Bateman at oracle.com> wrote:
>
> A few comments
>
> On 04/02/2019 19:36, Lance Andersen wrote:
>> :
>>
>> + * The Zip file system provider treats a Zip or JAR file as a file system
>> + * providing the ability to manipulate its contents.
> It might be a bit clearer to reduce this to: "The Zip file system provider treats the contents of a Zip or JAR file as a file system”.
OK
>
>
>
>> *
>> + * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem}
>> + * static factory methods can be used to create a new Zip file system or to
>> + * obtain a reference to an existing Zip file system.
> or "can be used to create a zip file system or open an existing file as a zip file system”.
OK
>
>
>> + *
>> + * FileSystem zipfs = FileSystems.newFileSystem(
>> + * Paths.get("tennisteam.jar"), null);
> You can change this to use Path.of, also might be nice to remove the line break so it's all on one line.
done. I broke it onto multiple lines so it was not too long, but reversed that per your request
>
>> + * Files.walk(zipfs.getPath("/"))
>> + * .forEach(System.out::println);
>>
> For clarity it might be better to create a variable, say top, for the root directory of the zip file system. The main thing that the reader needs to understand is that the file system is the factory to create paths to files in that file system.
Done:
——————
Module jdk.zipfs
<>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.
Accessing a Zip File System
The FileSystems <applewebdata://77B1CB4A-B501-47CC-8295-91C1020BCEC3/java.base/java/nio/file/FileSystems.html> newFileSystem static factory methods can be used to:
Create a Zip file system
Open an existing file as a Zip file system
URI Scheme Used to Identity the Zip File System
The URI scheme <applewebdata://77B1CB4A-B501-47CC-8295-91C1020BCEC3/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(Path.of("helloworld.jar"), null);
Path rootDir = zipfs.getPath("/");
Files.walk(rootDir)
.forEach(System.out::println);
Since:
9
————————
And the diff is:
—————
$ 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 Tue Feb 05 16:43:25 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 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(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
$
--------------
>
> -Alan
>
<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 at oracle.com <mailto:Lance.Andersen at oracle.com>
More information about the core-libs-dev
mailing list