/*
* 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.nio.file.attribute.FileAttributeView;
import java.nio.file.attribute.PosixFileAttributes;
import java.nio.file.attribute.PosixFilePermission;
import java.nio.file.attribute.PosixFileAttributeView;
import java.util.Set;
/**
* 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.
*
* <h2>Accessing a Zip File System</h2>
*
* 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>
*
* <h2>URI Scheme Used to Identify the Zip File System</h2>
*
* The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}.
*
* <h2>POSIX file attributes</h2>
*
* A Zip file system supports a file attribute {@link FileAttributeView view}
* named "{@code zip}" that defines the following file attribute:
*
* <blockquote>
* <table class="striped">
* <caption style="display:none">Supported attributes</caption>
* <thead>
* <tr>
* <th scope="col">Name</th>
* <th scope="col">Type</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row">permissions</th>
* <td>{@link Set}<{@link PosixFilePermission}></td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* The "permissions" attribute is the set of access permissions that are optionally
* stored for entries in a Zip file. The value of the attribute is {@code null}
* for entries that do not have access permissions. Zip file systems do not
* enforce access permissions.
*
* <p> The "permissions" attribute may be read and set using the
* {@linkplain Files#getAttribute(Path, String, LinkOption...) Files.getAttribute} and
* {@linkplain Files#setAttribute(Path, String, Object, LinkOption...) Files.setAttribute}
* methods. The following example uses these methods to read and set the attribute:
* <pre> {@code
* Set<PosixFilePermission> perms = Files.getAttribute(entry, "zip:permissions");
* if (perms == null) {
* perms = PosixFilePermissions.fromString("rw-rw-rw-");
* Files.setAttribute(entry, "zip:permissions", perms);
* }
* } </pre>
*
* <p> In addition to the "{@code zip}" view, a Zip file system optionally supports
* the {@link PosixFileAttributeView} ("{@code posix}").
* This view extends the "{@code basic}" view with type safe access to the
* {@link PosixFileAttributes#owner() owner}, {@link PosixFileAttributes#group() group-owner},
* and {@link PosixFileAttributes#permissions() permissions} attributes. The
* "{@code posix}" view is only supported when the Zip file system is created with
* the provider property "{@code enablePosixFileAttributes}" set to "{@code true}".
* The following creates a file system with this property and reads the access
* permissions of a file:
* <pre> {@code
* var env = Map.of("enablePosixFileAttributes", "true");
* try (FileSystem fs = FileSystems.newFileSystem(file, env) {
* Path entry = fs.getPath("entry");
* Set<PosixFilePermission> perms = Files.getPosixFilePermissions(entry);
* }
* } </pre>
*
* <p> The file owner and group owner attributes are not persisted, meaning they are
* not stored in the zip file. The "{@code defaultOwner}" and "{@code defaultGroup}"
* provider properties (listed below) can be used to configure the default values
* for these attributes. If these properties are not set then the file owner
* defaults to the owner of the zip file, and the group owner defaults to the
* zip file's group owner (or the file owner on platforms that don't support a
* group owner).
*
* <p> The "{@code permissions}" attribute is not optional in the "{@code posix}"
* view so a default set of permissions are used for entries that do not have
* access permissions stored in the Zip file. The default set of permissions
* are
* <ul>
* <li>{@link PosixFilePermission#OWNER_READ OWNER_READ}</li>
* <li>{@link PosixFilePermission#OWNER_WRITE OWNER_WRITE}</li>
* <li>{@link PosixFilePermission#GROUP_READ GROUP_READ}</li>
* </ul>
* The default permissions can be configured with the "{@code defaultPermissions}"
* property described below.
*
* <h2>Zip File System Properties</h2>
*
* The following properties may be specified when creating a Zip
* file system:
* <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>
* <th scope="row">create</th>
* <td>{@link java.lang.String} or {@link java.lang.Boolean}</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>
* <th scope="row">encoding</th>
* <td>{@link 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>
* <tr>
* <th scope="row">enablePosixFileAttributes</th>
* <td>{@link java.lang.String} or {@link java.lang.Boolean}</td>
* <td>false</td>
* <td>
* If the value is {@code true}, the Zip file system will support
* the {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView}.
* </td>
* </tr>
* <tr>
* <th scope="row">defaultOwner</th>
* <td>{@link java.nio.file.attribute.UserPrincipal UserPrincipal}<br> or
* {@link java.lang.String}</td>
* <td>null/unset</td>
* <td>
* Override the default owner for entries in the Zip file system.<br>
* The value can be a UserPrincipal or a String value that is used as the UserPrincipal's name.
* </td>
* </tr>
* <tr>
* <th scope="row">defaultGroup</th>
* <td>{@link java.nio.file.attribute.GroupPrincipal GroupPrincipal}<br> or
* {@link java.lang.String}</td>
* <td>null/unset</td>
* <td>
* Override the the default group for entries in the Zip file system.<br>
* The value can be a GroupPrincipal or a String value that is used as the GroupPrincipal's name.
* </td>
* </tr>
* <tr>
* <th scope="row">defaultPermissions</th>
* <td>{@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}><br>
* or {@link java.lang.String}</td>
* <td>null/unset</td>
* <td>
* Override the default Set of permissions for entries in the Zip file system.<br>
* The value can be a {@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}> or<br>
* a String that is parsed by {@link java.nio.file.attribute.PosixFilePermissions#fromString PosixFilePermissions::fromString}
* </td>
* </tr>
* <tr>
* <th scope="row">compressionMethod</th>
* <td>{@link java.lang.String}</td>
* <td>"DEFLATED"</td>
* <td>
* The value representing the compression method to use when writing entries
* to the Zip file system.
* <ul>
* <li>
* If the value is {@code "STORED"}, the Zip file system provider will
* not compress entries when writing to the Zip file system.
* </li>
* <li>
* If the value is {@code "DEFLATED"} or the property is not set,
* the Zip file system provider will use data compression when
* writing entries to the Zip file system.
* </li>
* <li>
* If the value is not {@code "STORED"} or {@code "DEFLATED"}, an
* {@code IllegalArgumentException} will be thrown when the Zip
* filesystem is created.
* </li>
* </ul>
* </td>
* </tr>
* <tr>
* <th scope="row">releaseVersion</th>
* <td>{@link java.lang.String} or {@link java.lang.Integer}</td>
* <td>null/unset</td>
* <td>
* A value representing the version entry to use when accessing a
* <a href=="{@docRoot}/../specs/jar/jar.html#multi-release-jar-files">
* multi-release JAR</a>. If the JAR is not a
* <a href=="{@docRoot}/../specs/jar/jar.html#multi-release-jar-files">
* multi-release JAR</a>, the value will be ignored and the JAR will be
* considered un-versioned.
* <p>
* The value must be either the string "runtime" or represent a valid
* {@linkplain Runtime.Version Java SE Platform version number},
* such as {@code 9} or {@code 14}, in order to determine the version entry.
*
* <ul>
* <li>
* If the value is {@code null} or the property is not set,
* then the JAR will be treated as an un-versioned JAR.
* </li>
* <li>
* If the value is {@code "runtime"}, the
* version entry will be determined by invoking
* {@linkplain Runtime.Version#feature() Runtime.Version.feature()}.
* </li>
* <li>
* If the value does not represent a valid
* {@linkplain Runtime.Version Java SE Platform version number},
* an {@code IllegalArgumentException} will be thrown.
* </li>
* </ul>
* </td>
* </tr>
* </tbody>
* </table>
*
* <h2>Examples:</h2>
*
* 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"));
* Path rootDir = zipfs.getPath("/");
* Files.walk(rootDir)
* .forEach(System.out::println);
* }
* </pre>
* @provides java.nio.file.spi.FileSystemProvider
* @moduleGraph
* @since 9
*/
module jdk.zipfs {
provides java.nio.file.spi.FileSystemProvider with
jdk.nio.zipfs.ZipFileSystemProvider;
}