Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8218572

jdk.zipfs should document the "create" and "encoding" properties

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 13
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      The update simply clarifies how to use the Zip File System therefore there is no compatibility issue.
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      Summary

      The jdk.zipfs module should document how to use the Zip file system to create or access a Zip or JAR file.

      Problem

      The Zip file system was included in JDK 7 as an example of how to create a custom file system provider. JDK 7 and JDK 8 provided a tech note on how to use the Zip file system:

      https://docs.oracle.com/javase/8/docs/technotes/guides/io/fsp/zipfilesystemprovider.html

      Unfortunately, the tech note was not carried forward to JDK 9 and beyond.

      Starting with JDK 9, the Zip file system provider became an officially supported file system provider. The JDK implementation is contained in the jdk.zipfs module.

      Solution

      Update the module summary for the jdk.zipfs module to include the information that was provided in the previous Zip file system provider tech note.

      Specification

      The following additions will be made to the module summary for the jdk.zipfs module:

      $ 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  Fri Feb 08 12:36: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,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 Identify 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
      $

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                lancea Lance Andersen
                Reporter:
                mchung Mandy Chung
                Reviewed By:
                Alan Bateman, Christoph Langer, Mandy Chung
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: