RFR 8182117 : Document Zip File System Properties
Roger Riggs
Roger.Riggs at oracle.com
Mon Feb 4 19:38:16 UTC 2019
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 at oracle.com
>> <mailto:Roger.Riggs at 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/zipfilesystemprovider.html.
>>>
>>> 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 at oracle.com <mailto:Lance.Andersen at oracle.com>
>>> <mailto:Lance.Andersen at 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 at oracle.com <mailto:Lance.Andersen at oracle.com>
>
>
>
More information about the core-libs-dev
mailing list