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類包含來自一個文件的輸入字節(jié)敬锐。可用的文件取決于主機的環(huán)境鼓择。FileInputStream意味著讀取輸入的生子節(jié)像是讀取圖片數(shù)據(jù)什么的。對于讀取字符流蜗元，可以考慮用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,.

構(gòu)造器總結(jié)

FileInputStream(File file)

通過打開和實際文件的鏈接創(chuàng)建一個FileInputStream，這個文件由文件系統(tǒng)中的File對象命名太抓。

FileInputStream(FileDescriptor fdObj)

通過描述符fdObj來創(chuàng)建一個FileInputStream空闲，這個描述符代表一個現(xiàn)成的鏈接文件系統(tǒng)中文件的鏈接。

FileInputStream(String name)

通過打開和世界文件的鏈接創(chuàng)建一個FileInputStream走敌，這個文件由文件系統(tǒng)中的路徑名來命名碴倾。

Method Summary

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

通過打開和實際文件的鏈接創(chuàng)建一個FileInputStream僧须，這個文件由文件系統(tǒng)中的File對象命名。一個新的描述符被創(chuàng)建用來代表這個鏈接项炼。

首先担平，如果這有個安全管理器，則它的checkRead方法會被調(diào)用锭部，并把name參數(shù)當(dāng)作它自己的參數(shù)[沒理解這個地方??]

如果叫這個名字的文件不存在驱闷，這是個目錄而不是個普通文件，或者因為其他原因讀不了這個文件空免，方法會拋出一個FileNotFoundException異常空另。

參數(shù)：

name - 系統(tǒng)里面這個文件的名字

拋出：

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

通過打開和一個實際文件的鏈接來創(chuàng)建一個輸入流墨坚，這個文件以文件系統(tǒng)中File Object的名字來命名秧饮。一個新的文件描述符會被創(chuàng)建去代表這個鏈接。

首先，這會有一個安全管理器盗尸，它的checkRead方法會被調(diào)用柑船，并且把path這個參數(shù)當(dāng)作自己的參數(shù)。

如果這個文件不存泼各，或者這個輸入的參數(shù)是一個目錄而不是一個普通文件鞍时，亦或是由于其他原因這個文件打不開，該方法都會拋出一個FileNotFound的異常扣蜻。

參數(shù)：

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

通過打開和一個實際文件的鏈接來創(chuàng)建一個輸入流，這個文件以文件系統(tǒng)中File Object的名字來命名庇勃。一個新的文件描述符會被創(chuàng)建去代表這個鏈接檬嘀。

如果有安全管理器，則使用文件描述符fdObj作為參數(shù)調(diào)用其checkRead方法责嚷，來檢查是否可以讀取文件描述符鸳兽。如果對文件描述符拒絕讀取訪問，則拋出SecurityException罕拂。

如果fdObj是空的揍异，那么該方法會拋出一個空指針異常。

如果fbObj是空的爆班，那么構(gòu)造器不會拋出異常衷掷。然而，如果這個結(jié)果流上調(diào)用方法以嘗試對流進行I/O操作柿菩，則該方法會拋出IOException戚嗅。

參數(shù)：

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

從輸入流中讀取一個字節(jié)的數(shù)據(jù)懦胞。這個方法阻塞直到?jīng)]有東西可以讀取。

具體說明：

在InputStream類中的read方法

返回：

讀取下一個字節(jié)中的數(shù)據(jù)凉泄，或者當(dāng)讀到文件結(jié)尾的時候返回-1

拋出：

IOException - 當(dāng)I/O錯誤發(fā)生時躏尉。

---

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的數(shù)據(jù)讀入字節(jié)數(shù)組b中。這個方法阻塞直到有數(shù)據(jù)可讀后众。

重寫：

這個方法時InputStream類中read方法的重寫胀糜。

參數(shù)：

b - 讀入數(shù)據(jù)的緩存數(shù)組

返回：

返回讀入緩存數(shù)組中的字節(jié)數(shù)颅拦，或者讀到文件結(jié)尾的時候返回一個-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字節(jié)的數(shù)據(jù)寫入數(shù)組b中教藻。如果len不是0距帅，那么這個方法阻塞直到輸入流有數(shù)據(jù)可讀；或者怖竭，沒數(shù)據(jù)讀的時候這個方法返回0.

重寫：

這個方法是Input Stream類中read方法的重寫锥债。

參數(shù)：

b - 存儲讀取數(shù)據(jù)的緩存陡蝇。

off - 寫入數(shù)據(jù)到數(shù)組b時的偏移量痊臭。

len - 可讀取字節(jié)數(shù)的最大值。

返回：

返回讀入數(shù)組中數(shù)據(jù)的字節(jié)數(shù)登夫，或者在讀到文件結(jié)尾的時候返回-1.

拋出：

NullPointerException - 如果數(shù)組b是null广匙。

IndexOutOfBoundsException - 當(dāng)off是負數(shù)，或者len是負數(shù)恼策，或者len比b.length - off大的時候

IOException - 當(dāng)一個I/O錯誤發(fā)生的時候

---

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個字節(jié)的數(shù)據(jù)鸦致。這個skip方法可能由于一些原因跳過數(shù)目較小的字節(jié)，可能是0涣楷。如果n是個負數(shù)分唾，那么這個方法會嘗試向后跳過。當(dāng)后備文件不支持在當(dāng)前位置向后跳過時狮斗，這個方法拋出IOException绽乔。該方法返回實際跳過的字節(jié)數(shù)。如果向前跳過碳褒，則返回一個正數(shù)折砸；反之，則返回一個負數(shù)沙峻。

這個方法跳過的字節(jié)數(shù)可能比后備文件中還剩下的多睦授。這不會產(chǎn)生異常，跳過的字節(jié)數(shù)可能包括超出后備文件EOF的一些字節(jié)數(shù)摔寨。跳過EOF嘗試從文件中讀取數(shù)據(jù)會讀到-1去枷。

重寫：

這個方法是InputStream類中Skip方法的重寫。

參數(shù)：

n - 被跳過的字節(jié)數(shù)是复。

返回：

該方法返回實際跳過的字節(jié)數(shù)

拋出：

IOException - 如果這個流不支持查找删顶，則會拋出IOException這個錯誤，或則其他I/O錯誤發(fā)生的時候佑笋。

---

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

返回對輸入流中可讀取或者可跳過字節(jié)的一個估計翼闹，這個方法在調(diào)用時并不會造成阻塞。它在讀到文件末尾時會返回0蒋纬。下次調(diào)用這個方法可能會在同一個線程里或者在不同的線程里面猎荠。一個單次的read或者skip不會造成阻塞坚弱，但是多次也許會。

重寫：

該方法是InputStream類中available方法的重寫关摇。

返回：

返回對輸入流中可讀或者可跳過字節(jié)書的一個估計荒叶，這個方法不會造成阻塞。

拋出：

IOException - 如果文件的輸入流因為調(diào)用close方法被關(guān)閉了输虱，這個方法會拋出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

關(guān)閉文件輸入流并且釋放任何相關(guān)的系統(tǒng)資源。

如果這個流和一個channel相關(guān)宪睹，那么這個channel也會被關(guān)閉愁茁。

詳見：

在Closeable接口中的close方法。

詳見：

在AutoCloseable接口中的close方法亭病。

重寫：

該方法是InputStream類中close方法的重寫鹅很。

拋出：

IOException - 當(dāng)發(fā)生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

---

返回一個代表實際文件和文件系統(tǒng)中被這個FileInputStream使用的文件之間聯(lián)系的文件描述符對象。

返回:

返回一個跟這個流相關(guān)的文件描述符對象罪帖。

拋出：

IOException - 當(dāng)I/O異常發(fā)生時促煮，拋出一個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

---

返回一個和這個輸入流關(guān)聯(lián)的唯一的FileChannel對象整袁。

該方法返回通道的初始文件位置將會等于在這個文件中已經(jīng)讀取的字節(jié)數(shù)菠齿。繼續(xù)從這個文件中讀取字節(jié)會增加這個通道的位置。不管是直接改變通道的位置或者通過讀寫改變通道的位置都會導(dǎo)致流在文件中的位置坐昙。

返回：

和輸入流相關(guān)的通道绳匀。

---

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

確保當(dāng)文件中沒有其他數(shù)據(jù)可讀的時候close方法被調(diào)用。

重寫：

該方法是Object類中finalize方法的重寫民珍。

拋出：

IOException - 當(dāng)I/O錯誤發(fā)生事襟士，拋出一個IOException.