src/jdk.zipfs/share/classes/module-info.java

rev 55003 : 8213031: (zipfs) Add support for POSIX file permissions

@@ -39,10 +39,46 @@
  *
  * <h3>URI Scheme Used to Identify the Zip File System</h3>
  *
  * The URI {@link java.net.URI#getScheme scheme} that identifies the ZIP file system is {@code jar}.
  *
+ * <h3>Support for POSIX file permissions</h3>
+ *
+ * A Zip file system supports POSIX permissions.<br>
+ * <br>
+ * 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}&lt;{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}&gt;.
+ * 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.<br>
+ * <br>
+ * 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}".
+ *
  * <h3>Zip File System Properties</h3>
  *
  * The following properties may be specified when creating a Zip
  * file system:
  * <p>

@@ -77,10 +113,48 @@
  *   <td>
  *       The value indicates the encoding scheme for the
  *       names of the entries in the Zip or JAR file.
  *   </td>
  * </tr>
+ * <tr>
+ *   <td scope="row">enablePosixFileAttributes</td>
+ *   <td>java.lang.String</td>
+ *   <td>false</td>
+ *   <td>
+ *       If the value is {@code true}, the created Zip file system will support
+ *       the {@link java.nio.file.attribute.PosixFileAttributeView PosixFileAttributeView}.
+ *   </td>
+ * </tr>
+ * <tr>
+ *   <td scope="row">defaultOwner</td>
+ *   <td>{@link java.nio.file.attribute.UserPrincipal UserPrincipal} or java.lang.String</td>
+ *   <td>null/unset</td>
+ *   <td>
+ *       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.
+ *   </td>
+ * </tr>
+ * <tr>
+ *   <td scope="row">defaultGroup</td>
+ *   <td>{@link java.nio.file.attribute.GroupPrincipal GroupPrincipal} or java.lang.String</td>
+ *   <td>null/unset</td>
+ *   <td>
+ *       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.
+ *   </td>
+ * </tr>
+ * <tr>
+ *   <td scope="row">defaultPermissions</td>
+ *   <td>{@link java.util.Set Set}&lt;{@link java.nio.file.attribute.PosixFilePermission PosixFilePermission}&gt;
+ *       or java.lang.String</td>
+ *   <td>null/unset</td>
+ *   <td>
+ *       Override the default Set of permissions for entries in the Zip file system.
+ *       The value can be a Set&lt;PosixFilePermission&gt; or a String that is parsed by
+ *       {@link java.nio.file.attribute.PosixFilePermissions#fromString PosixFilePermissions.fromString}
+ *   </td>
+ * </tr>
  * </tbody>
  * </table>
  *
  * <h3>Examples:</h3>
  *