RFR 8182117 : Document Zip File System Properties
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. + * <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} + * static factory methods to create a new Zip file system or to obtain a reference to an + * 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>
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>
Hi Roger, I made the suggested changes, thank you for the input ————— $ 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 Mon Feb 04 14:34:13 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 its 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> * + * 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. + * + * <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 $ ---------------
On Feb 4, 2019, at 1:50 PM, Roger Riggs <Roger.Riggs@oracle.com> wrote:
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>
<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>
Looks good. Thanks, Roger On 02/04/2019 02:36 PM, Lance Andersen wrote:
Hi Roger,
I made the suggested changes, thank you for the input
————— $ hg diff diff -r 213a2377b792 src/jdk.zipfs/share/classes/module-info.java --- a/src/jdk.zipfs/share/classes/module-info.javaMon Feb 04 11:00:12 2019 +0100 +++ b/src/jdk.zipfs/share/classes/module-info.javaMon Feb 04 14:34:13 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 its 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> * + * 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. + * + * <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 $ ---------------
On Feb 4, 2019, at 1:50 PM, Roger Riggs <Roger.Riggs@oracle.com <mailto:Roger.Riggs@oracle.com>> wrote:
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() <applewebdata://0B307EB5-DECC-44DF-8927-3891049153F4/java.base/java/net/URI.html#getScheme%28%29>> 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 NameData TypeDefault ValueDescription createjava.lang.StringfalseIf the value is true, the Zip file system provider creates a new Zip or JAR file if it does not exist. encodingjava.lang.StringUTF-8The 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.javaSun Jan 27 14:55:57 2019 -0500 +++ b/src/jdk.zipfs/share/classes/module-info.javaMon 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> <mailto:Lance.Andersen@oracle.com>
<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>
This looks good. Sherman added a comment on "encoding" which he thinks it may be downloaded as undocumented. You may want to create a JBS issue to revisit that in the future. thanks Mandy On 2/4/19 11:36 AM, Lance Andersen wrote:
Hi Roger,
I made the suggested changes, thank you for the input
————— $ 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 Mon Feb 04 14:34:13 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 its 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> * + * 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. + * + * <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 $ ---------------
On Feb 4, 2019, at 1:50 PM, Roger Riggs <Roger.Riggs@oracle.com> wrote:
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>
<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>
On 04/02/2019 21:44, Mandy Chung wrote:
This looks good.
Sherman added a comment on "encoding" which he thinks it may be downloaded as undocumented. You may want to create a JBS issue to revisit that in the future. Lance asked me a few days ago about this and given that Zip files can be cp437 or UTF-8 then documenting how to specify the coding when opening the Zip or JAR file seems okay.
-Alan
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".
* + * 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".
+ * + * 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.
+ * 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. -Alan
Hi Lance, Alan, Overall looks good to me.
A few comments
+ * 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".
+1
* + * 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".
Here I think Lance's point is what would happen when a FileSystem instance for a particular zip file would already exist and a call to newFileSystem would throw a FileSystemAlreadyExistsException. In that case you need to call getFileSystem. So maybe this sentence should be reworked to cover everything?
+ * + * 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.
+ * 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.
+1 I'm also wondering, whether we should mention how the FileSystemProvider instance can be resolved (e.g. iterating FileSystemProvider.installedProviders(), checking for scheme "jar")? Not quite sure... Best regards Christoph
Hi Christoph Thank you for the feedback, Please see below
On Feb 5, 2019, at 11:22 AM, Langer, Christoph <christoph.langer@sap.com> wrote:
* + * 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".
Here I think Lance's point is what would happen when a FileSystem instance for a particular zip file would already exist and a call to newFileSystem would throw a FileSystemAlreadyExistsException. In that case you need to call getFileSystem. So maybe this sentence should be reworked to cover everything?
This only appears to be the case when using a URI not a Path, so for now I suggest we leave it as is based on the last changes
I'm also wondering, whether we should mention how the FileSystemProvider instance can be resolved (e.g. iterating FileSystemProvider.installedProviders(), checking for scheme "jar")? Not quite sure…
I had included that originally, but Alan and I discussed that off line prior to the original RFR and we decided it was not needed for the average developer so I removed it prior to the RFR. Best Lance
Best regards Christoph
<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>
Thank you for the feedback. Please see below
On Feb 5, 2019, at 3:31 AM, Alan Bateman <Alan.Bateman@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@oracle.com <mailto:Lance.Andersen@oracle.com>
On 05/02/2019 21:45, Lance Andersen wrote:
Thank you for the feedback. Please see below The updated version that you attached looks okay to me.
-Alan
+1
-----Original Message----- From: core-libs-dev <core-libs-dev-bounces@openjdk.java.net> On Behalf Of Alan Bateman Sent: Mittwoch, 6. Februar 2019 10:09 To: Lance Andersen <lance.andersen@oracle.com> Cc: core-libs-dev@openjdk.java.net Subject: Re: RFR 8182117 : Document Zip File System Properties
On 05/02/2019 21:45, Lance Andersen wrote:
Thank you for the feedback. Please see below The updated version that you attached looks okay to me.
-Alan
Hi Lance, I found a small nit (hopefully right in time before pushing): + * <h3>URI Scheme Used to Identity the Zip File System</h3> should probably be: + * <h3>URI Scheme Used to Identify the Zip File System</h3> (Identify instead of Identity) Thanks Christoph
Thank you for catching that Christoph, sometimes you see what you want to see :-) I will tweak that prior to the push once the CSR is approved Thank you and have a good weekend
On Feb 8, 2019, at 8:56 AM, Langer, Christoph <christoph.langer@sap.com> wrote:
Hi Lance,
I found a small nit (hopefully right in time before pushing):
+ * <h3>URI Scheme Used to Identity the Zip File System</h3>
should probably be:
+ * <h3>URI Scheme Used to Identify the Zip File System</h3>
(Identify instead of Identity)
Thanks Christoph
<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>
participants (5)
-
Alan Bateman
-
Lance Andersen
-
Langer, Christoph
-
Mandy Chung
-
Roger Riggs