301 lines
12 KiB
Java
301 lines
12 KiB
Java
/*
|
|
* 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;
|
|
}
|