/* * 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. */ /** * 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. *

* *

Accessing a Zip File System

* * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem} * static factory methods can be used to: * * *

URI Scheme Used to Identify the Zip File System

* * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}. * *

Support for POSIX file permissions

* * A Zip file system supports POSIX permissions.
*
* A Zip file system that was created with default properties supports the attribute "{@code permissions}". * The value of the attribute will be of type * {@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}>. * As POSIX permission data is optional in Zip files, its value can be {@code null} for a file. * This means, no permission information is stored in the corresponding Zip entry. Files that are newly * created in a Zip file system will by default have no POSIX permission data.
*
* For extended POSIX support, allowing to use * {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView} and taking advantage * of {@link java.nio.file.Files#setPosixFilePermissions Files::setPosixFilePermissions} * or {@link java.nio.file.Files#getPosixFilePermissions Files::getPosixFilePermissions}, * a Zip file system can be created with the property "{@code enablePosixFileAttributes}" * set to {@code true}. Owner, group and permissions will then be initialized with default values. * If the file system that hosts the Zip file supports retrieving file owners, the default owner of * files inside the Zip file system will be the owner of the Zip file itself. Otherwise, * the default owner will be a {@link java.nio.file.attribute.UserPrincipal UserPrincipal} * with its name set to the value of {@code System.getProperty("user.name")}. * Analogously, if the file system that hosts the Zip file supports retrieving a file's group, * the default group of files inside the Zip file system will be the group of the Zip file itself. * Otherwise, the default group will be a {@link java.nio.file.attribute.GroupPrincipal GroupPrincipal} * with its name set to the value of the file owner's name. * The default {@link java.util.Set Set} of permissions for cases when no permission data * is associated with a Zip file entry will contain the permissions * {@link java.nio.file.attribute.PosixFilePermission#OWNER_READ OWNER_READ}, * {@link java.nio.file.attribute.PosixFilePermission#OWNER_WRITE OWNER_WRITE} and * {@link java.nio.file.attribute.PosixFilePermission#GROUP_READ GROUP_READ}. * It is possible to override these defaults using properties as specified below. * Owner, group and permission attributes can be modified for files hosted by a Zip file system. However, * owner and group information are not persisted. Files that are newly * created in a Zip file system will by default have no POSIX permission data, although default permissions * are returned for the attribute "{@code permissions}". * *

Zip File System Properties

* * The following properties may be specified when creating a Zip * file system: *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Configurable properties that may be specified when creating * a new Zip file system *
Property NameData TypeDefault ValueDescription
createjava.lang.Stringfalse * If the value is {@code true}, the Zip file system provider * creates a new Zip or JAR file if it does not exist. *
encodingjava.lang.StringUTF-8 * The value indicates the encoding scheme for the * names of the entries in the Zip or JAR file. *
enablePosixFileAttributesjava.lang.Stringfalse * If the value is {@code true}, the created Zip file system will support * the {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView}. *
defaultOwner{@link java.nio.file.attribute.UserPrincipal UserPrincipal} or java.lang.Stringnull/unset * Override the default owner for entries in the Zip file system. * The value can be a UserPrincipal or a String value that is used as the UserPrincipal's name. *
defaultGroup{@link java.nio.file.attribute.GroupPrincipal GroupPrincipal} or java.lang.Stringnull/unset * Override the the default group for entries in the Zip file system. * The value can be a GroupPrincipal or a String value that is used as the GroupPrincipal's name. *
defaultPermissions{@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}> * or java.lang.Stringnull/unset * Override the default Set of permissions for entries in the Zip file system. * The value can be a Set<PosixFilePermission> or a String that is parsed by * {@link java.nio.file.attribute.PosixFilePermissions#fromString PosixFilePermissions.fromString} *
* *

Examples:

* * Construct a new Zip file system that is identified by a URI. If the Zip file does not exist, * it will be created: * 
 * {@code
 *
 *     URI uri = URI.create("jar:file:/home/luckydog/tennisTeam.zip");
 *     Map 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: * 
 * {@code
 *
 *     FileSystem zipfs = FileSystems.newFileSystem(Path.of("helloworld.jar"), null);
 *     Path rootDir = zipfs.getPath("/");
 *     Files.walk(rootDir)
 *            .forEach(System.out::println);
 * }
 *
* @provides java.nio.file.spi.FileSystemProvider * @moduleGraph * @since 9 */ module jdk.zipfs { provides java.nio.file.spi.FileSystemProvider with jdk.nio.zipfs.ZipFileSystemProvider; }