@sitevision/api 2023.2.1 → 2023.2.2-beta.2

package/types/java/nio/file/FileSystem/index.d.ts

@@ -0,0 +1,402 @@
+import type { FileSystemProvider } from "../spi/FileSystemProvider";
+
+import type { String } from "../../../lang/String";
+import type { Iterable } from "../../../lang/Iterable";
+import type { Set } from "../../../util/Set";
+import type { Path } from "../Path";
+import type { PathMatcher } from "../PathMatcher";
+import type { UserPrincipalLookupService } from "../attribute/UserPrincipalLookupService";
+import type { WatchService } from "../WatchService";
+import type { Object } from "../../../lang/Object";
+import type { Closeable } from "../../../io/Closeable";
+
+/**
+ * Provides an interface to a file system and is the factory for objects to
+ *  access files and other objects in the file system.
+ *
+ *  <p> The default file system, obtained by invoking the {@link FileSystems#getDefault
+ *  FileSystems.getDefault} method, provides access to the file system that is
+ *  accessible to the Java virtual machine. The {@link FileSystems} class defines
+ *  methods to create file systems that provide access to other types of (custom)
+ *  file systems.
+ *
+ *  <p> A file system is the factory for several types of objects:
+ *
+ *  <ul>
+ *    <li><p> The {@link #getPath getPath} method converts a system dependent
+ *      <em>path string</em>, returning a {@link Path} object that may be used
+ *      to locate and access a file. </p></li>
+ *    <li><p> The {@link #getPathMatcher  getPathMatcher} method is used
+ *      to create a {@link PathMatcher} that performs match operations on
+ *      paths. </p></li>
+ *    <li><p> The {@link #getFileStores getFileStores} method returns an iterator
+ *      over the underlying {@link FileStore file-stores}. </p></li>
+ *    <li><p> The {@link #getUserPrincipalLookupService getUserPrincipalLookupService}
+ *      method returns the {@link UserPrincipalLookupService} to lookup users or
+ *      groups by name. </p></li>
+ *    <li><p> The {@link #newWatchService newWatchService} method creates a
+ *      {@link WatchService} that may be used to watch objects for changes and
+ *      events. </p></li>
+ *  </ul>
+ *
+ *  <p> File systems vary greatly. In some cases the file system is a single
+ *  hierarchy of files with one top-level root directory. In other cases it may
+ *  have several distinct file hierarchies, each with its own top-level root
+ *  directory. The {@link #getRootDirectories getRootDirectories} method may be
+ *  used to iterate over the root directories in the file system. A file system
+ *  is typically composed of one or more underlying {@link FileStore file-stores}
+ *  that provide the storage for the files. Theses file stores can also vary in
+ *  the features they support, and the file attributes or <em>meta-data</em> that
+ *  they associate with files.
+ *
+ *  <p> A file system is open upon creation and can be closed by invoking its
+ *  {@link #close() close} method. Once closed, any further attempt to access
+ *  objects in the file system cause {@link ClosedFileSystemException} to be
+ *  thrown. File systems created by the default {@link FileSystemProvider provider}
+ *  cannot be closed.
+ *
+ *  <p> A {@code FileSystem} can provide read-only or read-write access to the
+ *  file system. Whether or not a file system provides read-only access is
+ *  established when the {@code FileSystem} is created and can be tested by invoking
+ *  its {@link #isReadOnly() isReadOnly} method. Attempts to write to file stores
+ *  by means of an object associated with a read-only file system throws {@link
+ *  ReadOnlyFileSystemException}.
+ *
+ *  <p> File systems are safe for use by multiple concurrent threads. The {@link
+ *  #close close} method may be invoked at any time to close a file system but
+ *  whether a file system is <i>asynchronously closeable</i> is provider specific
+ *  and therefore unspecified. In other words, if a thread is accessing an
+ *  object in a file system, and another thread invokes the {@code close} method
+ *  then it may require to block until the first operation is complete. Closing
+ *  a file system causes all open channels, watch services, and other {@link
+ *  Closeable closeable} objects associated with the file system to be closed.
+ * @since 1.7
+ */
+export type FileSystem = Object &
+  Closeable & {
+    /**
+     * Returns the provider that created this file system.
+     * @return The provider that created this file system.
+     */
+    provider(): FileSystemProvider;
+
+    /**
+     * Closes this file system.
+     *
+     *  <p> After a file system is closed then all subsequent access to the file
+     *  system, either by methods defined by this class or on objects associated
+     *  with this file system, throw {@link ClosedFileSystemException}. If the
+     *  file system is already closed then invoking this method has no effect.
+     *
+     *  <p> Closing a file system will close all open {@link
+     *  java.nio.channels.Channel channels}, {@link DirectoryStream directory-streams},
+     *  {@link WatchService watch-service}, and other closeable objects associated
+     *  with this file system. The {@link FileSystems#getDefault default} file
+     *  system cannot be closed.
+     * @throws IOException&#xA; If an I/O error occurs
+     * @throws UnsupportedOperationException&#xA; Thrown in the case of the default file system
+     */
+    close(): void;
+
+    /**
+     * Tells whether or not this file system is open.
+     *
+     *  <p> File systems created by the default provider are always open.
+     * @return {@code true} if, and only if, this file system is open
+     */
+    isOpen(): boolean;
+
+    /**
+     * Tells whether or not this file system allows only read-only access to
+     *  its file stores.
+     * @return {@code true} if, and only if, this file system provides&#xA; read-only access
+     */
+    isReadOnly(): boolean;
+
+    /**
+     * Returns the name separator, represented as a string.
+     *
+     *  <p> The name separator is used to separate names in a path string. An
+     *  implementation may support multiple name separators in which case this
+     *  method returns an implementation specific <em>default</em> name separator.
+     *  This separator is used when creating path strings by invoking the {@link
+     *  Path#toString() toString()} method.
+     *
+     *  <p> In the case of the default provider, this method returns the same
+     *  separator as {@link java.io.File#separator}.
+     * @return The name separator
+     */
+    getSeparator(): string;
+
+    /**
+     * Returns an object to iterate over the paths of the root directories.
+     *
+     *  <p> A file system provides access to a file store that may be composed
+     *  of a number of distinct file hierarchies, each with its own top-level
+     *  root directory. Unless denied by the security manager, each element in
+     *  the returned iterator corresponds to the root directory of a distinct
+     *  file hierarchy. The order of the elements is not defined. The file
+     *  hierarchies may change during the lifetime of the Java virtual machine.
+     *  For example, in some implementations, the insertion of removable media
+     *  may result in the creation of a new file hierarchy with its own
+     *  top-level directory.
+     *
+     *  <p> When a security manager is installed, it is invoked to check access
+     *  to the each root directory. If denied, the root directory is not returned
+     *  by the iterator. In the case of the default provider, the {@link
+     *  SecurityManager#checkRead(String)} method is invoked to check read access
+     *  to each root directory. It is system dependent if the permission checks
+     *  are done when the iterator is obtained or during iteration.
+     * @return An object to iterate over the root directories
+     */
+    getRootDirectories(): Iterable;
+
+    /**
+     * Returns an object to iterate over the underlying file stores.
+     *
+     *  <p> The elements of the returned iterator are the {@link
+     *  FileStore FileStores} for this file system. The order of the elements is
+     *  not defined and the file stores may change during the lifetime of the
+     *  Java virtual machine. When an I/O error occurs, perhaps because a file
+     *  store is not accessible, then it is not returned by the iterator.
+     *
+     *  <p> In the case of the default provider, and a security manager is
+     *  installed, the security manager is invoked to check {@link
+     *  RuntimePermission}<tt>("getFileStoreAttributes")</tt>. If denied, then
+     *  no file stores are returned by the iterator. In addition, the security
+     *  manager's {@link SecurityManager#checkRead(String)} method is invoked to
+     *  check read access to the file store's <em>top-most</em> directory. If
+     *  denied, the file store is not returned by the iterator. It is system
+     *  dependent if the permission checks are done when the iterator is obtained
+     *  or during iteration.
+     *
+     *  <p> <b>Usage Example:</b>
+     *  Suppose we want to print the space usage for all file stores:
+     *  <pre>
+     *      for (FileStore store: FileSystems.getDefault().getFileStores()) {
+     *          long total = store.getTotalSpace() / 1024;
+     *          long used = (store.getTotalSpace() - store.getUnallocatedSpace()) / 1024;
+     *          long avail = store.getUsableSpace() / 1024;
+     *          System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail);
+     *      }
+     *  </pre>
+     * @return An object to iterate over the backing file stores
+     */
+    getFileStores(): Iterable;
+
+    /**
+     * Returns the set of the {@link FileAttributeView#name names} of the file
+     *  attribute views supported by this {@code FileSystem}.
+     *
+     *  <p> The {@link BasicFileAttributeView} is required to be supported and
+     *  therefore the set contains at least one element, "basic".
+     *
+     *  <p> The {@link FileStore#supportsFileAttributeView(String)
+     *  supportsFileAttributeView(String)} method may be used to test if an
+     *  underlying {@link FileStore} supports the file attributes identified by a
+     *  file attribute view.
+     * @return An unmodifiable set of the names of the supported file attribute&#xA; views
+     */
+    supportedFileAttributeViews(): Set;
+
+    /**
+     * Converts a path string, or a sequence of strings that when joined form
+     *  a path string, to a {@code Path}. If {@code more} does not specify any
+     *  elements then the value of the {@code first} parameter is the path string
+     *  to convert. If {@code more} specifies one or more elements then each
+     *  non-empty string, including {@code first}, is considered to be a sequence
+     *  of name elements (see {@link Path}) and is joined to form a path string.
+     *  The details as to how the Strings are joined is provider specific but
+     *  typically they will be joined using the {@link #getSeparator
+     *  name-separator} as the separator. For example, if the name separator is
+     *  "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the
+     *  path string {@code "/foo/bar/gus"} is converted to a {@code Path}.
+     *  A {@code Path} representing an empty path is returned if {@code first}
+     *  is the empty string and {@code more} does not contain any non-empty
+     *  strings.
+     *
+     *  <p> The parsing and conversion to a path object is inherently
+     *  implementation dependent. In the simplest case, the path string is rejected,
+     *  and {@link InvalidPathException} thrown, if the path string contains
+     *  characters that cannot be converted to characters that are <em>legal</em>
+     *  to the file store. For example, on UNIX systems, the NUL (&#92;u0000)
+     *  character is not allowed to be present in a path. An implementation may
+     *  choose to reject path strings that contain names that are longer than those
+     *  allowed by any file store, and where an implementation supports a complex
+     *  path syntax, it may choose to reject path strings that are <em>badly
+     *  formed</em>.
+     *
+     *  <p> In the case of the default provider, path strings are parsed based
+     *  on the definition of paths at the platform or virtual file system level.
+     *  For example, an operating system may not allow specific characters to be
+     *  present in a file name, but a specific underlying file store may impose
+     *  different or additional restrictions on the set of legal
+     *  characters.
+     *
+     *  <p> This method throws {@link InvalidPathException} when the path string
+     *  cannot be converted to a path. Where possible, and where applicable,
+     *  the exception is created with an {@link InvalidPathException#getIndex
+     *  index} value indicating the first position in the {@code path} parameter
+     *  that caused the path string to be rejected.
+     * @param first&#xA; the path string or initial part of the path string
+     * @param more&#xA; additional strings to be joined to form the path string
+     * @return the resulting {@code Path}
+     * @throws InvalidPathException&#xA; If the path string cannot be converted
+     */
+    getPath(first: String | string, more: String | string[]): Path;
+
+    /**
+     * Returns a {@code PathMatcher} that performs match operations on the
+     *  {@code String} representation of {@link Path} objects by interpreting a
+     *  given pattern.
+     *
+     *  The {@code syntaxAndPattern} parameter identifies the syntax and the
+     *  pattern and takes the form:
+     *  <blockquote><pre>
+     *  <i>syntax</i><b>:</b><i>pattern</i>
+     *  </pre></blockquote>
+     *  where {@code ':'} stands for itself.
+     *
+     *  <p> A {@code FileSystem} implementation supports the "{@code glob}" and
+     *  "{@code regex}" syntaxes, and may support others. The value of the syntax
+     *  component is compared without regard to case.
+     *
+     *  <p> When the syntax is "{@code glob}" then the {@code String}
+     *  representation of the path is matched using a limited pattern language
+     *  that resembles regular expressions but with a simpler syntax. For example:
+     *
+     *  <blockquote>
+     *  <table border="0" summary="Pattern Language">
+     *  <tr>
+     *    <td>{@code *.java}</td>
+     *    <td>Matches a path that represents a file name ending in {@code .java}</td>
+     *  </tr>
+     *  <tr>
+     *    <td>{@code *.*}</td>
+     *    <td>Matches file names containing a dot</td>
+     *  </tr>
+     *  <tr>
+     *    <td>{@code *.{java,class}}</td>
+     *    <td>Matches file names ending with {@code .java} or {@code .class}</td>
+     *  </tr>
+     *  <tr>
+     *    <td>{@code foo.?}</td>
+     *    <td>Matches file names starting with {@code foo.} and a single
+     *    character extension</td>
+     *  </tr>
+     *  <tr>
+     *    <td><tt>&#47;home&#47;*&#47;*</tt>
+     *    <td>Matches <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
+     *  </tr>
+     *  <tr>
+     *    <td><tt>&#47;home&#47;**</tt>
+     *    <td>Matches <tt>&#47;home&#47;gus</tt> and
+     *    <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
+     *  </tr>
+     *  <tr>
+     *    <td><tt>C:&#92;&#92;*</tt>
+     *    <td>Matches <tt>C:&#92;foo</tt> and <tt>C:&#92;bar</tt> on the Windows
+     *    platform (note that the backslash is escaped; as a string literal in the
+     *    Java Language the pattern would be <tt>"C:&#92;&#92;&#92;&#92;*"</tt>) </td>
+     *  </tr>
+     *
+     *  </table>
+     *  </blockquote>
+     *
+     *  <p> The following rules are used to interpret glob patterns:
+     *
+     *  <ul>
+     *    <li><p> The {@code *} character matches zero or more {@link Character
+     *    characters} of a {@link Path#getName(int) name} component without
+     *    crossing directory boundaries. </p></li>
+     *
+     *    <li><p> The {@code **} characters matches zero or more {@link Character
+     *    characters} crossing directory boundaries. </p></li>
+     *
+     *    <li><p> The {@code ?} character matches exactly one character of a
+     *    name component.</p></li>
+     *
+     *    <li><p> The backslash character ({@code \}) is used to escape characters
+     *    that would otherwise be interpreted as special characters. The expression
+     *    {@code \\} matches a single backslash and "\{" matches a left brace
+     *    for example.  </p></li>
+     *
+     *    <li><p> The {@code [ ]} characters are a <i>bracket expression</i> that
+     *    match a single character of a name component out of a set of characters.
+     *    For example, {@code [abc]} matches {@code "a"}, {@code "b"}, or {@code "c"}.
+     *    The hyphen ({@code -}) may be used to specify a range so {@code [a-z]}
+     *    specifies a range that matches from {@code "a"} to {@code "z"} (inclusive).
+     *    These forms can be mixed so [abce-g] matches {@code "a"}, {@code "b"},
+     *    {@code "c"}, {@code "e"}, {@code "f"} or {@code "g"}. If the character
+     *    after the {@code [} is a {@code !} then it is used for negation so {@code
+     *    [!a-c]} matches any character except {@code "a"}, {@code "b"}, or {@code
+     *    "c"}.
+     *    <p> Within a bracket expression the {@code *}, {@code ?} and {@code \}
+     *    characters match themselves. The ({@code -}) character matches itself if
+     *    it is the first character within the brackets, or the first character
+     *    after the {@code !} if negating.</p></li>
+     *
+     *    <li><p> The {@code { }} characters are a group of subpatterns, where
+     *    the group matches if any subpattern in the group matches. The {@code ","}
+     *    character is used to separate the subpatterns. Groups cannot be nested.
+     *    </p></li>
+     *
+     *    <li><p> Leading period<tt>&#47;</tt>dot characters in file name are
+     *    treated as regular characters in match operations. For example,
+     *    the {@code "*"} glob pattern matches file name {@code ".login"}.
+     *    The {@link Files#isHidden} method may be used to test whether a file
+     *    is considered hidden.
+     *    </p></li>
+     *
+     *    <li><p> All other characters match themselves in an implementation
+     *    dependent manner. This includes characters representing any {@link
+     *    FileSystem#getSeparator name-separators}. </p></li>
+     *
+     *    <li><p> The matching of {@link Path#getRoot root} components is highly
+     *    implementation-dependent and is not specified. </p></li>
+     *
+     *  </ul>
+     *
+     *  <p> When the syntax is "{@code regex}" then the pattern component is a
+     *  regular expression as defined by the {@link java.util.regex.Pattern}
+     *  class.
+     *
+     *  <p>  For both the glob and regex syntaxes, the matching details, such as
+     *  whether the matching is case sensitive, are implementation-dependent
+     *  and therefore not specified.
+     * @param syntaxAndPattern&#xA; The syntax and pattern
+     * @return A path matcher that may be used to match paths against the pattern
+     * @throws IllegalArgumentException&#xA; If the parameter does not take the form: {@code syntax:pattern}
+     * @throws java.util.regex.PatternSyntaxException&#xA; If the pattern is invalid
+     * @throws UnsupportedOperationException&#xA; If the pattern syntax is not known to the implementation
+     * @see Files#newDirectoryStream(Path,String)
+     */
+    getPathMatcher(syntaxAndPattern: String | string): PathMatcher;
+
+    /**
+     * Returns the {@code UserPrincipalLookupService} for this file system
+     *  <i>(optional operation)</i>. The resulting lookup service may be used to
+     *  lookup user or group names.
+     *
+     *  <p> <b>Usage Example:</b>
+     *  Suppose we want to make "joe" the owner of a file:
+     *  <pre>
+     *      UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService();
+     *      Files.setOwner(path, lookupService.lookupPrincipalByName("joe"));
+     *  </pre>
+     * @throws UnsupportedOperationException&#xA; If this {@code FileSystem} does not does have a lookup service
+     * @return The {@code UserPrincipalLookupService} for this file system
+     */
+    getUserPrincipalLookupService(): UserPrincipalLookupService;
+
+    /**
+     * Constructs a new {@link WatchService} <i>(optional operation)</i>.
+     *
+     *  <p> This method constructs a new watch service that may be used to watch
+     *  registered objects for changes and events.
+     * @return a new watch service
+     * @throws UnsupportedOperationException&#xA; If this {@code FileSystem} does not support watching file system&#xA; objects for changes and events. This exception is not thrown&#xA; by {@code FileSystems} created by the default provider.
+     * @throws IOException&#xA; If an I/O error occurs
+     */
+    newWatchService(): WatchService;
+  };

package/types/java/nio/file/FileSystem/index.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  provider: function provider() {},
+  close: function close() {},
+  isOpen: function isOpen() {},
+  isReadOnly: function isReadOnly() {},
+  getSeparator: function getSeparator() {},
+  getRootDirectories: function getRootDirectories() {},
+  getFileStores: function getFileStores() {},
+  supportedFileAttributeViews: function supportedFileAttributeViews() {},
+  getPath: function getPath() {},
+  getPathMatcher: function getPathMatcher() {},
+  getUserPrincipalLookupService: function getUserPrincipalLookupService() {},
+  newWatchService: function newWatchService() {}
+};
+exports["default"] = _default;

package/types/java/nio/file/LinkOption/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Defines the options as to how symbolic links are handled.
+ * @since 1.7
+ */
+export type LinkOption = {
+  NOFOLLOW_LINKS: "NOFOLLOW_LINKS";
+};

package/types/java/nio/file/LinkOption/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  NOFOLLOW_LINKS: "NOFOLLOW_LINKS"
+};
+exports["default"] = _default;

package/types/java/nio/file/OpenOption/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An object that configures how to open or create a file.
+ *
+ *  <p> Objects of this type are used by methods such as {@link
+ *  Files#newOutputStream(Path,OpenOption[]) newOutputStream}, {@link
+ *  Files#newByteChannel newByteChannel}, {@link
+ *  java.nio.channels.FileChannel#open FileChannel.open}, and {@link
+ *  java.nio.channels.AsynchronousFileChannel#open AsynchronousFileChannel.open}
+ *  when opening or creating a file.
+ *
+ *  <p> The {@link StandardOpenOption} enumeration type defines the
+ *  <i>standard</i> options.
+ * @since 1.7
+ */
+export type OpenOption = {};

package/types/java/nio/file/OpenOption/index.js

@@ -0,0 +1,8 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {};
+exports["default"] = _default;