@jahia/javascript-modules-library 0.2.0 → 0.4.0

package/types/java.io.d.ts

@@ -7,7 +7,7 @@ export class BufferedReader {
    * @return The character read, as an integer in the range
    *         0 to 65535 (`0x00-0xffff`), or -1 if the
    *         end of the stream has been reached
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
   */
   read(): number;
   /**
@@ -17,22 +17,24 @@ export class BufferedReader {
    * {@link Reader#read(char[], int, int) read} method of the
    * {@link Reader} class.  As an additional convenience, it
    * attempts to read as many characters as possible by repeatedly invoking
-   * the read method of the underlying stream.  This iterated
-   * read continues until one of the following conditions becomes
-   * true: 
+   * the `read` method of the underlying stream.  This iterated
+   * `read` continues until one of the following conditions becomes
+   * true:
+   * 
    *
    *    The specified number of characters have been read,
    *
-   *    The read method of the underlying stream returns
-   *   -1, indicating end-of-file, or
+   *    The `read` method of the underlying stream returns
+   *   `-1`, indicating end-of-file, or
    *
-   *    The ready method of the underlying stream
-   *   returns false, indicating that further input requests
+   *    The `ready` method of the underlying stream
+   *   returns `false`, indicating that further input requests
    *   would block.
    *
-   *  If the first read on the underlying stream returns
-   * -1 to indicate end-of-file then this method returns
-   * -1.  Otherwise this method returns the number of characters
+   * 
+   * If the first `read` on the underlying stream returns
+   * `-1` to indicate end-of-file then this method returns
+   * `-1`.  Otherwise this method returns the number of characters
    * actually read.
    *
    *  Subclasses of this class are encouraged, but not required, to
@@ -43,18 +45,17 @@ export class BufferedReader {
    * however, the buffer is empty, the mark is not valid, and the requested
    * length is at least as large as the buffer, then this method will read
    * characters directly from the underlying stream into the given array.
-   * Thus redundant BufferedReaders will not copy data
+   * Thus redundant `BufferedReader`s will not copy data
    * unnecessarily.
    *
-   * @param      cbuf  Destination buffer
-   * @param      off   Offset at which to start storing characters
-   * @param      len   Maximum number of characters to read
+   * @param      cbuf  {@inheritDoc}
+   * @param      off   {@inheritDoc}
+   * @param      len   {@inheritDoc}
    *
-   * @return     The number of characters read, or -1 if the end of the
-   *             stream has been reached
+   * @return     {@inheritDoc}
    *
-   * @exception  IOException  If an I/O error occurs
-   * @exception  IndexOutOfBoundsException {@inheritDoc}
+   * @throws     IndexOutOfBoundsException {@inheritDoc}
+   * @throws     IOException  {@inheritDoc}
   */
   read(cbuf: string[], off: number, len: number): number;
   /**
@@ -67,7 +68,7 @@ export class BufferedReader {
    *             any line-termination characters, or null if the end of the
    *             stream has been reached without reading any characters
    *
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
    *
    * @see java.nio.file.Files#readAllLines
   */
@@ -77,7 +78,7 @@ export class BufferedReader {
    * stream is ready if the buffer is not empty, or if the underlying
    * character stream is ready.
    *
-   * @exception  IOException  If an I/O error occurs
+   * @throws     IOException  If an I/O error occurs
   */
   ready(): boolean;
 }
@@ -95,7 +96,7 @@ export class File {
   getName(): string;
   /**
    * Returns the pathname string of this abstract pathname's parent, or
-   * null if this pathname does not name a parent directory.
+   * `null` if this pathname does not name a parent directory.
    *
    *  The parent of an abstract pathname consists of the
    * pathname's prefix, if any, and each name in the pathname's name
@@ -103,13 +104,13 @@ export class File {
    * the pathname does not name a parent directory.
    *
    * @return  The pathname string of the parent directory named by this
-   *          abstract pathname, or null if this pathname
+   *          abstract pathname, or `null` if this pathname
    *          does not name a parent
   */
   getParent(): string;
   /**
    * Returns the abstract pathname of this abstract pathname's parent,
-   * or null if this pathname does not name a parent
+   * or `null` if this pathname does not name a parent
    * directory.
    *
    *  The parent of an abstract pathname consists of the
@@ -118,7 +119,7 @@ export class File {
    * the pathname does not name a parent directory.
    *
    * @return  The abstract pathname of the parent directory named by this
-   *          abstract pathname, or null if this pathname
+   *          abstract pathname, or `null` if this pathname
    *          does not name a parent
    *
    * @since 1.2
@@ -135,12 +136,12 @@ export class File {
   /**
    * Tests whether this abstract pathname is absolute.  The definition of
    * absolute pathname is system dependent.  On UNIX systems, a pathname is
-   * absolute if its prefix is "/".  On Microsoft Windows systems, a
+   * absolute if its prefix is `"/"`.  On Microsoft Windows systems, a
    * pathname is absolute if its prefix is a drive specifier followed by
-   * "\\", or if its prefix is "\\\\".
+   * `"\\"`, or if its prefix is `"\\\\"`.
    *
-   * @return  true if this abstract pathname is absolute,
-   *          false otherwise
+   * @return  `true` if this abstract pathname is absolute,
+   *          `false` otherwise
   */
   isAbsolute(): boolean;
   /**
@@ -150,7 +151,7 @@ export class File {
    * string is simply returned as if by the {@link #getPath}
    * method.  If this abstract pathname is the empty abstract pathname then
    * the pathname string of the current user directory, which is named by the
-   * system property user.dir, is returned.  Otherwise this
+   * system property `user.dir`, is returned.  Otherwise this
    * pathname is resolved in a system-dependent way.  On UNIX systems, a
    * relative pathname is made absolute by resolving it against the current
    * user directory.  On Microsoft Windows systems, a relative pathname is made absolute
@@ -251,9 +252,9 @@ export class File {
    * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
    * Files.readAttributes} method may be used.
    *
-   * @return true if and only if the file denoted by this
+   * @return `true` if and only if the file denoted by this
    *          abstract pathname exists and is a directory;
-   *          false otherwise
+   *          `false` otherwise
    *
    * @throws  SecurityException
    *          If a security manager exists and its {@link
@@ -273,9 +274,9 @@ export class File {
    * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
    * Files.readAttributes} method may be used.
    *
-   * @return  true if and only if the file denoted by this
+   * @return  `true` if and only if the file denoted by this
    *          abstract pathname exists and is a normal file;
-   *          false otherwise
+   *          `false` otherwise
    *
    * @throws  SecurityException
    *          If a security manager exists and its {@link
@@ -287,10 +288,10 @@ export class File {
    * Tests whether the file named by this abstract pathname is a hidden
    * file.  The exact definition of hidden is system-dependent.  On
    * UNIX systems, a file is considered to be hidden if its name begins with
-   * a period character ('.').  On Microsoft Windows systems, a file is
+   * a period character (`'.'`).  On Microsoft Windows systems, a file is
    * considered to be hidden if it has been marked as such in the filesystem.
    *
-   * @return  true if and only if the file denoted by this
+   * @return  `true` if and only if the file denoted by this
    *          abstract pathname is hidden according to the conventions of the
    *          underlying platform
    *
@@ -304,10 +305,13 @@ export class File {
   isHidden(): boolean;
   /**
    * Returns the size of the partition named by this
-   * abstract pathname.
+   * abstract pathname. If the total number of bytes in the partition is
+   * greater than {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be
+   * returned.
    *
    * @return  The size, in bytes, of the partition or `0L` if this
-   *          abstract pathname does not name a partition
+   *          abstract pathname does not name a partition or if the size
+   *          cannot be obtained
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -316,10 +320,13 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getTotalSpace
   */
   getTotalSpace(): number;
   /**
-   * Returns the number of unallocated bytes in the partition named by this abstract path name.
+   * Returns the number of unallocated bytes in the partition named by this abstract path name.  If the
+   * number of unallocated bytes in the partition is greater than
+   * {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be returned.
    *
    *  The returned number of unallocated bytes is a hint, but not
    * a guarantee, that it is possible to use most or any of these
@@ -331,9 +338,10 @@ export class File {
    * will succeed.
    *
    * @return  The number of unallocated bytes on the partition or `0L`
-   *          if the abstract pathname does not name a partition.  This
-   *          value will be less than or equal to the total file system size
-   *          returned by {@link #getTotalSpace}.
+   *          if the abstract pathname does not name a partition or if this
+   *          number cannot be obtained.  This value will be less than or
+   *          equal to the total file system size returned by
+   *          {@link #getTotalSpace}.
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -342,28 +350,32 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getUnallocatedSpace
   */
   getFreeSpace(): number;
   /**
    * Returns the number of bytes available to this virtual machine on the
-   * partition named by this abstract pathname.  When
-   * possible, this method checks for write permissions and other operating
-   * system restrictions and will therefore usually provide a more accurate
-   * estimate of how much new data can actually be written than {@link
-   * #getFreeSpace}.
+   * partition named by this abstract pathname.  If
+   * the number of available bytes in the partition is greater than
+   * {@link Long#MAX_VALUE}, then `Long.MAX_VALUE` will be returned.
+   * When possible, this method checks for write permissions and other
+   * operating system restrictions and will therefore usually provide a more
+   * accurate estimate of how much new data can actually be written than
+   * {@link #getFreeSpace}.
    *
    *  The returned number of available bytes is a hint, but not a
    * guarantee, that it is possible to use most or any of these bytes.  The
-   * number of unallocated bytes is most likely to be accurate immediately
+   * number of available bytes is most likely to be accurate immediately
    * after this call.  It is likely to be made inaccurate by any external
    * I/O operations including those made on the system outside of this
    * virtual machine.  This method makes no guarantee that write operations
    * to this file system will succeed.
    *
    * @return  The number of available bytes on the partition or `0L`
-   *          if the abstract pathname does not name a partition.  On
-   *          systems where this information is not available, this method
-   *          will be equivalent to a call to {@link #getFreeSpace}.
+   *          if the abstract pathname does not name a partition or if this
+   *          number cannot be obtained.  On systems where this information
+   *          is not available, this method will be equivalent to a call to
+   *          {@link #getFreeSpace}.
    *
    * @throws  SecurityException
    *          If a security manager has been installed and it denies
@@ -372,6 +384,7 @@ export class File {
    *          read access to the file named by this abstract pathname
    *
    * @since  1.6
+   * @see FileStore#getUsableSpace
   */
   getUsableSpace(): number;
 }
@@ -476,9 +489,8 @@ export class PrintWriter {
   print(obj: any): void;
   /**
    * Terminates the current line by writing the line separator string.  The
-   * line separator string is defined by the system property
-   * `line.separator`, and is not necessarily a single newline
-   * character (`'\n'`).
+   * line separator is {@link System#lineSeparator()} and is not necessarily
+   * a single newline character (`'\n'`).
   */
   println(): void;
   /**
@@ -545,7 +557,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -592,7 +604,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -630,7 +642,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *
@@ -669,7 +681,7 @@ export class PrintWriter {
    *         extra arguments are ignored.  The number of arguments is
    *         variable and may be zero.  The maximum number of arguments is
    *         limited by the maximum dimension of a Java array as defined by
-   *         The Java™ Virtual Machine Specification.
+   *         The Java Virtual Machine Specification.
    *         The behaviour on a
    *         `null` argument depends on the conversion.
    *

package/types/java.net.d.ts

@@ -42,7 +42,7 @@ declare module 'java.net' {
  * A URL may have appended to it a "fragment", also known
  * as a "ref" or a "reference". The fragment is indicated by the sharp
  * sign character "#" followed by more characters. For example,
- *  *     http://java.sun.com/index.html#chapter1
+ *  *     http://www.example.com/index.html#chapter1
  * 
  * 
  * This fragment is not technically part of the URL. Rather, it
@@ -55,13 +55,13 @@ declare module 'java.net' {
  * which contains only enough information to reach the resource
  * relative to another URL. Relative URLs are frequently used within
  * HTML pages. For example, if the contents of the URL:
- *  *     http://java.sun.com/index.html
+ *  *     http://www.example.com/index.html
  * 
  * contained within it the relative URL:
  *  *     FAQ.html
  * 
  * it would be a shorthand for:
- *  *     http://java.sun.com/FAQ.html
+ *  *     http://www.example.com/FAQ.html
  * 
  * 
  * The relative URL need not specify all the components of a URL. If
@@ -89,6 +89,26 @@ declare module 'java.net' {
  * used, but only for HTML form encoding, which is not the same
  * as the encoding scheme defined in RFC2396.
  *
+ * @apiNote
+ *
+ * Applications working with file paths and file URIs should take great
+ * care to use the appropriate methods to convert between the two.
+ * The {@link Path#of(URI)} factory method and the {@link File#File(URI)}
+ * constructor can be used to create {@link Path} or {@link File}
+ * objects from a file URI. {@link Path#toUri()} and {@link File#toURI()}
+ * can be used to create a {@link URI} from a file path, which can be
+ * converted to URL using {@link URI#toURL()}.
+ * Applications should never try to {@linkplain #URL(String, String, String)
+ * construct} or {@linkplain #URL(String) parse} a `URL`
+ * from the direct string representation of a `File` or `Path`
+ * instance.
+ * 
+ * Some components of a URL or URI, such as userinfo, may
+ * be abused to construct misleading URLs or URIs. Applications
+ * that deal with URLs or URIs should take into account
+ * the recommendations advised in RFC3986,
+ * Section 7, Security Considerations.
+ *
  * @author  James Gosling
  * @since 1.0
 */
@@ -181,7 +201,7 @@ export class URL {
    * 
    *
    * @return     the contents of this URL.
-   * @exception  IOException  if an I/O exception occurs.
+   * @throws     IOException  if an I/O exception occurs.
    * @see        java.net.URLConnection#getContent()
   */
   getContent(): any;