JDK 1.8 API阅读与翻译(1) InputStream

Author: Alex Wang

Date: Feb 22 2019

简述

开始看Java的API文档了,连带着一起翻译了，感觉这样更有印象一些，水平有限，好多东西我都没用过🤦‍♂️，有错误的地方希望各位大佬帮忙指正。先弄常用的部分，我暂时用不到的地方，后面再补着翻。另外可能翻的有点口语化🤦‍♂️

1 InputStream

原文：

public abstract class InputStream extends Object implements Closeable

This abstract class is the superclass of all classes representing an input stream of bytes.

Applications that need to define a subclass of InputStream must always provide a method that returns the next byte of input.

翻译：
抽象类InputStream继承自Object类，是Closeable的实现。这个抽象类是所有代表输入字节流的一个父类。对这个类的应用需要定义一个子类，这个子类中必须包含一个返回输入内容下一个字节的方法。

这个东西的子类：

AudioInputStream、ByteArrayInputStream、FileInputStream、FilterInputStream、FilterInputStream、InputStream、ObjectInputStream、PipedInputStream、SequenceInputStream、StringBufferInputStream.

方法的总结：

方法的详细说明

--
read
--
public abstract int read() throw IO Exception

Read the next byte of data fromn the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned,. This method blocks until input data is availiable, the end of the stream is detected, or an exceotion is thrown.

A subclass must provide an implementation of this method.

Returns:
the next byte of data, or -1 if the end of the stream is reached.

Throws:
IOException - if an I/O error occurs.

--
翻译
--
读取输入流中下一个字节的数据，返回一个0-255之间的整数。如果因为到达输入流末尾而没有可用数据，则返回一个-1。这个方法阻塞直到输入数据可用，到达流的末尾，或者抛出一个异常。

--
read
--
public int read(byte[] b) throw IOException

Reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected ,or an exception is thrown.

If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at the end of the file, the value -1 is returned; otherwise ,at least one byte is read and stored into b.

The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is ,at most equal to the length of b. Let k be the bunber of bytes actually read; these bytes will be stored in elements b[0] through b[k-1],leaving elements b[k] through b[b.length -1] unaffected.

The read(b) method for class InputStream has the same effect as:

read(b,0,b.length)

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 th stream has been reached.

Throws：

IOException - If the first byte cannot be read for any reason other than the end of the file, if the input stream has been closed, or if some other I/O error occurs.

NullPointerException - if b is bull

See Also：

read(byte[],int,int)

--
翻译
--
从输入流中读取一些字节然后储存到缓存数组b中。这个方法将实际读到的字节数作为一个整数来返回。该方法阻塞直到输入数据可用，检测到文件结尾，或者抛出一个异常。

如果缓存数组b的长度为0,那么这个方法不会读任何东西，并且返回一个0；此外，这个方法会尝试去读至少一个字节的数据。如果因为已经读到了文件末尾而没有字节可读，这个方法会返回一个-1；此外，它会存储至少一个字节的数据到数组b中。

第一个被读到的字节会被存在b[0]里，下一个是b[1]，以此类推。这个方法最多能读到b.length的字节。这里定义k是实际读到的字节数；这些字节会被存储在b[0] - b[k-1]这些元素中，而数组b中剩下的部分不被影响。

参数：

b - 存储读取数据的缓存。

返回值：

这个方法返回读取到缓存中的总字节数，或者读到文件末尾的时候返回-1.

抛出：

IOException 当这个流中的第一个字节因为不是到达文件末尾而无法读取时抛出这个异常，或者是因为这个流被关闭了，再或者是其他的I/O 错误发生。

NullPointerException - 如果b是null，会报这个错

--
read
--
public int read(byte[] b, int off, int len) throw IOException

Reads up to len bytes of data from the input stream into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read. The number of bytes actually read ist return as an integer.

The method blocks until input data is available, end of file is detected ,or an exception is throw.

If len is zero,m then no byt4es are read and 0 is returned; otherwise, there is an attempt ro read at least one byte. If no byte is avaliasble because the stream is at the end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte is stored into element b[off], the next one into b[off + 1],and so on. The number of bytes read is , at most , equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off + k -1], leaving elements b[off + k] through b[off + len] through b[b.length -1] are unaffected.

In every case, elements b[0] through b[off] and elements b[off + len] through b[b.length -1] are uneffected.

The read(b, off, len) method for class InputStream simply calls the method read() repeatedly. If the first such call results in an IoException, that exception is returned fromn the call to the read(b,off,len) method. If any subsequent call to read() results in a IOException, the exception is caught and treated as if it were end of file; the bytes read up to that point are stored into b and the number of bytes read before the exception occured is returned. The default implementation of this method blocks until the requested amount of input data len has been read, end of file is detected, or an exception is thrown. Subclasses are encouraged to provide a more efficient implementation of this method.

Parameters:

b - the buffer intu which the data is read.

off - the start offset in array b at which the data is wrirtten.

len - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - If the first byte cannot be read for any reason other than end of file, or if the input stream has been closed, or if some other I/O error occurs.

NullPointerException - If b is null.

IndexOutOfBoundsExceotion - If off is negative, len is negative, or len is greater than b.length -off

See Also:
read()

--
翻译
--
将输入流中最多长度为len字节的数据读入一个字节数组中。 这个方法会尝试去读取长度有len字节的数据，但是也可能读一个比len小的长度。实际读区的字节数会作为一个整数被返回。

这个方法阻塞直到数据可用，或者读到了文件末尾，或者抛出异常。

如果len等于0，这个方法不会读取任何数据，并且返回一个0；此外，它会尝试去读取至少一个字节的数据。如果读到了文件末尾，这个方法会返回一个-1；此外会有至少一个字节的数据被存在数组中。

第一个被读取的字节会被存储在b[off]中，下一个会被存在b[off+1]，以此类推。能读的最大字节数等于len。定义k为实际读取到的字节数；这些字节会被存储在b[off] - b[off+k-1]中，数组中b[off+len]至b[b.length-1]这些元素不受影响。

在InputStream类中，read(b,off,len)这个方法仅仅是重复调用read()。如果第一次调用的结果是IOException，那么这个异常会被read(b,off,len)方法返回。如果最后调用read()的过程中出现IOException，那么这个异常会被当作文件的结尾；读取到该点的数据都会被存储在数组b中，并且这个方法会返回在这个异常发生之前读取的字节数。这个方法的默认实现会阻塞[这有点说不通啊🤦‍♂️]，直到长度为len的输入数据被读取了，或者读到了文件的结尾，或者抛出一个异常。Java鼓励开发者在子类中提供这个方法更有效的实现。

参数：

b - 存储读取数据的缓存。

off - 写入数据到数组b时的偏移量。

len - 可读取字节数的最大值。

--
skip
--
public long skip(long n) throw IOException

Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes, possibly 0. This may result from any of a number of conditions l reaching end of tfile beafore n bytes have been skipped is only one possibility. The actual numnber of bytes skipped is returned. If n is negative, the skip method for class InputStream alaways returns 0, and no bytes are skipped. Subclasses may handle the negative value differently.

The skip method of this class creates a byte array and then repeatedly reads into it until n bytes habe been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method. For instance, the implementation may depend on the ability to seek.

Parameters：

n - the number of bytes to be skipped.

Returns：

the actual number of bytes skipped.

Throws:

IOException - if the stream does not support seek, or if some other I/O error occurs.

--
翻译
--
在这个输入流中跳过并放弃n个字节的数据。这个skip方法可能由于一些原因跳过数目较小的字节，可能是0[这块翻译不太通顺🤦‍♂️]。它可能因为很多条件而发生；到达文件结尾之前的n个字节被跳过只是一种情况。该方法会返回实际跳过的字节数。如果n是个负数，那么这个方法会返回0，然后不会有任何字节被跳过。子类可以用不同的方法来处理负数。

InputStream类中的这个方法会创建一个长度为a的字节数组，并且重复将数据读入这个数组，直到读取了n个字节或者读到了文件的结尾。Java鼓励开发者在子类中用更有效的方法去实现这个方法。举个栗子🌰，这个实现也许可以取决于查找的能力。[觉得好别扭🤦‍♂️]

参数：

n - 被跳过的字节数。

Returns：

该方法返回实际跳过的字节数

Throws：

IOException - 如果这个流不支持查找，则会抛出IOException这个错误，或则其他I/O错误发生的时候。

--
available
--
public int available() throws IOException

Returns an estimate of the number of 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. The next invocation might be the same thread or another thread. A single read or skip of this many bytes will not block, but may read or skip fewer bytes.

Note that while some implementations of InputStream will return the total number of bytes in the stream, many will not. It is never correct to use the return value of this method to allocate a buffer intended to hold all data in this stream.

A subclass' implementation of this method may choose to throw an IOException if this input stream has been closed by invoking the close() method.

The available method for class InputStream always returns 0.

This method should be overridden by subclasses.

Returns：

an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking or 0 when it reaches the end of the input stream.

Throws：

IOException - if an I/O error occurs.

--
翻译
--
这个方法返回在输入流中对可读或者可跳过字节数的一个估计值，而不会阻塞下一个调用这个流的方法。下一个调用可能是同样的线程或者另外一个线程。一次单独的读取或者跳过并不会造成堵塞，但是也许多次读取或者跳过会造成阻塞。（读取和跳过指调用read或skip方法）

注意尽管有一些这个方法的实现会返回这个流中的总字节数，但是这个方法的实现也不会返回总的字节数。使用这个方法的返回值去设置缓存数组的长度来存储流中所有数据是错误的。

一个子类中的这个方法的实现可以在输入流被close()方法关闭时，选择抛出一个IOException异常。

InputStream这个类中的available方法总是返回0；

这个方法应该在子类中被重写。

返回：

返回输入流中可读取或者可跳过字节数的一个估计值，直到读到文件的结尾返回一个0，这个方法不会引起阻塞。

抛出：
IOException - I/O错误发生时抛出该异常。

--
close()
--
public void close() throws IOException

Closes this input stream and releases any system resources associated with the stream.

The close method of InputStream does nothing.

Specified by：

close in interface Closeable

Specified by：

close in interface AutoCloseable

Throws：

IOException - if an I/O error occurs.

--
翻译
--
关闭一个流并且释放所有相关的系统资源

InputStream这个类中的close()方法啥也不做。

--
mark
--
public void mark(int readlimit)

Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

The readlimit arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated.

TGhe general contract of mark is that, if the method markSupported returns true, the stream somehow remembers all the bytes read after the call to mark and stands ready to suypply those same bytes again if and whenever the method reset is called. However, the stream is not required to remember any data at all if more than readlimit bytes are read from the stream before reset is called.

Marking a closed stream should not habe any effect on the stream.

The mark method of InputStream does nothing,.

Parameter：

readlimit - the maximum limit of bytes that can be read before the mark position becomes invalid.

See Also:
reset()

--
翻译
--
这个方法标记现在在输入流中的位置。[感觉有个类似游标的东西，最近我得试试这些方法]。随后调用一个reposition方法可以重新定位到这个流中上次调用mark方法的位置，用这种的方法可以重复读取同样的字节。

readlimit这个参量控制输入流允许在标记位置失效前允许读取的最大字节数。

对于mark这个方法有一个通用的约定，如果markSupported这个方法返回true时，这个流会记住所有调用mark这个方法之后字节，然后准备再次提供相同的字节，在reset这个方法被调用的时候。然而，如果在调用reset这个方法之前从流中读取超过readlimit数量的字节时，这个流根本不需要去记住任何数据。

对于一个关闭的流使用mark方法并没有什么用。

在InputStream这个类中的mark方法也没啥用。

Parameters：

readlimit -在标记位置失效之前可以读区的最大字节数

--
reset
--

public void reset() throws IOException

Repositions this stream to the position at the time the mark method was last called on this input stream.

The general contract of reset is:

1. If the method markSupported returns true, then:

If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown.

If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset.

2. If the method markSupported returns false, then:

The call to reset may throw an IOException.

If an IOException is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the read method depend on the particular type of the input stream.
The method reset for class InputStream does nothing except throw an IOException.

Throws：

IOException - if this stream has not been marked or if the mark has been invalidated.

See Also:

mark(int), IOException

--
翻译
--
把这个流重新定位到mark方法最后一次被调用的地方。

对这个方法有一些常规的约定：

1. 如果markSupported返回true:

如果mark从流创建的时候没有被调用，或者当mark方法被调用时从这个流中读取的字节数大于上次调用mark方法的readlimit的参数，这两种情况都可能抛出IOException.

如果这个IOException没有被抛出，那么流将重置到一个状态以便所有从上次调用mark方法时（在没有调用过mark方法时，流会被定位到文件开始的位置）被读取的数据都会被后续read方法的调用者使用。[后面这句不知道怎么理解🤦‍♂️，等我问了大佬之后再改这里]

2. 如果markSupported方法返回false:

这个调用可能会抛出IOException.

如果IOException没有被抛出，那么这个流会被重新定位到一个修复的状态，这个状态取决于流的特定类型和这个流是怎么被创建的。这些字节会根据流的特定类型提供给后续read方法的调用者使用。

在InputStream这个类中,reset这个方法除了抛出一个IOException之外没别的用。

抛出：

IOException - 如果这个流没有被标记，或者标记失效的情况下，该方法会抛出一个IOException.

--
markSuppported
--
public boolean markSupported()

Tests if this input stream supports the mark and reset methods. Whether or not mark and reset are supported is an invariant property of a particular input stream instance. The markSupported method of InputStream returns false.

Return：

true if this stream instance supports the mark and reset methods; false otherwise.

See Also：
mark(int),reset()

--
翻译
--
该方法用于测试流是否支持mark和reset方法。是否支持mark和reset是特定输入流实例的一个不变属性。在InputStream这个类中，该方法返回false。

返回：
如果这个流的实例支持mark和reset方法，返回true；其他情况返回false。