| /* |
| * Copyright (c) 2014, 2025, 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> |
| * |
| * The ZIP file system provider does not support opening an existing ZIP file |
| * that contains entries with "." or ".." in its name elements. |
| * |
| * <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">accessMode</th> |
| * <td>{@link java.lang.String}</td> |
| * <td>null/unset</td> |
| * <td> |
| * A value defining the desired access mode of the file system. |
| * ZIP file systems can be created to allow for <em>read-write</em> or |
| * <em>read-only</em> access. |
| * <ul> |
| * <li> |
| * If no value is set, the file system is created as <em>read-write</em> |
| * if possible. Use {@link java.nio.file.FileSystem#isReadOnly() |
| * isReadOnly()} to determine the actual access mode. |
| * </li> |
| * <li> |
| * If the value is {@code "readOnly"}, the file system is created |
| * <em>read-only</em>, and {@link java.nio.file.FileSystem#isReadOnly() |
| * isReadOnly()} will always return {@code true}. Creating a |
| * <em>read-only</em> file system requires the underlying ZIP file to |
| * already exist. |
| * </li> |
| * <li> |
| * If the value is {@code "readWrite"}, the file system is created |
| * <em>read-write</em>, and {@link java.nio.file.FileSystem#isReadOnly() |
| * isReadOnly()} will always return {@code false}. If a writable file |
| * system cannot be created, an {@code IOException} will be thrown |
| * when creating the ZIP file system. |
| * </li> |
| * <li> |
| * Any other values will cause an {@code IllegalArgumentException} |
| * to be thrown when creating the ZIP file system. |
| * </li> |
| * </ul> |
| * The {@code accessMode} property has no effect on reported POSIX file |
| * permissions (in cases where POSIX support is enabled). |
| * </td> |
| * </tr> |
| * <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. Specifying the {@code create} |
| * property as {@code true} with the {@code accessMode} as {@code "readOnly"} |
| * will cause an {@code IllegalArgumentException} to be thrown when creating |
| * the ZIP file system. |
| * </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 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 creating the |
| * ZIP file system. |
| * </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 when creating |
| * the ZIP file system. |
| * </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; |
| } |
