RemoteIterators (Apache Hadoop Main 3.4.1 API)

java.lang.Object
- org.apache.hadoop.util.functional.RemoteIterators

```
@InterfaceAudience.Public
 @InterfaceStability.Unstable
public final class RemoteIterators
extends Object
```
一组支持转换和过滤的远程迭代器，具有IOStatisticsSource透传功能，并能将迭代器转换为列表/数组，以及对值执行操作。
其目标是使使用lambda表达式转换迭代器结果变得简单直接，同时在此过程中不丢失统计信息，并能将操作链接在一起。
可关闭操作将通过包装其他RemoteIterators的RemoteIterators传递。这是为了支持任何可以关闭以释放持有的连接、文件句柄等的迭代器。除非客户端代码假设RemoteIterator实例可以被关闭，否则这一功能不太可能被广泛使用。添加它是为了以受控方式采用此功能。
一个显著特点是 foreach(RemoteIterator, ConsumerRaisingIOE)方法会在调试级别记录迭代器提供的任何IOStatistics（如果提供了此类统计信息）。如果日志未设置为调试级别，则不会尝试检索和记录，因此除非记录器org.apache.hadoop.fs.functional.RemoteIterators 处于DEBUG级别，否则这是一个零成本功能。
基于S3A列表代码，以及将其他代码迁移到使用迭代列表以获取统计信息的一些工作。

方法摘要

All Methods 静态方法具体方法
修饰符和类型	方法和描述
`static <T> void`	`cleanupRemoteIterator(org.apache.hadoop.fs.RemoteIterator<T> source)` 在迭代后进行清理。
`static <S> org.apache.hadoop.fs.RemoteIterator<S>`	`关闭远程迭代器(org.apache.hadoop.fs.RemoteIterator<S> iterator, Closeable toClose)` 这会在源迭代器支持的Closeable.close()方法之外，额外添加一个关闭操作。
`static <S> org.apache.hadoop.fs.RemoteIterator<S>`	`filteringRemoteIterator(org.apache.hadoop.fs.RemoteIterator<S> iterator, org.apache.hadoop.util.functional.FunctionRaisingIOE<? super S,Boolean> filter)` 从RemoteIterator和过滤函数创建一个RemoteIterator，该函数对每个需要传递的元素返回true。
`static <T> long`	`foreach(org.apache.hadoop.fs.RemoteIterator<T> source, org.apache.hadoop.util.functional.ConsumerRaisingIOE<? super T> consumer)` 对RemoteIterator的所有值应用一个操作。
`static <S> org.apache.hadoop.fs.RemoteIterator<S>`	`haltableRemoteIterator(org.apache.hadoop.fs.RemoteIterator<S> iterator, org.apache.hadoop.util.functional.CallableRaisingIOE<Boolean> continueWork)` 用添加延续探针的迭代器包装一个迭代器。
`static <S,T> org.apache.hadoop.fs.RemoteIterator<T>`	`mappingRemoteIterator(org.apache.hadoop.fs.RemoteIterator<S> iterator, org.apache.hadoop.util.functional.FunctionRaisingIOE<? super S,T> mapper)` 从一个迭代器和一个转换函数创建迭代器。
`static org.apache.hadoop.fs.RemoteIterator<Long>`	`rangeExcludingIterator(long start, long excludedFinish)` A remote iterator which simply counts up, stopping once the value is greater than the value of `excludedFinish`.
`static <T> org.apache.hadoop.fs.RemoteIterator<T>`	`remoteIteratorFromArray(T[] array)` 从数组创建一个远程迭代器。
`static <T> org.apache.hadoop.fs.RemoteIterator<T>`	`remoteIteratorFromIterable(Iterable<T> iterable)` 从java.util.Iterable创建一个远程迭代器 - 例如
`static <T> org.apache.hadoop.fs.RemoteIterator<T>`	`remoteIteratorFromIterator(Iterator<T> iterator)` 从java.util.Iterator创建一个远程迭代器。
`static <T> org.apache.hadoop.fs.RemoteIterator<T>`	`从单例创建远程迭代器(T singleton)` 从单例创建一个迭代器。
`static <T> T[]`	`toArray(org.apache.hadoop.fs.RemoteIterator<T> source, T[] a)` 从RemoteIterator构建一个数组。
`static <T> 列表<T>`	`转换为列表(org.apache.hadoop.fs.RemoteIterator<T> source)` 从RemoteIterator构建列表。
`static <S,T> org.apache.hadoop.fs.RemoteIterator<T>`	`类型转换远程迭代器(org.apache.hadoop.fs.RemoteIterator<S> iterator)` 从一个RemoteIterator创建另一个RemoteIterator，在此过程中进行类型转换。

从java.lang.Object类继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 方法详情
  - remoteIteratorFromSingleton
```
public static  org.apache.hadoop.fs.RemoteIterator remoteIteratorFromSingleton(@Nullable
                                                                                     T singleton)
```
    从单例对象创建迭代器。
    
    类型参数：
    
    T - 类型
    
    参数：
    
    singleton - 实例
    
    返回：
    
    远程迭代器
  - remoteIteratorFromIterator
```
public static  org.apache.hadoop.fs.RemoteIterator remoteIteratorFromIterator(Iterator iterator)
```
    从java.util.Iterator创建一个远程迭代器。
    
    类型参数：
    
    T - 类型
    
    参数：
    
    iterator - 迭代器
    
    返回：
    
    一个远程迭代器
  - remoteIteratorFromIterable
```
public static  org.apache.hadoop.fs.RemoteIterator remoteIteratorFromIterable(Iterable iterable)
```
    从java.util.Iterable（例如列表或其他集合）创建远程迭代器
    
    类型参数：
    
    T - 类型
    
    参数：
    
    iterable - 可迭代对象
    
    返回值：
    
    一个远程迭代器
  - remoteIteratorFromArray
```
public static  org.apache.hadoop.fs.RemoteIterator remoteIteratorFromArray(T[] array)
```
    从数组创建远程迭代器
    
    类型参数：
    
    T - 类型
    
    参数：
    
    array - 数组
    
    返回值：
    
    一个远程迭代器
  - mappingRemoteIterator
```
public static  org.apache.hadoop.fs.RemoteIterator mappingRemoteIterator(org.apache.hadoop.fs.RemoteIterator iterator,
                                                                                 org.apache.hadoop.util.functional.FunctionRaisingIOE mapper)
```
    通过迭代器和转换函数创建一个新的迭代器。
    
    类型参数：
    
    S - 源类型
    
    T - 结果类型
    
    参数：
    
    iterator - 源
    
    mapper - 转换函数
    
    返回值：
    
    一个远程迭代器
  - typeCastingRemoteIterator
```
public static  org.apache.hadoop.fs.RemoteIterator typeCastingRemoteIterator(org.apache.hadoop.fs.RemoteIterator iterator)
```
    从RemoteIterator创建一个RemoteIterator，在此过程中进行类型转换。这有助于解决文件系统API调用中因重载导致的混淆问题（例如listStatusIterator()）
    
    类型参数：
    
    S - 源类型
    
    T - 结果类型
    
    参数：
    
    iterator - 源
    
    返回：
    
    一个远程迭代器
  - filteringRemoteIterator
```
public static  org.apache.hadoop.fs.RemoteIterator filteringRemoteIterator(org.apache.hadoop.fs.RemoteIterator iterator,
                                                                                 org.apache.hadoop.util.functional.FunctionRaisingIOEBoolean> filter)
```
    从一个RemoteIterator和过滤函数创建一个RemoteIterator，该函数对每个需要传递的元素返回true。
    元素在hasNext()方法中被过滤；如果不使用该方法，过滤将在next()调用中按需进行。
    
    类型参数:
    
    S - 类型
    
    参数:
    
    iterator - 源
    
    filter - 过滤器
    
    返回:
    
    一个远程迭代器
  - closingRemoteIterator
```
public static  org.apache.hadoop.fs.RemoteIterator closingRemoteIterator(org.apache.hadoop.fs.RemoteIterator iterator,
                                                                               Closeable toClose)
```
    这会在透传源迭代器支持的Closeable.close()方法基础上，额外添加一个关闭操作。
    
    类型参数：
    
    S - 源类型
    
    参数：
    
    iterator - 源迭代器
    
    toClose - 需要额外关闭的对象
    
    返回值：
    
    一个新的迭代器
  - haltableRemoteIterator
```
public static  org.apache.hadoop.fs.RemoteIterator haltableRemoteIterator(org.apache.hadoop.fs.RemoteIterator iterator,
                                                                                org.apache.hadoop.util.functional.CallableRaisingIOE<Boolean> continueWork)
```
    包装一个迭代器，为其添加继续探测功能。这允许工作快速退出而无需复杂的跳出逻辑
    
    类型参数：
    
    S - 源类型
    
    参数：
    
    iterator - 源
    
    continueWork - 如果返回false将触发快速停止的谓词
    
    返回：
    
    一个新的迭代器
  - rangeExcludingIterator
```
public static org.apache.hadoop.fs.RemoteIterator<Long> rangeExcludingIterator(long start,
                                                                               long excludedFinish)
```
    一个远程迭代器，它简单地向上计数，一旦值大于excludedFinish的值就停止。这主要用于测试或向TaskPool提交工作时。相当于
```
   for(long l = start, l < excludedFinish; l++) yield l;
```
    参数:
    
    start - 起始值
    
    excludedFinish - 排除的结束值
    
    返回:
    
    一个返回[start, finish)范围内长整数的迭代器
  - toList
```
public static  List toList(org.apache.hadoop.fs.RemoteIterator source)
                          throws IOException
```
    从RemoteIterator构建列表
    
    类型参数：
    
    T - 类型
    
    参数：
    
    source - 源迭代器
    
    返回：
    
    值的列表
    
    抛出：
    
    IOException - 如果源RemoteIterator抛出此异常
  - toArray
```
public static  T[] toArray(org.apache.hadoop.fs.RemoteIterator source,
                              T[] a)
                       throws IOException
```
    从RemoteIterator构建数组
    
    类型参数：
    
    T - 类型
    
    参数：
    
    source - 源迭代器
    
    a - 目标数组；如果太小则会创建同类型的新数组
    
    返回值：
    
    值的数组
    
    抛出异常：
    
    IOException - 如果源RemoteIterator抛出该异常
  - foreach
```
public static  long foreach(org.apache.hadoop.fs.RemoteIterator source,
                               org.apache.hadoop.util.functional.ConsumerRaisingIOE consumer)
                        throws IOException
```
    对RemoteIterator的所有值应用操作。如果迭代器是返回非空统计数据的IOStatisticsSource，并且此类的日志级别设置为DEBUG，则操作统计信息将被评估并记录在调试级别。
    返回已处理的条目数，了解这一点很有用，特别是在测试期间或向用户报告值时。
    此操作不会在之后关闭迭代器。
    
    类型参数：
    
    T - 源类型
    
    参数：
    
    source - 迭代器源
    
    consumer - 值的消费者
    
    返回：
    
    处理的元素数量
    
    抛出：
    
    IOException - 如果源RemoteIterator或消费者抛出异常
  - cleanupRemoteIterator
```
public static  void cleanupRemoteIterator(org.apache.hadoop.fs.RemoteIterator source)
```
    迭代后进行清理。如果日志级别为debug，则计算并记录IO统计信息。如果迭代器可关闭，则进行类型转换后清理迭代器
    
    类型参数:
    
    T - 源类型
    
    参数:
    
    source - 迭代器源

类 RemoteIterators

方法摘要

从java.lang.Object类继承的方法

方法详情

remoteIteratorFromSingleton

remoteIteratorFromIterator

remoteIteratorFromIterable

remoteIteratorFromArray

mappingRemoteIterator

typeCastingRemoteIterator

filteringRemoteIterator

closingRemoteIterator

haltableRemoteIterator

rangeExcludingIterator

toList

toArray

foreach

cleanupRemoteIterator