21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
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 |
22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. |
23 * questions. |
24 */ |
24 */ |
25 |
25 |
|
26 import java.nio.file.Files; |
|
27 import java.nio.file.LinkOption; |
|
28 import java.nio.file.Path; |
|
29 import java.nio.file.attribute.FileAttributeView; |
|
30 import java.nio.file.attribute.PosixFileAttributes; |
|
31 import java.nio.file.attribute.PosixFilePermission; |
|
32 import java.nio.file.attribute.PosixFileAttributeView; |
|
33 import java.util.Set; |
|
34 |
26 /** |
35 /** |
27 * Provides the implementation of the Zip file system provider. |
36 * 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. |
37 * The Zip file system provider treats the contents of a Zip or JAR file as a file system. |
29 * <p> |
38 * |
30 * |
39 * <h2>Accessing a Zip File System</h2> |
31 * <h3>Accessing a Zip File System</h3> |
|
32 * |
40 * |
33 * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem} |
41 * The {@linkplain java.nio.file.FileSystems FileSystems} {@code newFileSystem} |
34 * static factory methods can be used to: |
42 * static factory methods can be used to: |
35 * <ul> |
43 * <ul> |
36 * <li>Create a Zip file system</li> |
44 * <li>Create a Zip file system</li> |
37 * <li>Open an existing file as a Zip file system</li> |
45 * <li>Open an existing file as a Zip file system</li> |
38 * </ul> |
46 * </ul> |
39 * |
47 * |
40 * <h3>URI Scheme Used to Identify the Zip File System</h3> |
48 * <h2>URI Scheme Used to Identify the Zip File System</h2> |
41 * |
49 * |
42 * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}. |
50 * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}. |
43 * |
51 * |
44 * <h3>Zip File System Properties</h3> |
52 * <h2>POSIX file attributes</h2> |
|
53 * |
|
54 * A Zip file system supports a file attribute {@link FileAttributeView view} |
|
55 * named "{@code zip}" that defines the following file attribute: |
|
56 * |
|
57 * <blockquote> |
|
58 * <table class="striped"> |
|
59 * <caption style="display:none">Supported attributes</caption> |
|
60 * <thead> |
|
61 * <tr> |
|
62 * <th scope="col">Name</th> |
|
63 * <th scope="col">Type</th> |
|
64 * </tr> |
|
65 * </thead> |
|
66 * <tbody> |
|
67 * <tr> |
|
68 * <th scope="row">permissions</th> |
|
69 * <td>{@link Set}<{@link PosixFilePermission}></td> |
|
70 * </tr> |
|
71 * </tbody> |
|
72 * </table> |
|
73 * </blockquote> |
|
74 * |
|
75 * The "permissions" attribute is the set of access permissions that are optionally |
|
76 * stored for entries in a Zip file. The value of the attribute is {@code null} |
|
77 * for entries that do not have access permissions. Zip file systems do not |
|
78 * enforce access permissions. |
|
79 * |
|
80 * <p> The "permissions" attribute may be read and set using the |
|
81 * {@linkplain Files#getAttribute(Path, String, LinkOption...) Files.getAttribute} and |
|
82 * {@linkplain Files#setAttribute(Path, String, Object, LinkOption...) Files.setAttribute} |
|
83 * methods. The following example uses these methods to read and set the attribute: |
|
84 * <pre> {@code |
|
85 * Set<PosixFilePermission> perms = Files.getAttribute(entry, "zip:permissions"); |
|
86 * if (perms == null) { |
|
87 * perms = PosixFilePermissions.fromString("rw-rw-rw-"); |
|
88 * Files.setAttribute(entry, "zip:permissions", perms); |
|
89 * } |
|
90 * } </pre> |
|
91 * |
|
92 * <p> In addition to the "{@code zip}" view, a Zip file system optionally supports |
|
93 * the {@link PosixFileAttributeView} ("{@code posix}"). |
|
94 * This view extends the "{@code basic}" view with type safe access to the |
|
95 * {@link PosixFileAttributes#owner() owner}, {@link PosixFileAttributes#group() group-owner}, |
|
96 * and {@link PosixFileAttributes#permissions() permissions} attributes. The |
|
97 * "{@code posix}" view is only supported when the Zip file system is created with |
|
98 * the provider property "{@code enablePosixFileAttributes}" set to "{@code true}". |
|
99 * The following creates a file system with this property and reads the access |
|
100 * permissions of a file: |
|
101 * <pre> {@code |
|
102 * var env = Map.of("enablePosixFileAttributes", "true"); |
|
103 * try (FileSystem fs = FileSystems.newFileSystem(file, env) { |
|
104 * Path entry = fs.getPath("entry"); |
|
105 * Set<PosixFilePermission> perms = Files.getPosixFilePermissions(entry); |
|
106 * } |
|
107 * } </pre> |
|
108 * |
|
109 * <p> The file owner and group owner attributes are not persisted, meaning they are |
|
110 * not stored in the zip file. The "{@code defaultOwner}" and "{@code defaultGroup}" |
|
111 * provider properties (listed below) can be used to configure the default values |
|
112 * for these attributes. If these properties are not set then the file owner |
|
113 * defaults to the owner of the zip file, and the group owner defaults to the |
|
114 * zip file's group owner (or the file owner on platforms that don't support a |
|
115 * group owner). |
|
116 * |
|
117 * <p> The "{@code permissions}" attribute is not optional in the "{@code posix}" |
|
118 * view so a default set of permissions are used for entries that do not have |
|
119 * access permissions stored in the Zip file. The default set of permissions |
|
120 * are |
|
121 * <ul> |
|
122 * <li>{@link PosixFilePermission#OWNER_READ OWNER_READ}</li> |
|
123 * <li>{@link PosixFilePermission#OWNER_WRITE OWNER_WRITE}</li> |
|
124 * <li>{@link PosixFilePermission#GROUP_READ GROUP_READ}</li> |
|
125 * </ul> |
|
126 * The default permissions can be configured with the "{@code defaultPermissions}" |
|
127 * property described below. |
|
128 * |
|
129 * <h2>Zip File System Properties</h2> |
45 * |
130 * |
46 * The following properties may be specified when creating a Zip |
131 * The following properties may be specified when creating a Zip |
47 * file system: |
132 * file system: |
48 * <p> |
|
49 * <table class="striped"> |
133 * <table class="striped"> |
50 * <caption style="display:none"> |
134 * <caption style="display:none"> |
51 * Configurable properties that may be specified when creating |
135 * Configurable properties that may be specified when creating |
52 * a new Zip file system |
136 * a new Zip file system |
53 * </caption> |
137 * </caption> |
54 * <thead> |
138 * <thead> |
55 * <tr> |
139 * <tr> |
56 * <th scope="col">Property Name</th> |
140 * <th scope="col">Property Name</th> |
57 * <th scope="col">Data Type</th> |
141 * <th scope="col">Data Type</th> |
58 * <th scope="col">Default Value</th> |
142 * <th scope="col">Default Value</th> |
59 * <th scope="col">Description</th> |
143 * <th scope="col">Description</th> |
60 * </tr> |
144 * </tr> |
61 * </thead> |
145 * </thead> |
62 * |
146 * |
63 * <tbody> |
147 * <tbody> |
64 * <tr> |
148 * <tr> |
65 * <td scope="row">create</td> |
149 * <th scope="row">create</th> |
66 * <td>java.lang.String</td> |
150 * <td>{@link java.lang.String} or {@link java.lang.Boolean}</td> |
67 * <td>false</td> |
151 * <td>false</td> |
68 * <td> |
152 * <td> |
69 * If the value is {@code true}, the Zip file system provider |
153 * If the value is {@code true}, the Zip file system provider |
70 * creates a new Zip or JAR file if it does not exist. |
154 * creates a new Zip or JAR file if it does not exist. |
71 * </td> |
155 * </td> |
72 * </tr> |
156 * </tr> |
73 * <tr> |
157 * <tr> |
74 * <td scope="row">encoding</td> |
158 * <th scope="row">encoding</th> |
75 * <td>java.lang.String</td> |
159 * <td>{@link java.lang.String}</td> |
76 * <td>UTF-8</td> |
160 * <td>UTF-8</td> |
77 * <td> |
161 * <td> |
78 * The value indicates the encoding scheme for the |
162 * The value indicates the encoding scheme for the |
79 * names of the entries in the Zip or JAR file. |
163 * names of the entries in the Zip or JAR file. |
80 * </td> |
164 * </td> |
81 * </tr> |
165 * </tr> |
82 * </tbody> |
166 * <tr> |
|
167 * <th scope="row">enablePosixFileAttributes</th> |
|
168 * <td>{@link java.lang.String} or {@link java.lang.Boolean}</td> |
|
169 * <td>false</td> |
|
170 * <td> |
|
171 * If the value is {@code true}, the Zip file system will support |
|
172 * the {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView}. |
|
173 * </td> |
|
174 * </tr> |
|
175 * <tr> |
|
176 * <th scope="row">defaultOwner</th> |
|
177 * <td>{@link java.nio.file.attribute.UserPrincipal UserPrincipal}<br> or |
|
178 * {@link java.lang.String}</td> |
|
179 * <td>null/unset</td> |
|
180 * <td> |
|
181 * Override the default owner for entries in the Zip file system.<br> |
|
182 * The value can be a UserPrincipal or a String value that is used as the UserPrincipal's name. |
|
183 * </td> |
|
184 * </tr> |
|
185 * <tr> |
|
186 * <th scope="row">defaultGroup</th> |
|
187 * <td>{@link java.nio.file.attribute.GroupPrincipal GroupPrincipal}<br> or |
|
188 * {@link java.lang.String}</td> |
|
189 * <td>null/unset</td> |
|
190 * <td> |
|
191 * Override the the default group for entries in the Zip file system.<br> |
|
192 * The value can be a GroupPrincipal or a String value that is used as the GroupPrincipal's name. |
|
193 * </td> |
|
194 * </tr> |
|
195 * <tr> |
|
196 * <th scope="row">defaultPermissions</th> |
|
197 * <td>{@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}><br> |
|
198 * or {@link java.lang.String}</td> |
|
199 * <td>null/unset</td> |
|
200 * <td> |
|
201 * Override the default Set of permissions for entries in the Zip file system.<br> |
|
202 * The value can be a {@link java.util.Set Set}<{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}> or<br> |
|
203 * a String that is parsed by {@link java.nio.file.attribute.PosixFilePermissions#fromString PosixFilePermissions::fromString} |
|
204 * </td> |
|
205 * </tr> |
|
206 * <tr> |
|
207 * <th scope="row">compressionMethod</th> |
|
208 * <td>{@link java.lang.String}</td> |
|
209 * <td>"DEFLATED"</td> |
|
210 * <td> |
|
211 * The value representing the compression method to use when writing entries |
|
212 * to the Zip file system. |
|
213 * <ul> |
|
214 * <li> |
|
215 * If the value is {@code "STORED"}, the Zip file system provider will |
|
216 * not compress entries when writing to the Zip file system. |
|
217 * </li> |
|
218 * <li> |
|
219 * If the value is {@code "DEFLATED"} or the property is not set, |
|
220 * the Zip file system provider will use data compression when |
|
221 * writing entries to the Zip file system. |
|
222 * </li> |
|
223 * <li> |
|
224 * If the value is not {@code "STORED"} or {@code "DEFLATED"}, an |
|
225 * {@code IllegalArgumentException} will be thrown when the Zip |
|
226 * filesystem is created. |
|
227 * </li> |
|
228 * </ul> |
|
229 * </td> |
|
230 * </tr> |
|
231 * <tr> |
|
232 * <th scope="row">releaseVersion</th> |
|
233 * <td>{@link java.lang.String} or {@link java.lang.Integer}</td> |
|
234 * <td>null/unset</td> |
|
235 * <td> |
|
236 * A value representing the version entry to use when accessing a |
|
237 * <a href=="{@docRoot}/../specs/jar/jar.html#multi-release-jar-files"> |
|
238 * multi-release JAR</a>. If the JAR is not a |
|
239 * <a href=="{@docRoot}/../specs/jar/jar.html#multi-release-jar-files"> |
|
240 * multi-release JAR</a>, the value will be ignored and the JAR will be |
|
241 * considered un-versioned. |
|
242 * <p> |
|
243 * The value must be either the string "runtime" or represent a valid |
|
244 * {@linkplain Runtime.Version Java SE Platform version number}, |
|
245 * such as {@code 9} or {@code 14}, in order to determine the version entry. |
|
246 * |
|
247 * <ul> |
|
248 * <li> |
|
249 * If the value is {@code null} or the property is not set, |
|
250 * then the JAR will be treated as an un-versioned JAR. |
|
251 * </li> |
|
252 * <li> |
|
253 * If the value is {@code "runtime"}, the |
|
254 * version entry will be determined by invoking |
|
255 * {@linkplain Runtime.Version#feature() Runtime.Version.feature()}. |
|
256 * </li> |
|
257 * <li> |
|
258 * If the value does not represent a valid |
|
259 * {@linkplain Runtime.Version Java SE Platform version number}, |
|
260 * an {@code IllegalArgumentException} will be thrown. |
|
261 * </li> |
|
262 * </ul> |
|
263 * </td> |
|
264 * </tr> |
|
265 * </tbody> |
83 * </table> |
266 * </table> |
84 * |
267 * |
85 * <h3>Examples:</h3> |
268 * <h2>Examples:</h2> |
86 * |
269 * |
87 * Construct a new Zip file system that is identified by a URI. If the Zip file does not exist, |
270 * Construct a new Zip file system that is identified by a URI. If the Zip file does not exist, |
88 * it will be created: |
271 * it will be created: |
89 * <pre> |
272 * <pre> |
90 * {@code |
273 * {@code |