Module java.base

Package java.nio.file

Interface WatchKey

       public interface WatchKey
      

代表使用watchable对象在WatchService中注册的令牌。

当一个可观察对象与观察服务注册时，将创建一个观察键。该键保持有效直到：

1. 通过显式调用其cancel方法取消，或
2. 由于对象不再可访问而隐式取消，或
3. 通过关闭观察服务close。

观察键具有状态。初始创建时，该键被称为准备就绪。当检测到事件时，该键被标记并排队，以便通过调用观察服务的poll或take方法检索。一旦标记，键将保持在此状态，直到调用其reset方法将键返回到准备就绪状态。在键处于标记状态时检测到的事件将被排队，但不会导致将键重新排队以从观察服务中检索。通过调用键的pollEvents方法检索事件。该方法检索并删除为对象累积的所有事件。初始创建时，观察键没有待处理事件。通常在键处于标记状态时检索事件，导致以下习语：

    for (;;) {
        // 检索键
        WatchKey key = watcher.take();

        // 处理事件
        for (WatchEvent<?> event: key.pollEvents()) {
            :
        }

        // 重置键
        boolean valid = key.reset();
        if (!valid) {
            // 对象不再注册
        }
    }

观察键可安全用于多个并发线程。当有多个线程从观察服务中检索标记的键时，应注意确保只在对象的事件已被处理后才调用reset方法。这确保了一次只有一个线程处理对象的事件。

自：

1.7

Method Summary

Modifier and Type	Method	Description
void	cancel()	取消与观察服务的注册。
boolean	isValid()	告知此观察键是否有效。
List<WatchEvent<?>>	pollEvents()	检索并删除此观察键的所有待处理事件，返回检索到的事件的List。
boolean	reset()	重置此观察键。
Watchable	watchable()	返回创建此观察键的对象。

Method Details

isValid

             boolean isValid()
            

告知此观察键是否有效。

观察键在创建时有效，并保持有效直到被取消，或其观察服务关闭。

返回：

如果此观察键有效，则返回true

pollEvents

             List<WatchEvent<?>> pollEvents()
            

检索并删除此观察键的所有待处理事件，返回检索到的事件的List。

请注意，如果没有待处理事件，此方法不会等待。

返回：

检索到的事件列表；可能为空

reset

             boolean reset()
            

重置此观察键。

如果此观察键已被取消或此观察键已处于准备就绪状态，则调用此方法不会产生任何效果。否则，如果对象有待处理事件，则此观察键将立即重新排队到观察服务。如果没有待处理事件，则观察键将置于准备就绪状态，并保持在该状态，直到检测到事件或观察键被取消。

返回：

如果观察键有效且已重置，则返回true，如果观察键无法重置因为不再有效，则返回false

cancel

             void cancel()
            

取消与观察服务的注册。返回时，观察键将无效。如果观察键已排队等待从观察服务中检索，则它将保留在队列中直到被移除。待处理事件（如果有）仍然待处理，并且在取消键后可以通过调用pollEvents方法检索。

如果此观察键已被取消，则调用此方法不会产生任何效果。一旦取消，观察键将永远无效。

watchable

             Watchable watchable()
            

返回创建此观察键的对象。即使在取消键后，此方法仍将返回对象。

由于WatchService旨在直接映射到本机文件事件通知功能（如果可用），因此关于如何监视已注册对象的许多细节高度依赖于具体实现。例如，当监视目录进行更改时，如果目录在文件系统中移动或重命名，则不能保证观察键将被取消，因此通过此方法返回的对象可能不再是目录的有效路径。

返回：

创建此观察键的对象