jdk-sandbox: comparison src/java.base/share/classes/java/io/FileInputStream.java

equal deleted inserted replaced

-:13588c901957
+:9cf78a70fa4f
 /*
-* Copyright (c) 1994, 2018, Oracle and/or its affiliates. All rights reserved.
+* Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 import java.nio.channels.FileChannel;
 import sun.nio.ch.FileChannelImpl;
 /**
-* A <code>FileInputStream</code> obtains input bytes
+* A {@code FileInputStream} obtains input bytes
 * from a file in a file system. What files
 * are  available depends on the host environment.
 *
-* <p><code>FileInputStream</code> is meant for reading streams of raw bytes
+* <p>{@code FileInputStream} is meant for reading streams of raw bytes
 * such as image data. For reading streams of characters, consider using
-* <code>FileReader</code>.
+* {@code FileReader}.
 *
 * @apiNote
 * To release resources used by this stream {@link #close} should be called
 * directly or by try-with-resources. Subclasses are responsible for the cleanup
 * of resources acquired by the subclass.
 private final Object closeLock = new Object();
 private volatile boolean closed;
 /**
-* Creates a <code>FileInputStream</code> by
+* Creates a {@code FileInputStream} by
 * opening a connection to an actual file,
-* the file named by the path name <code>name</code>
+* the file named by the path name {@code name}
-* in the file system.  A new <code>FileDescriptor</code>
+* in the file system.  A new {@code FileDescriptor}
 * object is created to represent this file
 * connection.
 * <p>
 * First, if there is a security
-* manager, its <code>checkRead</code> method
+* manager, its {@code checkRead} method
-* is called with the <code>name</code> argument
+* is called with the {@code name} argument
 * as its argument.
 * <p>
 * If the named file does not exist, is a directory rather than a regular
 * file, or for some other reason cannot be opened for reading then a
-* <code>FileNotFoundException</code> is thrown.
+* {@code FileNotFoundException} is thrown.
 *
 * @param      name   the system-dependent file name.
-* @exception  FileNotFoundException  if the file does not exist,
+* @throws     FileNotFoundException  if the file does not exist,
-*                   is a directory rather than a regular file,
+*             is a directory rather than a regular file,
-*                   or for some other reason cannot be opened for
+*             or for some other reason cannot be opened for
-*                   reading.
+*             reading.
-* @exception  SecurityException      if a security manager exists and its
+* @throws     SecurityException      if a security manager exists and its
-*               <code>checkRead</code> method denies read access
+*             {@code checkRead} method denies read access
-*               to the file.
+*             to the file.
 * @see        java.lang.SecurityManager#checkRead(java.lang.String)
 */
 public FileInputStream(String name) throws FileNotFoundException {
 this(name != null ? new File(name) : null);
 }
 /**
-* Creates a <code>FileInputStream</code> by
+* Creates a {@code FileInputStream} by
 * opening a connection to an actual file,
-* the file named by the <code>File</code>
+* the file named by the {@code File}
-* object <code>file</code> in the file system.
+* object {@code file} in the file system.
-* A new <code>FileDescriptor</code> object
+* A new {@code FileDescriptor} object
 * is created to represent this file connection.
 * <p>
 * First, if there is a security manager,
-* its <code>checkRead</code> method  is called
+* its {@code checkRead} method  is called
-* with the path represented by the <code>file</code>
+* with the path represented by the {@code file}
 * argument as its argument.
 * <p>
 * If the named file does not exist, is a directory rather than a regular
 * file, or for some other reason cannot be opened for reading then a
-* <code>FileNotFoundException</code> is thrown.
+* {@code FileNotFoundException} is thrown.
 *
 * @param      file   the file to be opened for reading.
-* @exception  FileNotFoundException  if the file does not exist,
+* @throws     FileNotFoundException  if the file does not exist,
-*                   is a directory rather than a regular file,
+*             is a directory rather than a regular file,
-*                   or for some other reason cannot be opened for
+*             or for some other reason cannot be opened for
-*                   reading.
+*             reading.
-* @exception  SecurityException      if a security manager exists and its
+* @throws     SecurityException      if a security manager exists and its
-*               <code>checkRead</code> method denies read access to the file.
+*             {@code checkRead} method denies read access to the file.
 * @see        java.io.File#getPath()
 * @see        java.lang.SecurityManager#checkRead(java.lang.String)
 */
 public FileInputStream(File file) throws FileNotFoundException {
 String name = (file != null ? file.getPath() : null);
 open(name);
 FileCleanable.register(fd);       // open set the fd, register the cleanup
 }
 /**
-* Creates a <code>FileInputStream</code> by using the file descriptor
+* Creates a {@code FileInputStream} by using the file descriptor
-* <code>fdObj</code>, which represents an existing connection to an
+* {@code fdObj}, which represents an existing connection to an
 * actual file in the file system.
 * <p>
-* If there is a security manager, its <code>checkRead</code> method is
+* If there is a security manager, its {@code checkRead} method is
-* called with the file descriptor <code>fdObj</code> as its argument to
+* called with the file descriptor {@code fdObj} as its argument to
 * see if it's ok to read the file descriptor. If read access is denied
-* to the file descriptor a <code>SecurityException</code> is thrown.
+* to the file descriptor a {@code SecurityException} is thrown.
 * <p>
-* If <code>fdObj</code> is null then a <code>NullPointerException</code>
+* If {@code fdObj} is null then a {@code NullPointerException}
 * is thrown.
 * <p>
-* This constructor does not throw an exception if <code>fdObj</code>
+* This constructor does not throw an exception if {@code fdObj}
 * is {@link java.io.FileDescriptor#valid() invalid}.
 * However, if the methods are invoked on the resulting stream to attempt
-* I/O on the stream, an <code>IOException</code> is thrown.
+* I/O on the stream, an {@code IOException} is thrown.
 *
 * @param      fdObj   the file descriptor to be opened for reading.
 * @throws     SecurityException      if a security manager exists and its
-*                 <code>checkRead</code> method denies read access to the
+*             {@code checkRead} method denies read access to the
-*                 file descriptor.
+*             file descriptor.
 * @see        SecurityManager#checkRead(java.io.FileDescriptor)
 */
 public FileInputStream(FileDescriptor fdObj) {
 SecurityManager security = System.getSecurityManager();
 if (fdObj == null) {
 /**
 * Reads a byte of data from this input stream. This method blocks
 * if no input is yet available.
 *
-* @return     the next byte of data, or <code>-1</code> if the end of the
+* @return     the next byte of data, or {@code -1} if the end of the
 *             file is reached.
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
 */
 public int read() throws IOException {
 return read0();
 }
 private native int read0() throws IOException;
 /**
 * Reads a subarray as a sequence of bytes.
-* @param b the data to be written
+* @param     b the data to be written
-* @param off the start offset in the data
+* @param     off the start offset in the data
-* @param len the number of bytes that are written
+* @param     len the number of bytes that are written
-* @exception IOException If an I/O error has occurred.
+* @throws    IOException If an I/O error has occurred.
 */
 private native int readBytes(byte b[], int off, int len) throws IOException;
 /**
-* Reads up to <code>b.length</code> bytes of data from this input
+* Reads up to {@code b.length} bytes of data from this input
 * stream into an array of bytes. This method blocks until some input
 * is available.
 *
 * @param      b   the buffer into which the data is read.
 * @return     the total number of bytes read into the buffer, or
-*             <code>-1</code> if there is no more data because the end of
+*             {@code -1} if there is no more data because the end of
 *             the file has been reached.
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
 */
 public int read(byte b[]) throws IOException {
 return readBytes(b, 0, b.length);
 }
 /**
-* Reads up to <code>len</code> bytes of data from this input stream
+* Reads up to {@code len} bytes of data from this input stream
-* into an array of bytes. If <code>len</code> is not zero, the method
+* into an array of bytes. If {@code len} is not zero, the method
 * blocks until some input is available; otherwise, no
-* bytes are read and <code>0</code> is returned.
+* bytes are read and {@code 0} is returned.
 *
 * @param      b     the buffer into which the data is read.
-* @param      off   the start offset in the destination array <code>b</code>
+* @param      off   the start offset in the destination array {@code b}
 * @param      len   the maximum number of bytes read.
 * @return     the total number of bytes read into the buffer, or
-*             <code>-1</code> if there is no more data because the end of
+*             {@code -1} if there is no more data because the end of
 *             the file has been reached.
-* @exception  NullPointerException If <code>b</code> is <code>null</code>.
+* @throws     NullPointerException If {@code b} is {@code null}.
-* @exception  IndexOutOfBoundsException If <code>off</code> is negative,
+* @throws     IndexOutOfBoundsException If {@code off} is negative,
-* <code>len</code> is negative, or <code>len</code> is greater than
+*             {@code len} is negative, or {@code len} is greater than
-* <code>b.length - off</code>
+*             {@code b.length - off}
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
 */
 public int read(byte b[], int off, int len) throws IOException {
 return readBytes(b, off, len);
 }
 /**
-* Skips over and discards <code>n</code> bytes of data from the
+* Skips over and discards {@code n} bytes of data from the
 * input stream.
 *
-* <p>The <code>skip</code> method may, for a variety of
+* <p>The {@code skip} method may, for a variety of
 * reasons, end up skipping over some smaller number of bytes,
-* possibly <code>0</code>. If <code>n</code> is negative, the method
+* possibly {@code 0}. If {@code n} is negative, the method
 * will try to skip backwards. In case the backing file does not support
-* backward skip at its current position, an <code>IOException</code> is
+* backward skip at its current position, an {@code IOException} is
 * thrown. The actual number of bytes skipped is returned. If it skips
 * forwards, it returns a positive value. If it skips backwards, it
 * returns a negative value.
 *
 * <p>This method may skip more bytes than what are remaining in the
 * backing file. Attempting to read from the stream after skipping past
 * the end will result in -1 indicating the end of the file.
 *
 * @param      n   the number of bytes to be skipped.
 * @return     the actual number of bytes skipped.
-* @exception  IOException  if n is negative, if the stream does not
+* @throws     IOException  if n is negative, if the stream does not
 *             support seek, or if an I/O error occurs.
 */
 public long skip(long n) throws IOException {
 return skip0(n);
 }
 * blocked when it is merely slow, for example when reading large
 * files over slow networks.
 *
 * @return     an estimate of the number of remaining bytes that can be read
 *             (or skipped over) from this input stream without blocking.
-* @exception  IOException  if this file input stream has been closed by calling
+* @throws     IOException  if this file input stream has been closed by calling
 *             {@code close} or an I/O error occurs.
 */
 public int available() throws IOException {
 return available0();
 }
 * Do not depend on finalization to invoke {@code close};
 * finalization is not reliable and is deprecated.
 * If cleanup of native resources is needed, other mechanisms such as
 * {@linkplain java.lang.ref.Cleaner} should be used.
 *
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
 *
 * @revised 1.4
 * @spec JSR-51
 */
 public void close() throws IOException {
 }
 });
 }
 /**
-* Returns the <code>FileDescriptor</code>
+* Returns the {@code FileDescriptor}
 * object  that represents the connection to
 * the actual file in the file system being
-* used by this <code>FileInputStream</code>.
+* used by this {@code FileInputStream}.
 *
 * @return     the file descriptor object associated with this stream.
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
 * @see        java.io.FileDescriptor
 */
 public final FileDescriptor getFD() throws IOException {
 if (fd != null) {
 return fd;

branch	datagramsocketimpl-branch
changeset 58678	9cf78a70fa4f
parent 52149	0edbbc64393c
child 58679	9c3209ff7550