JDK 1.8 API阅读与翻译(2) FileInputStream
Author: Alex Wang
Date: Feb 28 2019
原文：
public class FileInputStream extends InputStream
A FileInputStream obtains input bytes from a file in a file system. What files are availiable depends on the host environment.
FileInputStream is meant for reading streams of raw bytes such as image data. For reading streams of characters, consider using FileReader.
翻译：
公共类FileInputStream继承InputStream类。一个FileInputStream类包含来自一个文件的输入字节。可用的文件取决于主机的环境。FileInputStream意味着读取输入的生子节像是读取图片数据什么的。对于读取字符流，可以考虑用FileReader类。
Constructor Summary
Constructors
FileInputStream(File file)
Creates a FileInputStream by opening a connection to an actual file, the file named by the File object file in the file system.
FileInputStream(FileDescriptor fdObj)
Creates a FileInputStream by using the file descriptor fdObj, which represents an existing connection to an actual file in the file system.
FileInputStream(String name)
Creates a FileInputStream by opening a connection to a actual file, the file named by the path name name in the file system,.
构造器总结
FileInputStream(File file)
通过打开和实际文件的链接创建一个FileInputStream，这个文件由文件系统中的File对象命名。
FileInputStream(FileDescriptor fdObj)
通过描述符fdObj来创建一个FileInputStream，这个描述符代表一个现成的链接文件系统中文件的链接。
FileInputStream(String name)
通过打开和世界文件的链接创建一个FileInputStream，这个文件由文件系统中的路径名来命名。
Method Summary
| Modifier and Type | Method and Description |
|---|---|
| int | available() Returns an estimate of the number of remaining bytes that can be read(or skipped over) from this input stream without blocking by the next invocation of a method for this input stream. |
| void | close() Closes this file input stream and releases any system resources associated with the stream. |
| protected void | finalized() Ensures that the close method of this file input stream is called when there are no more references to it. |
| FileChannel | getChannel() Returns the unique FileChannel object associated with this file input stream |
| FileDescriptor | getFD() Returns the FileDescriptor object that represents the connection to the actual file in the file system being used by this FileInputStream |
| int | read() Reads a byte of data from this input stream |
| int | read(byte[] b) Reads up to b.length bytes from this input stream into an array of bytes |
| int | read(byte[] b, int off, int len) Reads up to len bytes of data from this input stream into an array of bytes. |
| long | skip(long n) Skips over and discards n bytes of data from the input stream |
| 方法类型 | 方法及其描述 |
|---|---|
| int | available() 从这个输入流中返回一个可读的字节数的估计值（或者可被跳过的），而不会阻塞下一个调用这个输入流的方法。 |
| void | close() 关闭这个输入流并且释放任何相关的系统资源 |
| protected void | finalized() 当这个不会再被引用的时候确保close方法被调用 |
| FileChannel | getChannel() 返回一个唯一的和这个输入流相关的FileChannel对象 |
| FileDescriptor | getFD() 返回描述符，用于描述被这个输入流使用的文件系统中的文件和实际文件的链接 |
| int | read() 读取这个输入流中一个字节的数据 |
| int | read(byte[] b) 在这个输入流读到长度为b字节的数据，并写入缓存数组byte[]中 |
| int | read(byte[] b, int off, int len) 从这个输入流中读取长度为len字节的数据，并把它写入缓存数组b中 |
| long | skip(long n) 在这个流中跳过n个字节的数据 |
Constructor Detail
FileInputStream
public FileInputStream(String name) throws FileNotFoundException
Creates a FileInputStream by opening a connection to an actual file, the file named buy the path name name in the file system. A new FileDescriptor object is created to represent this file connection.
First, if there is a security manager, its checkRead method is called with the name argument as its arguments.
If the named file does not exist, is a directory rather than a regualr file, or for some other reason cannot be open for reading then a FIleNotFoundException is thrown.
Parameters:
name - the system-dependent file name.
Throws:
FileNoeFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be open for reading .
SecurityException - if a security manager exists and its checkRead method denies read access to the file.
See Also:
SecurityManager. checkRead(Java.lang.String)
FileInputStream
通过打开和实际文件的链接创建一个FileInputStream，这个文件由文件系统中的File对象命名。一个新的描述符被创建用来代表这个链接。
首先，如果这有个安全管理器，则它的checkRead方法会被调用，并把name参数当作它自己的参数[没理解这个地方]
如果叫这个名字的文件不存在，这是个目录而不是个普通文件，或者因为其他原因读不了这个文件，方法会抛出一个FileNotFoundException异常。
参数：
name - 系统里面这个文件的名字
抛出：
FileNotFoundException -如果文件不存在，或者输入的文件名是个目录、不是普通文件，亦或者因为其他原因读不了这个东西，那么会抛出这个异常。
SecurityException -如果一个安全管理器存在，然后它的checkRead方法否决了对这个文件的读取。
FileInputStream
public FileInputStream(File file) throws FileNotFoundException
Creates a FileInputStream by opening a connection to an actual file, the file named by the File object file in the file system. A new FileDescriptor object created to represent this file connection.
First, if there is a security manager, its checkRead method is called with the path reapreseneted by the file argument as its argument.
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 FileNotFoundException is thrown.
Parameters:
file - the file to be opened for reading.
Throws:
FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reson cannot be openedf for reading.
SecurityExceptionb - if a security manager exists and its checkRead method denies read access to the file.
See Also:
File.getPath(), SecurityManager.checkRead(java.lang.String)
FileInputStream
通过打开和一个实际文件的链接来创建一个输入流，这个文件以文件系统中File Object的名字来命名。一个新的文件描述符会被创建去代表这个链接。
首先，这会有一个安全管理器，它的checkRead方法会被调用，并且把path这个参数当作自己的参数。
如果这个文件不存，或者这个输入的参数是一个目录而不是一个普通文件，亦或是由于其他原因这个文件打不开，该方法都会抛出一个FileNotFound的异常。
参数：
file - 要读取的文件
抛出：
FileNotFoundException -如果文件不存在，或者输入的文件名是个目录、不是普通文件，亦或者因为其他原因读不了这个东西，那么会抛出这个异常。
SecurityException -如果一个安全管理器存在，然后它的checkRead方法否决了对这个文件的读取。
FileInputStream
public FileInputStream(FileDescriptor fdObj)
Create a FileInputStream by using the file descriptor dfObj , which represents an existing connection to an actual file int he file system.
If there is a security manager, its checkRead method is called with the file descriptor fdObj as its arguments to see if it's ok to read the file descriptor. If read accessis denied to the file descriptor a SecurityException is thrown.
If fdObj is null then a NullPointerException is thrown.
This constructor does not throw an exception if fdObj is invalid. However, if the methods are invoked on the resulting stream to attempt I/O on the stream an IOException is thrown.
Parameters:
fdObj - the file descriptor to be opened for reading.Throws:
SecurityException - if a sevurity manager exists and its checkRead method denies read access to the file descriptor.See Also:
SecurityManager.checkRead(java.io.File.Descriptor)
FileInputStream
通过打开和一个实际文件的链接来创建一个输入流，这个文件以文件系统中File Object的名字来命名。一个新的文件描述符会被创建去代表这个链接。
如果有安全管理器，则使用文件描述符fdObj作为参数调用其checkRead方法，来检查是否可以读取文件描述符。如果对文件描述符拒绝读取访问，则抛出SecurityException。
如果fdObj是空的，那么该方法会抛出一个空指针异常。
如果fbObj是空的，那么构造器不会抛出异常。然而，如果这个结果流上调用方法以尝试对流进行I/O操作，则该方法会抛出IOException。
参数：
fdObj - 要被读取或者打开的文件描述符
抛出：
SecurityException -如果一个安全管理器存在，然后它的checkRead方法否决了对这个文件的读取。
Method Detail
read
public int read() throws IOException
Reads a byte of data from this input stream. This method blocks if no input is yet available.
Specified by:
read in class InputStream
Returns:
the next byte of data, or -1 if the end of the file is reached.
Throws:
IOException - if an I/O error occurs.
read
从输入流中读取一个字节的数据。这个方法阻塞直到没有东西可以读取。
具体说明：
在InputStream类中的read方法
返回：
读取下一个字节中的数据，或者当读到文件结尾的时候返回-1
抛出：
IOException - 当I/O错误发生时。
read
public int read(byte[] b) throws IOException
Reads up to b.length bytes of data from this input stream into an array of bytes. This method blocks until some input is available.
Overrides:
read in class InputStream
Parameters:
b - the buffer into which the data is read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Throws:
IOException - if an I/O error occurs.
See Also:
InputStream.read(bytep[], int, int)
read：
将流中长度为b.length的数据读入字节数组b中。这个方法阻塞直到有数据可读。
重写：
这个方法时InputStream类中read方法的重写。
参数：
b - 读入数据的缓存数组
返回：
返回读入缓存数组中的字节数，或者读到文件结尾的时候返回一个-1。
抛出：
IOException - if an I/O error occurs.
read
public int read(byte[] b, int off, int len) throws IOException
Reads up to len bytes of data from this input stream into an array of bytes. If len is not zero, the method blocks until some input is available; otherwise, no bytes are read and 0 is returned.
Overrides:
read in class InputStream.
Parameters:
b - the buffer into which the data is read.
off - the start offset in the destination array b.
len - the maximum number of byters read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Throws:
NullPointerException - If b is null.
IndexOutOfBoundsException - If off is negative, len is negative, or len is greater than b.length - off.
IOException - if an I/O error occurs.
See Also:
InputStream.read()
Read:
从输入流中读取长度为len字节的数据写入数组b中。如果len不是0，那么这个方法阻塞直到输入流有数据可读；或者，没数据读的时候这个方法返回0.
重写：
这个方法是Input Stream类中read方法的重写。
参数：
b - 存储读取数据的缓存。
off - 写入数据到数组b时的偏移量。
len - 可读取字节数的最大值。
返回：
返回读入数组中数据的字节数，或者在读到文件结尾的时候返回-1.
抛出：
NullPointerException - 如果数组b是null。
IndexOutOfBoundsException - 当off是负数，或者len是负数，或者len比b.length - off大的时候
IOException - 当一个I/O错误发生的时候
Skip
public long skip(long n) throws IOException
Skips over and discards n bytes of data from the input stream.
The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. If 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 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.This method may skip more bytes than what are remaining in the backing file. This produces no exception and the number of bytes skipped may include some number of bytes that were beyond the EOF of the backing file. Attempting to read from the stream after skipping past the end will result in -1 indicating the end of the file.
Overrides:
skip in class InputStream
Parameters:
n - the number of bytes to be skipped.
Returns:
the actual number of bytes skipped.
Throws:
IOException - if n is negative, if the stream does not support seek, or if an I/O error occurs.
Skip
在这个输入流中跳过并放弃n个字节的数据。这个skip方法可能由于一些原因跳过数目较小的字节，可能是0。如果n是个负数，那么这个方法会尝试向后跳过。当后备文件不支持在当前位置向后跳过时，这个方法抛出IOException。该方法返回实际跳过的字节数。如果向前跳过，则返回一个正数；反之，则返回一个负数。
这个方法跳过的字节数可能比后备文件中还剩下的多。这不会产生异常，跳过的字节数可能包括超出后备文件EOF的一些字节数。跳过EOF尝试从文件中读取数据会读到-1。
重写：
这个方法是InputStream类中Skip方法的重写。
参数：
n - 被跳过的字节数。
返回：
该方法返回实际跳过的字节数
抛出：
IOException - 如果这个流不支持查找，则会抛出IOException这个错误，或则其他I/O错误发生的时候。
available
public int available() throws IOException
Returns an estimate of number of remaining bytes that can be read(or skipped over) from this input stream without blocking by the next invocation of a method for this input stream. Returns 0 when the file position is beyond EOF. The next invocation might be the same thread of another thread. A single read or skip of this many bytes will not block, but mat read of skip fewer bytes.
In some cases, a non-blocking read(or read) may appear to be blocked when it is merely slow, for example when reading large files over slow networks.
Overides:
available in class InputStream.
Returns:
an estimate of the number of remaining bytes that can be read (or skipped over) from this input stream without blocking.
Throws:
IOException - if this file input stream has been closed by calling close or an I/O error occurs.
available
返回对输入流中可读取或者可跳过字节的一个估计，这个方法在调用时并不会造成阻塞。它在读到文件末尾时会返回0。下次调用这个方法可能会在同一个线程里或者在不同的线程里面。一个单次的read或者skip不会造成阻塞，但是多次也许会。
重写：
该方法是InputStream类中available方法的重写。
返回：
返回对输入流中可读或者可跳过字节书的一个估计，这个方法不会造成阻塞。
抛出：
IOException - 如果文件的输入流因为调用close方法被关闭了，这个方法会抛出I/O异常。
close
public void close() throws IOException
Closes this file input stream and releases any system resources associated with the stream.
If this stream has an associated channel then the channel is closed as well.
Specified by:
close in interface Closeable.
Specified by:
close in interface AutoCloseable.
Overrides:
close in class InputStream.
Throws:
IOException - if an I/O error occurs.
close
关闭文件输入流并且释放任何相关的系统资源。
如果这个流和一个channel相关，那么这个channel也会被关闭。
详见：
在Closeable接口中的close方法。
详见：
在AutoCloseable接口中的close方法。
重写：
该方法是InputStream类中close方法的重写。
抛出：
IOException - 当发生I/O错误时会抛出IOException
getFD
public final FileDescriptor getFD() throws IOException
Returns the FileDescriptor object that repressents the connection to the actual file in the file system being used by this FileInputStream.
Returns:
the file descriptor object associated with this stream.
Throws:
IOException - if an I/O error occurs.
See Also:
FileDescritpor
返回一个代表实际文件和文件系统中被这个FileInputStream使用的文件之间联系的文件描述符对象。
返回:
返回一个跟这个流相关的文件描述符对象。
抛出：
IOException - 当I/O异常发生时，抛出一个IOException。
getChannel
public FileChannel getChannel()
Returns the unique FileChannel object associated with this file input stream.
The initial position of the returned channel will be equal to the number of bytes read from the file so far. Reading bytes from this stream will increment the channels's position. Changing the channel's position, either explicitly or by reading ,will change this stream's file position.
Returns:
the file channel associated with this file input stream.
Since:
1.4
返回一个和这个输入流关联的唯一的FileChannel对象。
该方法返回通道的初始文件位置将会等于在这个文件中已经读取的字节数。继续从这个文件中读取字节会增加这个通道的位置。不管是直接改变通道的位置或者通过读写改变通道的位置都会导致流在文件中的位置。
返回：
和输入流相关的通道。
finalize
protected void finalized() throws IOException
Ensures that the close method of this file input stream is called when there are no more references to it.
Overrides:
finalized in class Object.
Throws:
IOException - if an I/O error occurs.
See Also:
close()
finalize
确保当文件中没有其他数据可读的时候close方法被调用。
重写：
该方法是Object类中finalize方法的重写。
抛出：
IOException - 当I/O错误发生事，抛出一个IOException.