1 /* 2 * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /** 27 * Provides the implementation of the Zip file system provider. 28 * The Zip file system provider treats the contents of a Zip or JAR file as a file system. 29 * <p> 30 * 31 * <h3>Accessing a Zip File System</h3> 32 * 33 * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem} 34 * static factory methods can be used to: 35 * <ul> 36 * <li>Create a Zip file system</li> 37 * <li>Open an existing file as a Zip file system</li> 38 * </ul> 39 * 40 * <h3>URI Scheme Used to Identify the Zip File System</h3> 41 * 42 * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}. 43 * 44 * <h3>Support for POSIX file permissions</h3> 45 * 46 * A Zip file system supports POSIX permissions.<br> 47 * <br> 48 * A Zip file system that was created with default properties supports the attribute "{@code permissions}". 49 * The value of the attribute will be of type 50 * {@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}>. 51 * As POSIX permission data is optional in Zip files, its value can be {@code null} for a file. 52 * This means, no permission information is stored in the corresponding Zip entry. Files that are newly 53 * created in a Zip file system will by default have no POSIX permission data.<br> 54 * <br> 55 * For extended POSIX support, allowing to use 56 * {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView} and taking advantage 57 * of {@link java.nio.file.Files#setPosixFilePermissions Files::setPosixFilePermissions} 58 * or {@link java.nio.file.Files#getPosixFilePermissions Files::getPosixFilePermissions}, 59 * a Zip file system can be created with the property "{@code enablePosixFileAttributes}" 60 * set to {@code true}. Owner, group and permissions will then be initialized with default values. 61 * If the file system that hosts the Zip file supports retrieving file owners, the default owner of 62 * files inside the Zip file system will be the owner of the Zip file itself. Otherwise, 63 * the default owner will be a {@link java.nio.file.attribute.UserPrincipal UserPrincipal} 64 * with its name set to the value of {@code System.getProperty("user.name")}. 65 * Analogously, if the file system that hosts the Zip file supports retrieving a file's group, 66 * the default group of files inside the Zip file system will be the group of the Zip file itself. 67 * Otherwise, the default group will be a {@link java.nio.file.attribute.GroupPrincipal GroupPrincipal} 68 * with its name set to the value of the file owner's name. 69 * The default {@link java.util.Set Set} of permissions for cases when no permission data 70 * is associated with a Zip file entry will contain the permissions 71 * {@link java.nio.file.attribute.PosixFilePermission#OWNER_READ OWNER_READ}, 72 * {@link java.nio.file.attribute.PosixFilePermission#OWNER_WRITE OWNER_WRITE} and 73 * {@link java.nio.file.attribute.PosixFilePermission#GROUP_READ GROUP_READ}. 74 * It is possible to override these defaults using properties as specified below. 75 * Owner, group and permission attributes can be modified for files hosted by a Zip file system. However, 76 * owner and group information are not persisted. Files that are newly 77 * created in a Zip file system will by default have no POSIX permission data, although default permissions 78 * are returned for the attribute "{@code permissions}". 79 * 80 * <h3>Zip File System Properties</h3> 81 * 82 * The following properties may be specified when creating a Zip 83 * file system: 84 * <p> 85 * <table class="striped"> 86 * <caption style="display:none"> 87 * Configurable properties that may be specified when creating 88 * a new Zip file system 89 * </caption> 90 * <thead> 91 * <tr> 92 * <th scope="col">Property Name</th> 93 * <th scope="col">Data Type</th> 94 * <th scope="col">Default Value</th> 95 * <th scope="col">Description</th> 96 * </tr> 97 * </thead> 98 * 99 * <tbody> 100 * <tr> 101 * <td scope="row">create</td> 102 * <td>java.lang.String</td> 103 * <td>false</td> 104 * <td> 105 * If the value is {@code true}, the Zip file system provider 106 * creates a new Zip or JAR file if it does not exist. 107 * </td> 108 * </tr> 109 * <tr> 110 * <td scope="row">encoding</td> 111 * <td>java.lang.String</td> 112 * <td>UTF-8</td> 113 * <td> 114 * The value indicates the encoding scheme for the 115 * names of the entries in the Zip or JAR file. 116 * </td> 117 * </tr> 118 * <tr> 119 * <td scope="row">enablePosixFileAttributes</td> 120 * <td>java.lang.String</td> 121 * <td>false</td> 122 * <td> 123 * If the value is {@code true}, the created Zip file system will support 124 * the {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView}. 125 * </td> 126 * </tr> 127 * <tr> 128 * <td scope="row">defaultOwner</td> 129 * <td>{@link java.nio.file.attribute.UserPrincipal UserPrincipal} or java.lang.String</td> 130 * <td>null/unset</td> 131 * <td> 132 * Override the default owner for entries in the Zip file system. 133 * The value can be a UserPrincipal or a String value that is used as the UserPrincipal's name. 134 * </td> 135 * </tr> 136 * <tr> 137 * <td scope="row">defaultGroup</td> 138 * <td>{@link java.nio.file.attribute.GroupPrincipal GroupPrincipal} or java.lang.String</td> 139 * <td>null/unset</td> 140 * <td> 141 * Override the the default group for entries in the Zip file system. 142 * The value can be a GroupPrincipal or a String value that is used as the GroupPrincipal's name. 143 * </td> 144 * </tr> 145 * <tr> 146 * <td scope="row">defaultPermissions</td> 147 * <td>{@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}> 148 * or java.lang.String</td> 149 * <td>null/unset</td> 150 * <td> 151 * Override the default Set of permissions for entries in the Zip file system. 152 * The value can be a Set<PosixFilePermission> or a String that is parsed by 153 * {@link java.nio.file.attribute.PosixFilePermissions#fromString PosixFilePermissions.fromString} 154 * </td> 155 * </tr> 156 * </tbody> 157 * </table> 158 * 159 * <h3>Examples:</h3> 160 * 161 * Construct a new Zip file system that is identified by a URI. If the Zip file does not exist, 162 * it will be created: 163 * <pre> 164 * {@code 165 * 166 * URI uri = URI.create("jar:file:/home/luckydog/tennisTeam.zip"); 167 * Map<String, String> env = Map.of("create", "true"); 168 * FileSystem zipfs = FileSystems.newFileSystem(uri, env); 169 * } 170 * </pre> 171 * 172 * Construct a new Zip file system that is identified by specifying a path 173 * and using automatic file type detection. Iterate from the root of the JAR displaying each 174 * found entry: 175 * <pre> 176 * {@code 177 * 178 * FileSystem zipfs = FileSystems.newFileSystem(Path.of("helloworld.jar"), null); 179 * Path rootDir = zipfs.getPath("/"); 180 * Files.walk(rootDir) 181 * .forEach(System.out::println); 182 * } 183 * </pre> 184 * @provides java.nio.file.spi.FileSystemProvider 185 * @moduleGraph 186 * @since 9 187 */ 188 module jdk.zipfs { 189 provides java.nio.file.spi.FileSystemProvider with 190 jdk.nio.zipfs.ZipFileSystemProvider; 191 }