RFR 8182117 : Document Zip File System Properties

Lance Andersen lance.andersen at oracle.com
Mon Feb 4 19:36:38 UTC 2019 

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 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()> 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 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