From 18d9db85c4366f69b992cda7714a44bc28905431 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=BD=97=E7=A5=A5?= <1366971433@qq.com>
Date: Mon, 20 Apr 2020 15:50:13 +0800
Subject: [PATCH] Java NIO
---
README.md | 16 +-
notes/Java_NIO.md | 734 ++++++++++++++++++--------------
pictures/java_nio.pptx | Bin 65274 -> 70313 bytes
pictures/nio_channel_buffer.png | Bin 0 -> 6308 bytes
pictures/nio_chat_group.png | Bin 68080 -> 40608 bytes
pictures/nio_selector.png | Bin 0 -> 13173 bytes
6 files changed, 424 insertions(+), 326 deletions(-)
create mode 100644 pictures/nio_channel_buffer.png
create mode 100644 pictures/nio_selector.png
diff --git a/README.md b/README.md
index bebcc34..93601c2 100644
--- a/README.md
+++ b/README.md
@@ -34,19 +34,19 @@
JConsole、VisualVM 、监控本地进程、监控远程进程
-7. IO、NIO、AIO
+7. [Java NIO 核心组件详解](notes/Java_NIO.md)
-8. Socket 网络编程系列
+ 缓冲区 Buffer、通道 Channel、选择器 Selector、实现多人聊天室
-9. 高性能网络框架 Netty
+8. 高性能网络框架 Netty
+
+9. [Tomcat 架构解析](notes/Tomcat_架构解析.md)
+
+ 核心组件、连接器、多层容器、请求处理流程、程序启动过程、类加载器
10. Java 集合类源码解析
-11. [Tomcat 架构解析](notes/Tomcat_架构解析.md)
-
- 核心组件、连接器、多层容器、请求处理流程、程序启动过程、类加载器
-
-12. 函数式编程
+11. 函数式编程
diff --git a/notes/Java_NIO.md b/notes/Java_NIO.md
index ec8353a..d586065 100644
--- a/notes/Java_NIO.md
+++ b/notes/Java_NIO.md
@@ -1,18 +1,95 @@
-## 一、Buffer
+# Java NIO
-### 1.1 缓冲区属性
+
-
+## 一、简介
-所有缓冲区都直接或间接继承自 Buffer 抽象类，Buffer 中定义了缓冲区的四个基本属性：
+Java NIO 是 JDK 1.4 中引入的新的 IO 方式，它主要包含 Buffer、Channel、Selector 这三个核心的组件，它与传统 IO 的区别如下：
+
+
+
+ | NIO |
+ IO |
+
+
+ | 面向缓冲 |
+ 面向流 |
+
+
+ | 同步非阻塞 |
+ 同步阻塞 |
+
+
+ | 多路复用（选择器） |
+ 无 |
+
+
+
+### 1.1 面向缓冲
+
+传统的 IO 是面向流的，传统 IO 每次从流中读取一个或者多个字节，直至读取完所有的字节。而 NIO 是面向缓冲区的，所有的读写操作都需要通过 Buffer 来完成，数据会被先写入 Buffer 中，然后再进行处理，Buffer 提供了多种方法用于操纵其中的数据，因此其在操作上更加灵活，读取速度也更加快。
+
+### 1.2 同步非阻塞
+
+传统 IO 的流都是单向的，因此它们需要分为 Input Stream 和 Output Stream。而 NIO 中的 Channel 则是双向的，数据可以从 Channel 读到 Buffer 中，也可以从 Buffer 写到 Channel：
+
+ 
+
+
+> 注意：从 Channel 写入到 Buffer 执行的是 read 方法，而从 Buffer 写出到 Channel 执行的是 write 方法。
+
+Channel 可以设置为非阻塞模式，此时当 Channel 从 Buffer 中读取数据时，如果有待读取的数据则返回该数据；如果没有待读取的数据，对应的方法也不会阻塞，而是直接返回。
+
+### 1.3 多路复用
+
+Java NIO 通过 Reactor 模型实现了 IO 的多路复用，可以在一个线程上通过一个选择（Selector）使用轮询的方式去监听多个通道 Channel 上注册的事件，从而在一个线程上就能实现对多个 Channel 的处理：
+
+ 
+
+
+
+
+## 二、Buffer
+
+### 2.1 缓冲区属性
+
+ 
+
+
+所有缓冲区（ByteBuffer、FloatBuffer、IntBuffer、DoubleBuffer、ShortBuffer、LongBuffer、CharBuffer、MappedByteBuffer）都直接或间接继承自 Buffer 抽象类，Buffer 中定义了缓冲区的四个基本属性：
```java
public abstract class Buffer {
-
- private int mark = -1;
- private int position = 0;
- private int limit;
+
private int capacity;
+ private int limit;
+ private int position = 0;
+ private int mark = -1;
...
}
```
@@ -22,7 +99,7 @@ public abstract class Buffer {
+ **位置 (Position)**：下一个待操作元素的索引。
+ **标记 (Mark)**：标记位置。通过 `mark()` 方法可以让 mark 等于当前 position；之后通过 `reset()` 方法可以让 position 恢复到标记位置。
-### 1.2 创建缓冲区
+### 2.2 创建缓冲区
通常可以通过以下两种方法来创建缓冲区：
@@ -39,7 +116,7 @@ char[] chars = new char[100];
CharBuffer buffer = CharBuffer.wrap(chars);
```
-实际上缓冲区内部就是通过数组来存储元素，以 CharBuffer 为例，它的内部维持有一个名为 `hb` 的数组，用来存放实际的元素：
+实际上，在缓冲区内部就是通过数组来存储元素，以 CharBuffer 为例，它的内部维持有一个名为 `hb` 的数组，用来存放实际的元素：
```java
public abstract class CharBuffer extends Buffer implements Comparable, Appendable, CharSequence, Readable
@@ -51,9 +128,10 @@ public abstract class CharBuffer extends Buffer implements Comparable 
-### 1.3 操作缓冲区
+
+### 2.3 操作缓冲区
**1. put()**
@@ -72,7 +150,8 @@ put(char[] src, int offset, int length)
当我们向 Buffer 中添加数据后，position 属性也会随之变动：
-
+ 
+
**2. get()**
@@ -105,31 +184,36 @@ buffer.clear();
当使用 `filp()` 将 Buffer 由写模式切换到读模式后：position 属性会恢复到初始位置，代表从此处开始读取数据；limit 属性也会随之变动，代表我们所能读取数据的上界：
-
+ 
-当我们再通过 `get()` 方法进行读取时，position 属性会随之移动，position 和 limit 之间的数据就是待处理的数据：
-
+当我们再通过 `get()` 方法进行读取时，position 属性会随之移动，position 和 limit 之间就是待处理的数据：
+
+ 
+
**4. hasRemaining()**
-`hasRemaining()` 用于判断当前的 position 是否小于 limit：如果 position 小于 limit，则返回 true，代表仍存在待处理的数据。
+`hasRemaining()` 用于判断当前的 position 是否小于 limit：如果 position 小于 limit，则返回 true，代表仍有待处理的数据。
**5. clear()**
-将 position 设置为 0，并将 limit 设置为 capacity 的大小，从而让缓冲区恢复到初始状态。此时缓冲区的状态如下：
+`clear()` 并不会真的清除缓冲区中的数据，它只是将 position 设置为 0，并将 limit 设置为 capacity 的大小，从而让缓冲区恢复到初始状态：
-
+ 
+
+当有新的数据写入时，新的数据会覆盖原有位置上的数据。
**6. compact()**
用于压缩缓冲区，即将数组中待处理的数据复制到头部。如下所示，会将未读取的 `LL0` 复制到头部：
-
+ 
-需要注意的是这里执行的是复制操作，而不是移动操作，底层调用的是 `System.arraycopy` 方法，因此原有位置上的数据依然存在。但是由于 position 会移动到未处理数据的下一个位置上，所以不用担心原有位置上的数据会被读取到，原因是你切换到读模式时，原有的 `LO` 数据仍处于 limit 之后：
-
+需要注意的是这里执行的是复制操作，而不是移动操作，底层调用的是 `System.arraycopy` 方法，因此原有位置上的数据依然存在。但由于 position 会移动到未处理数据的下一个位置上，所以不用担心原有位置上的数据会被读取到，原因是你切换到读模式时，原有的 `LO` 数据仍处于 limit 之后：
+
+ 
**7. mark()**
@@ -139,7 +223,7 @@ buffer.clear();
buffer.position(2).mark().position(5).reset().position(); //从位置2移动到位置5，之后又恢复到位置2
```
-### 1.4 复制缓冲区
+### 2.4 复制缓冲区
如果想要对一个已有的缓冲区进行复制，可以有以下三种方法：
@@ -155,15 +239,17 @@ public abstract CharBuffer slice();
- 复制缓冲区的 mark、position、limit、capcaity 属性的初始值与复制时原缓冲区的 mark、position、limit、capcaity 的值相同，但这些属性与原缓冲区的属性相互独立，创建后就不再受原有缓冲区的影响；
- 如果原缓冲区是只读缓冲区或直接缓冲区，则复制缓冲区也将继承这些属性。
-
+ 
+
`asReadOnlyBuffer()` 与 `duplicate()` 类似，但创建的复制缓冲区为只读缓冲区。
`slice()` 也与 `duplicate()` 类似，但创建的复制缓冲区与原缓冲区只共享部分数据元素，并且所有标志位都处于原始状态：
-
+ 
-示例如下：
+
+使用示例如下：
```java
CharBuffer buffer = CharBuffer.allocate(100);
@@ -178,9 +264,9 @@ System.out.println("duplicate:" + duplicate.position() + "," + duplicate.limit()
System.out.println("slice:" + slice.position() + "," + slice.limit()); //slice:0,3
```
-### 1.5 直接缓冲区
+### 2.5 直接缓冲区
-ByteBuffer 支持使用 `allocateDirect` 方法来创建直接缓冲区，示例如下：
+ByteBuffer 支持使用 `allocateDirect()` 方法来创建直接缓冲区，示例如下：
```java
ByteBuffer byteBuffer = ByteBuffer.allocate(100);
@@ -188,13 +274,11 @@ ByteBuffer byteBuffer = ByteBuffer.allocate(100);
+## 三、Channel
+### 3.1 通道基础
-## 二、Channel
-
-### 2.1 通道基础
-
-Channel 接口的定义如下，其中包含了两个基础方法：
+Channel 接口的定义如下，其中定义了两个基础方法：
+ **isOpen()**：判断当前 Channel 是否处于打开状态；
+ **close()**：关闭当前 Channel 。Channel 关闭后，就不能在其上再进行任何 IO 操作，否则将抛出 ClosedChannelException 异常。
@@ -224,11 +308,12 @@ FileInputStream fileInputStream = new FileInputStream(new File("path"));
FileChannel fileChannel = fileInputStream.getChannel();
```
-### 2.2 文件通道
+### 3.2 文件通道
-FileChannel 是一个连接到文件的通道，通过该通道可以完成文件的读写。需要注意的是 FileChannel 无法设置为非阻塞模式，因此它总是运行在阻塞模式下。通过 FileChannel 和 Buffer 可以高效地完成文件的拷贝，示例如下：
+FileChannel 是一个连接到文件的通道，通过该通道可以完成文件的读写。另外 FileChannel 无法设置为非阻塞模式，因为对文件读写操作设置非阻塞并没有什么意义。FileChannel 的使用示例如下：
```java
+// 示例：文件拷贝
try {
FileInputStream inputStream = new FileInputStream(new File("D:\\a.png"));
FileOutputStream outputStream = new FileOutputStream(new File("D:\\b.png"));
@@ -275,7 +360,7 @@ public void close() throws IOException {
}
```
-### 2.3 Channel To Channel
+### 3.3 Channel To Channel
在 Java NIO 中，如果两个 Channel 中有一个是 FileChannel，那么可以直接将数据从一个 Channel 传输到另外一个 Channel：
@@ -290,20 +375,20 @@ transferFrom(ReadableByteChannel src, long position, long count)
```java
try {
- FileInputStream inputStream = new FileInputStream(new File("D:\\a.png"));
- FileOutputStream outputStream = new FileOutputStream(new File("D:\\b.png"));
- FileChannel inChannel = inputStream.getChannel();
- FileChannel outChannel = outputStream.getChannel();
- inChannel.transferTo(0,inChannel.size(),outChannel); //使用transferTo实现
- // outChannel.transferFrom(inChannel, 0, inChannel.size()); //使用transferFrom实现
- inputStream.close();
- outputStream.close();
+ FileInputStream inputStream = new FileInputStream(new File("D:\\a.png"));
+ FileOutputStream outputStream = new FileOutputStream(new File("D:\\b.png"));
+ FileChannel inChannel = inputStream.getChannel();
+ FileChannel outChannel = outputStream.getChannel();
+ inChannel.transferTo(0,inChannel.size(),outChannel); //使用transferTo实现
+ // outChannel.transferFrom(inChannel, 0, inChannel.size()); //使用transferFrom实现
+ inputStream.close();
+ outputStream.close();
} catch (IOException e) {
- e.printStackTrace();
+ e.printStackTrace();
}
```
-### 2.4 Scatter/Gather
+### 3.4 Scatter/Gather
Java NIO 支持 scatter 和 gather 操作：
@@ -320,7 +405,8 @@ fileInputStream.getChannel().read(buffers);
此时 Channel 中的数据会依次写入到 Buffer01， Buffer02， Buffer03 上。Scatter 通常用于固定长度数据的处理，假设一个数据单元由 header，body，footer 三部分组成，并且每部分的长度都是固定的，此时通过 Scatter 操作，每一组数据的 header，body，footer 都会分别固定地写到 Buffer01， Buffer02， Buffer03 上，此时就可以对每个 Buffer 应用不同的处理逻辑：
-
+ 
+
+ **聚集 (gather)**：将多个 Buffer 中的数据依次写入到同一个 Channel 上。示例如下：
@@ -333,15 +419,17 @@ ByteBuffer[] buffers = new ByteBuffer[]{buffer01, buffer02, buffer03};
fileInputStream.getChannel().read(buffers);
```
-
+ 
-### 2.5 Pipe
-Java 提供了 Pipe 类用于在不同线程之间传递数据：
+### 3.5 Pipe
-
+Java NIO 还提供了 Pipe 管道用于在不同线程之间传递数据：
-Pipe 管道可以通过 Pipe 的静态方法 `open()` 来创建：
+ 
+
+
+Pipe 管道可以通过 Pipe 类的静态方法 `open()` 来创建：
```java
Pipe pipe = Pipe.open();
@@ -349,7 +437,7 @@ Pipe pipe = Pipe.open();
创建完成后可以通过其 `sink()` 和 `source()` 方法来创建对应的 SinkChannel 和 SourceChannel：
-```shell
+```java
Pipe.SinkChannel sinkChannel = pipe.sink();
Pipe.SourceChannel sourceChannel = pipe.source();
```
@@ -359,44 +447,44 @@ SinkChannel 和 SourceChannel 的使用与基本的 Channel 类似，示例如
```java
Pipe pipe = Pipe.open();
new Thread(() -> {
- try {
- Pipe.SinkChannel sink = pipe.sink();
- ByteBuffer buffer = ByteBuffer.allocate(1024);
- buffer.put("HelloWorld".getBytes());
- buffer.flip();
- while (buffer.hasRemaining()) {
- // 将数据写入SinkChannel
- sink.write(buffer);
- }
- sink.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
+ try {
+ Pipe.SinkChannel sink = pipe.sink();
+ ByteBuffer buffer = ByteBuffer.allocate(1024);
+ buffer.put("HelloWorld".getBytes());
+ buffer.flip();
+ while (buffer.hasRemaining()) {
+ // 将数据写入SinkChannel
+ sink.write(buffer);
+ }
+ sink.close();
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
}).start();
new Thread(() -> {
- try {
- Pipe.SourceChannel source = pipe.source();
- ByteBuffer buffer = ByteBuffer.allocate(1024);
- // 读取SourceChannel中的数据
- while (source.read(buffer) > 0) {
- buffer.flip();
- while (buffer.hasRemaining()) {
- System.out.print((char) buffer.get()); //输出：HelloWorld
- }
- buffer.clear();
- }
- source.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
+ try {
+ Pipe.SourceChannel source = pipe.source();
+ ByteBuffer buffer = ByteBuffer.allocate(1024);
+ // 读取SourceChannel中的数据
+ while (source.read(buffer) > 0) {
+ buffer.flip();
+ while (buffer.hasRemaining()) {
+ System.out.print((char) buffer.get()); //输出：HelloWorld
+ }
+ buffer.clear();
+ }
+ source.close();
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
}).start();
```
-## 三、Selector
+## 四、Selector
-### 3.1 创建选择器
+### 4.1 创建选择器
想要创建一个选择器，可以通过 Selector 类的静态方法 `open()` 来实现：
@@ -404,9 +492,9 @@ new Thread(() -> {
Selector selector = Selector.open();
```
-### 3.2 注册通道
+### 4.2 注册通道
-想要将 Channel 和 Selector 配合使用，必须要通过 `register()` 方法将 Channel 注册到 Selector 上，示例如下：
+之后须要通过 `register()` 方法将 Channel 注册到 Selector 上，示例如下：
```java
// 创建ServerSocketChannel
@@ -446,7 +534,7 @@ register(Selector sel, int ops, Object att)
这个附加信息可以在事件触发时通过 SelectionKey 对象再次得到。
-### 3.3 select
+### 4.3 select
当你在 Selector 上注册好通道后，就可以使用 `select()` 方法来获取处于就绪状态的事件的集合。示例如下：
@@ -460,17 +548,18 @@ select 有以下三个重载方法：
+ **select(long timeout)**：与 `select()` 类似，但最长只阻塞 timout 毫秒；
+ **selectNow()**：不会阻塞，如果不存在就绪事件，则直接返回 0。
-需要注意的是如果是 Ready 操作集发生了变化，select 操作的返回值也可能是 0。这意味着如果某个通道注册的是 `OP_READ` 事件，那么该通道在第一次收到消息时 select 操作返回的值是 1，但是之后收到消息时 select 的返回值则是 0。因此在循环获取消息时，对于 select 返回值的判断应该加上为 0 的情况：
+需要注意的是如果是 Ready 操作集发生了变化，select 操作的返回值也可能是 0。这意味着如果某个通道注册的是 `OP_READ` 事件，那么该通道在第一次收到消息时，select 操作返回的值是 1；但是之后收到消息时，select 的返回值却可能是 0。因此在循环获取消息时，对于 select 返回值的判断应该加上为 0 的情况：
```java
+// 如果选择器上存在就绪事件，则进行处理
while (selector.select() >= 0) {
....
}
```
-### 3.4 SelectionKey
+### 4.4 SelectionKey
-当存在注册的事件处于就绪状态时，可以通过 Selector 的 `selectedKeys()` 方法来获取处于就绪状态的事件信息：
+当注册的事件处于就绪状态时，可以通过 Selector 的 `selectedKeys()` 方法来获取处于就绪状态的事件信息：
```java
Set selectionKeys = selector.selectedKeys();
@@ -523,15 +612,18 @@ public abstract class SelectionKey {
}
```
-## 四、聊天室实例
+
+
+## 五、聊天室实例
下面以一个群聊的聊天室为例，来展示 Java NIO 三大组件的综合使用，效果如下：
-
+ 
-### 4.1 群聊服务器
+
+### 5.1 群聊服务器
群聊服务器的实现如下：
@@ -547,135 +639,136 @@ import java.util.Set;
public class ChatServer {
- private String hostname;
- private int port;
- private Selector selector;
- private final ByteBuffer rBuffer = ByteBuffer.allocate(1024);
- private final ByteBuffer wBuffer = ByteBuffer.allocate(1024);
+ private String hostname;
+ private int port;
+ private Selector selector;
+ private final ByteBuffer rBuffer = ByteBuffer.allocate(1024);
+ private final ByteBuffer wBuffer = ByteBuffer.allocate(1024);
- ChatServer(int port) {
- this("127.0.0.1", port);
- }
+ ChatServer(int port) {
+ this("127.0.0.1", port);
+ }
- ChatServer(String hostname, int port) {
- this.hostname = hostname;
- this.port = port;
- }
+ ChatServer(String hostname, int port) {
+ this.hostname = hostname;
+ this.port = port;
+ }
- public void start() {
- try {
- // 创建ServerSocketChannel
- ServerSocketChannel serverChannel = ServerSocketChannel.open();
- // 设置为非阻塞模式
- serverChannel.configureBlocking(false);
- serverChannel.bind(new InetSocketAddress(hostname, port));
+ public void start() {
+ try {
+ // 创建ServerSocketChannel
+ ServerSocketChannel serverChannel = ServerSocketChannel.open();
+ // 设置为非阻塞模式
+ serverChannel.configureBlocking(false);
+ serverChannel.bind(new InetSocketAddress(hostname, port));
- // 创建selector
- selector = Selector.open();
- // 注册监听CONNECT事件
- serverChannel.register(selector, SelectionKey.OP_ACCEPT);
+ // 创建selector
+ selector = Selector.open();
+ // 注册监听CONNECT事件
+ serverChannel.register(selector, SelectionKey.OP_ACCEPT);
- // 持续调用select()
- while (true) {
- selector.select();
- Set selectionKeys = selector.selectedKeys();
- for (SelectionKey selectionKey : selectionKeys) {
- // 处理Accept事件
- if (selectionKey.isAcceptable()) {
- // 获取ServerSocketChannel
- ServerSocketChannel server = (ServerSocketChannel) selectionKey.channel();
- // 通过ServerSocketChannel获取SocketChannel
- SocketChannel clientChannel = server.accept();
- clientChannel.configureBlocking(false);
- // 注册Read事件
- clientChannel.register(selector, SelectionKey.OP_READ);
- System.out.println("欢迎" + clientChannel.socket().getPort() + "加入聊天室！");
- // 处理Readable事件
- } else if (selectionKey.isReadable()) {
- handleMessage(selectionKey);
- }
- }
- selectionKeys.clear();
- }
+ // 持续调用select()
+ while (true) {
+ selector.select();
+ Set selectionKeys = selector.selectedKeys();
+ for (SelectionKey selectionKey : selectionKeys) {
+ // 处理Accept事件
+ if (selectionKey.isAcceptable()) {
+ // 获取ServerSocketChannel
+ ServerSocketChannel server = (ServerSocketChannel) selectionKey.channel();
+ // 通过ServerSocketChannel获取SocketChannel
+ SocketChannel clientChannel = server.accept();
+ clientChannel.configureBlocking(false);
+ // 注册Read事件
+ clientChannel.register(selector, SelectionKey.OP_READ);
+ System.out.println("欢迎" + clientChannel.socket().getPort() + "加入聊天室！");
+ // 处理Readable事件
+ } else if (selectionKey.isReadable()) {
+ handleMessage(selectionKey);
+ }
+ }
+ selectionKeys.clear();
+ }
- } catch (IOException e) {
- e.printStackTrace();
- } finally {
- // 关闭selector后，与之相关的所有资源都会被释放
- try {
- selector.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
- }
- }
+ } catch (IOException e) {
+ e.printStackTrace();
+ } finally {
+ // 关闭selector后，与之相关的所有资源都会被释放
+ try {
+ selector.close();
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
+ }
+ }
- /**
- * 处理客户端消息
- *
- * @param selectionKey 处于Read状态的SelectionKey
- */
- private void handleMessage(SelectionKey selectionKey) {
- SocketChannel clientChannel = (SocketChannel) selectionKey.channel();
- try {
- // 获取来自客户端的消息
- StringBuilder buffer = new StringBuilder();
- while (clientChannel.read(rBuffer) > 0) {
- rBuffer.flip();
- buffer.append(StandardCharsets.UTF_8.decode(rBuffer));
- rBuffer.clear();
- }
- String msg = buffer.toString();
- // 将消息发送给其他客户端
- broadcastMessage(clientChannel, msg);
- } catch (IOException e) {
- // 该异常由clientChannel.read(rBuffer)方法抛出，如果出现该异常，则说明clientChannel已经关闭
- // 此时需要调用cancel()取消注册在selector上的事件
- selectionKey.cancel();
- // 在多线程环境下，如果另一个线程正在阻塞地调用select()，因为事件集已经改变，
+ /**
+ * 处理客户端消息
+ *
+ * @param selectionKey 处于Read状态的SelectionKey
+ */
+ private void handleMessage(SelectionKey selectionKey) {
+ SocketChannel clientChannel = (SocketChannel) selectionKey.channel();
+ try {
+ // 获取来自客户端的消息
+ StringBuilder buffer = new StringBuilder();
+ while (clientChannel.read(rBuffer) > 0) {
+ rBuffer.flip();
+ buffer.append(StandardCharsets.UTF_8.decode(rBuffer));
+ rBuffer.clear();
+ }
+ String msg = buffer.toString();
+ // 将消息发送给其他客户端
+ broadcastMessage(clientChannel, msg);
+ } catch (IOException e) {
+ // 该异常由clientChannel.read(rBuffer)方法抛出，如果出现该异常，则说明clientChannel已经关闭
+ // 此时需要调用cancel()取消注册在selector上的事件
+ selectionKey.cancel();
+ // 在多线程环境下，如果另一个线程正在阻塞地调用select()，因为事件集已经改变，
// 因此需要通过wakeup()让其立刻返回并重新select()
- selector.wakeup();
- System.out.println("用户" + clientChannel.socket().getPort() + "退出聊天室！");
- }
- }
+ selector.wakeup();
+ System.out.println("用户" + clientChannel.socket().getPort() + "退出聊天室！");
+ }
+ }
- /**
- * 将客户端发来的消息广播给其他客户端
- *
- * @param clientChannel 消息源
- * @param msg 消息
- */
- private void broadcastMessage(SocketChannel clientChannel, String msg) {
- try {
- // 遍历当前selector上所有channel
- for (SelectionKey selectionKey : selector.keys()) {
- SelectableChannel channel = selectionKey.channel();
- // 消息不需要转发给ServerSocketChannel和当前客户端自己
- if (selectionKey.isValid() && !(channel instanceof ServerSocketChannel)
- && !channel.equals(clientChannel)) {
- SocketChannel otherClient = (SocketChannel) channel;
- wBuffer.put(("用户" + clientChannel.socket().getPort() + ": " + msg).getBytes());
- while (wBuffer.hasRemaining()) {
- wBuffer.flip();
- otherClient.write(wBuffer);
- }
- wBuffer.clear();
- }
- }
- } catch (IOException e) {
- e.printStackTrace();
- }
+ /**
+ * 将客户端发来的消息广播给其他客户端
+ *
+ * @param clientChannel 消息源
+ * @param msg 消息
+ */
+ private void broadcastMessage(SocketChannel clientChannel, String msg) {
+ try {
+ // 遍历当前selector上所有channel
+ for (SelectionKey selectionKey : selector.keys()) {
+ SelectableChannel channel = selectionKey.channel();
+ // 消息不需要转发给ServerSocketChannel和当前客户端自己
+ if (selectionKey.isValid() && !(channel instanceof ServerSocketChannel)
+ && !channel.equals(clientChannel)) {
+ SocketChannel otherClient = (SocketChannel) channel;
+ wBuffer.put(("用户" + clientChannel.socket().getPort() + ": " + msg).getBytes());
+ while (wBuffer.hasRemaining()) {
+ wBuffer.flip();
+ otherClient.write(wBuffer);
+ }
+ wBuffer.clear();
+ }
+ }
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
- }
+ }
- public static void main(String[] args) {
- new ChatServer(8888).start();
- }
+ public static void main(String[] args) {
+ new ChatServer(8888).start();
+ }
}
-
```
-### 4.2 客户端实现
+### 5.2 客户端实现
+
+客户端的实现如下：
```java
package chat;
@@ -693,130 +786,135 @@ import java.util.Set;
public class ChatClient {
- private String hostname;
- private int port;
- private Selector selector;
- private final ByteBuffer rBuffer = ByteBuffer.allocate(1024);
- private final ByteBuffer wBuffer = ByteBuffer.allocate(1024);
+ private String hostname;
+ private int port;
+ private Selector selector;
+ private final ByteBuffer rBuffer = ByteBuffer.allocate(1024);
+ private final ByteBuffer wBuffer = ByteBuffer.allocate(1024);
- ChatClient(String hostname, int port) {
- this.hostname = hostname;
- this.port = port;
- }
+ ChatClient(String hostname, int port) {
+ this.hostname = hostname;
+ this.port = port;
+ }
- public void start() {
- try {
- // 创建SocketChannel
- SocketChannel socketChannel = SocketChannel.open();
- socketChannel.configureBlocking(false);
- socketChannel.connect(new InetSocketAddress(hostname, port));
+ public void start() {
+ try {
+ // 创建SocketChannel
+ SocketChannel socketChannel = SocketChannel.open();
+ socketChannel.configureBlocking(false);
+ socketChannel.connect(new InetSocketAddress(hostname, port));
- // 创建selector
- selector = Selector.open();
- // 注册监听CONNECT事件
- socketChannel.register(selector, SelectionKey.OP_CONNECT);
+ // 创建selector
+ selector = Selector.open();
+ // 注册监听CONNECT事件
+ socketChannel.register(selector, SelectionKey.OP_CONNECT);
- // 持续调用select
- while (true) {
- selector.select();
- Set selectionKeys = selector.selectedKeys();
- for (SelectionKey selectionKey : selectionKeys) {
- // 处理Connect事件
- if (selectionKey.isConnectable()) {
- SocketChannel clientChannel = (SocketChannel) selectionKey.channel();
- // 有可能正处于连接中的状态
- if (clientChannel.isConnectionPending()) {
- // 等待连接完成
- clientChannel.finishConnect();
- // 开始监听用户输入
- inputListening(clientChannel);
- // 为clientChannel注册上Read
- clientChannel.register(selector, SelectionKey.OP_READ);
- System.out.println("尊敬的用户" + clientChannel.socket().getLocalPort()
- + ", 你已成功加入群聊！");
- }
- // 处理Read事件
- } else if (selectionKey.isReadable()) {
- handleMessage(selectionKey);
- }
- }
- }
- } catch (ClosedSelectorException e) {
- // 主动关闭客户端，不做任何处理
- } catch (IOException e) {
- e.printStackTrace();
- } finally {
- try {
- selector.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
- }
- }
+ // 持续调用select
+ while (true) {
+ selector.select();
+ Set selectionKeys = selector.selectedKeys();
+ for (SelectionKey selectionKey : selectionKeys) {
+ // 处理Connect事件
+ if (selectionKey.isConnectable()) {
+ SocketChannel clientChannel = (SocketChannel) selectionKey.channel();
+ // 有可能正处于连接中的状态
+ if (clientChannel.isConnectionPending()) {
+ // 等待连接完成
+ clientChannel.finishConnect();
+ // 开始监听用户输入
+ inputListening(clientChannel);
+ // 为clientChannel注册上Read
+ clientChannel.register(selector, SelectionKey.OP_READ);
+ System.out.println("尊敬的用户" + clientChannel.socket().getLocalPort()
+ + ", 你已成功加入群聊！");
+ }
+ // 处理Read事件
+ } else if (selectionKey.isReadable()) {
+ handleMessage(selectionKey);
+ }
+ }
+ }
+ } catch (ClosedSelectorException e) {
+ // 主动关闭客户端，不做任何处理
+ } catch (IOException e) {
+ e.printStackTrace();
+ } finally {
+ try {
+ selector.close();
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
+ }
+ }
- /**
- * 监听用户来自控制台的输入
- *
- * @param clientChannel 客户端Channel
- */
- private void inputListening(SocketChannel clientChannel) {
- // 要持续监听用户输入，但又不能阻塞主线程，所以需要一个单独的线程来完成
- new Thread(() -> {
- Scanner scanner = new Scanner(System.in);
- try {
- while (scanner.hasNextLine()) {
- String input = scanner.nextLine();
- if (!input.isEmpty()) {
- if ("exit".equals(input)) {
- selector.close();
- return;
- }
- wBuffer.put(input.getBytes());
- wBuffer.flip();
- while (wBuffer.hasRemaining()) {
- clientChannel.write(wBuffer);
- }
- wBuffer.clear();
- }
- }
- } catch (IOException e) {
- e.printStackTrace();
- }
- }).start();
- }
+ /**
+ * 监听用户来自控制台的输入
+ *
+ * @param clientChannel 客户端Channel
+ */
+ private void inputListening(SocketChannel clientChannel) {
+ // 要持续监听用户输入，但又不能阻塞主线程，所以需要一个单独的线程来完成
+ new Thread(() -> {
+ Scanner scanner = new Scanner(System.in);
+ try {
+ while (scanner.hasNextLine()) {
+ String input = scanner.nextLine();
+ if (!input.isEmpty()) {
+ if ("exit".equals(input)) {
+ selector.close();
+ return;
+ }
+ wBuffer.put(input.getBytes());
+ wBuffer.flip();
+ while (wBuffer.hasRemaining()) {
+ clientChannel.write(wBuffer);
+ }
+ wBuffer.clear();
+ }
+ }
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
+ }).start();
+ }
- /**
- * 处理来自其他客户端的消息
- *
- * @param selectionKey 处于Read状态的selectionKey
- */
- private void handleMessage(SelectionKey selectionKey) {
- try {
- SocketChannel channel = (SocketChannel) selectionKey.channel();
- StringBuilder buffer = new StringBuilder();
- while (channel.read(rBuffer) > 0) {
- rBuffer.flip();
- buffer.append(StandardCharsets.UTF_8.decode(rBuffer));
- rBuffer.clear();
- }
- System.out.println(buffer.toString());
- } catch (IOException e) {
- selectionKey.cancel();
- selector.wakeup();
- System.out.println("聊天室服务器已关闭！");
- }
- }
+ /**
+ * 处理来自其他客户端的消息
+ *
+ * @param selectionKey 处于Read状态的selectionKey
+ */
+ private void handleMessage(SelectionKey selectionKey) {
+ try {
+ SocketChannel channel = (SocketChannel) selectionKey.channel();
+ StringBuilder buffer = new StringBuilder();
+ while (channel.read(rBuffer) > 0) {
+ rBuffer.flip();
+ buffer.append(StandardCharsets.UTF_8.decode(rBuffer));
+ rBuffer.clear();
+ }
+ System.out.println(buffer.toString());
+ } catch (IOException e) {
+ selectionKey.cancel();
+ selector.wakeup();
+ System.out.println("聊天室服务器已关闭！");
+ }
+ }
- public static void main(String[] args) {
- new ChatClient("127.0.0.1", 8888).start();
- }
+ public static void main(String[] args) {
+ new ChatClient("127.0.0.1", 8888).start();
+ }
}
-
```
+## 参考资料
+
++ [Ron Hitchens . Java NIO . O'Reilly Media . 2002-08-15](https://book.douban.com/subject/1433583/)
++ [Java NIO Tutorial](http://tutorials.jenkov.com/java-nio/index.html)
++ [一文读懂 Java NIO 和 IO 的不同](https://baijiahao.baidu.com/s?id=1632673729522644150&wfr=spider&for=pc)
+
diff --git a/pictures/java_nio.pptx b/pictures/java_nio.pptx
index b86e79dd4cf0453f47422b9035e06b936cfe98d5..27bca40c07b9717e8fbe2da07b65352e27a4a4c9 100644
GIT binary patch
delta 46118
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
z
zwT`VN`S{~QvP=*&wQYUx*ROwm41V4Do@q6!TUD)_L>fC!Ld5r9gE>Fem!m_t@g$8E
z7m#pNGldGObcPL=&(j18=vKMY*b;N>Xtw(8j|sSk!|}V90X6NJVBKRh`^-$U&9_q*
z2j+)cucAXYjdMXlbGU!h>YZAKu~W)_{pGMG&ID&J+R*a8xH#w;=Z8~DjSu@uPs99RhKL%M{pWQY1mF0|)<_j&&+MB)D9Ua|nxldVd3H?mw
z%6QgwV>g-#*eV!(#nljMmod+Ab75uA1KEJa9*um|1mt`osj_Z3(|_6H)v68U;LbXYBet-OU;E%g1)D3f7+Y8kYNbvc3pLH;fHN27|_PArOQR
zdJ^f;OerK7DM&Hj!)D_C1Qacm)q|S*kq&_7j^iK{Kv>A_QNqhuuvmW-5s&9{+t7qd29w)e2BVkJFX}@e75Y8qY
z-PT}rwMbVpbT{x+HwsSLxQ{IxwL&>z3y9)#d8-S!e-z{aJ|v3K3P8lMk^8E4-fzPq
zQTKu~MAz>8N)M>J{33pK47PdmSXn12R*mrmEb_nP^-{N1+*>U+k>eJ=H^#lSOAtIo
zzTc{R_}v!tT?(-DKHrst{tk#qNVWc>R$vnYF;sapMZN5s>Z)y#+;vslafAXdCr=}=vdqT
z+U`qcoXT@MG?`Fz)3z}!sBI{2Ds;RTR4FejCoJOe(4{Sn**KtLbNaNQ^`oS%vaD=R
zO4{%1D6{{POE`qw8+|LYD<>E3GyA6(9(?oIwZ+0h>*^&Gf}pDJ@jv&3QATCX!ZU4_0x(0?Am6J-HvSSemiqC^QL*ADQ8gbJ?F#Nxlh-;p9^GbRY-l;&A8g1_xS)586e~%=2bV
zQk;o$n>TB5UcaSbLXz`o!ccT%%VCJ3$=M!sTv;h}IPADWEXc||;fQh!bT}yiK`wS$
zzM*Pq?&n*efjw1?@OUc>x@*nPwe41}BuNmMrEeRj*KVtd<
zK9)cq)}Xn**Y1!AezQ_^%P*lP!K^nzqSSGLlJwBMSgKKEgI|7jm2NTd(>QitR6>Za
zOzy0dSG#&0KO#qulbv9++M(mgm02`9dP<4%LaXnr9Cw9Tlh^rR#)qNJUOnQ;fDBok+6*w)w=>YrE^3lS~%F!+b|i
zQ(D)Ys}H)&0z8(dG2eYkBY)@#YY{p#!A9Fn8)mpMdw7OR#U21P$!;nEsgiJB
ziRyclKf}Jw>FzmJyFGCVNGM_r(t&~8bo>hECpMi$B3rm;$gm6t-_Sm>g@!~P0;tpo
zjTKY=4=ZPg)GK-rJUtv76v+S_L#Qrm>I6OoF9+o$H)N8kSQ~fK*21sG1;@_Ct|U*t
zie|3K2!vOnAT(Er?s=Y8a|?JNu*^|(Wz#4KjYuP0zlklxmu9sM>3aNeZQOGV5}NcJ
zGSodQBJlPZ9zL(CdowalQYi?6UIffNa=rU8xzk@x;nEhsiYE^
zWqw?g@UdQyK$Qw&)@u>%3;f>t^PALyNVCfw$4heZ$<%I&qGw_}ax7J}-*fNLy&x9d
zc?jyB*mfl;W=@T3c{If5^9#Wv(
z*gGR|!i&Q5!B1;W*&#D$e&zcvHuW-Hb#PJC32SwaRhqAj+;mF_(`$=}%tE2#Ft6+L
zAfoCCv8=KaMv>Qw+)I`G^vB1;=JHYw0&(AmTtR$^=HD+@aojoIr{^x^K$U-7zGh$M
zlBSuvg|6k^Z
zyS*qd^m}+1AvNOFd(?9x(egO`VZ*m^1@cE98$MN=Rz=c#=80L(I*FsNn5v};M
zm^x}^rCQcjE0S*p6Ql6PNrF6CL?3?+8)CNQ=@mivlVVzL8PB*clFu}Cm|%ZA1`U%_
zG9Na>w1kppmBecLqsam0rc+=8_~Nka@TZJA_hpM^Rw={iyjyq3aNRBzDAsX>0;1R}
zV16WB&2(|w{f+opQNDMcZ(_Ej<~(81>@qWD+b9dgcJpKcpLf&ZswwlRCsIatmG?&n
z=Q`UgYC%qSgmb8Mej5Bu;md@LdYMppO>^Nm5~E_e?LpqENlEK=Dl1P@)lPkZRpkT7
zEWq9s{;_EoPCUC<<;hn$c_rcU0dz_W^g@EXeRfQM49o7nh|TnrR&=Khe9tKT*8oUSt+0{5`{(U-W0?`s49V1hnM>w!97=j02AC>6717qsdIL
zp1)m?;~=8iFbiSH(o+@7yIgKVO+1a%t1qTW>H*9r!f>YGU}z22Deyw>K}efKJfa=E
zGZDV+dmZ#m3-hAuMyX>FV%q#x@co)8^T&oyEEZF)r}*=VF3wg-h$lOc)bt@oWz$AJ
z&`b^!4j1fssmgW=Fi?2#I{JAt4z9#O`!-^(z60ES4jsjmk#EAS$_i`QF@D-!f|D_K
z^iV@{HJVx3Ie(RYD=mKpf(8|#a;Zpju~>hioHw1FO%3xzXIhLs8%F^zMiXA8>{X95})5hMG)>s=`t3L{J`W#Sg
z5yWSR!?9|!e(~}C>mUQ<^YBpcHTQ?e8}fLz1drw{bV9MHTC4$)+i*pE(!sX`gYZ(=
zB?TV$W8!1`4Jx@MRZv3ofK}QjbFHE8j_2D=HR!c|YuiazdD1mF$jtOd26sKO{FZ7t
zD4)xwf_P-st?xomcxrtR>NquKG}F-_*qE8h(2H12uPE@#GAk=v42$z4$dJS!*0>P~
zlvwoP!L@&fa8M_1#_$9QtR@^$ozLI|zByjDb!Pl-TTrfYMg;Aql{PKqRhKpy-gH*(
zJ*ay}3^K@C`Uiw)5}3GC^~A;ff#E+;IyR3qWbz}0!!xfCS{1&tWJG@uXEHnCm^{-z
zD$YMW+|Z#VlUK^A#LYlp&d?n*RF<3S;<|~OLx$4tt&MUDHJIaBY*{|29kMn#?)Ls&XECUQxDzn%|47kIf3{cUkb#*|W>YH~4
zTk%F3m4UZlF6bK8Y>+p<5#<8h7L_s0^q5%syM1aoj}mCEy{9vc=SRKRgk5^!aQNZ~
zHC5tb#F<_!_I#N1I3~p3VGW7Yczgq3hav_vVzFjndKk5n>oFVRMfHQKL+exPQiXz_jvsWWMKF&bWdpK4&|
zXqA5@oH{({`jA9wdK#l_+#y9*i@xdB+G_lDJ)tsTR>L%1)2<
z=~eaN1C4c-QUjvb_dl=3#=U<=Qp!a(VtQ_JKyQC@Kp$=pT?_+GHsx7E+#WGmw1d2n
z4Wgh)B{USh7CI99sui4W7C<R@M;~pg>A+5UuCr}i;^LG
zt13!K>N4)@TILBnn^Yu1whKH%A5Rg(>gsP#PxsFBR9AIZdFfP#
z{GMvAQ23>d#=bV^k1!-7V#Z^XoiGrAD8o}2iP-iBj+ErHB6l-7yKD>=9uU
zLl0OGSU=7e5RTAISU~I#0zef=2ylgL16bi?z{n{oAQ-X;rOyCgZzfn?fIDRCuN+vu
z|E7Rm)OiGbD%}9!MT7{xXiQ+SZ(h%|?o+^bWO=pQ}Hje
z107PZVQ+~50WNuv<&A0HP8uQgi#2^^OZZu$BSr~#ipZHgq%S5t-SAal(}fOk9p>aq
zT)SUDo-Jlyo%ULT?%WR#XpG`NNNK8qMt8@5yk4(u2y{O@P+-0k&$HwP`+MiZcx5e|
zBphvJ`5at03euMc;C$F2_+jiD?7NwLU#39%7F#+mbRvxuNpV#);B|@(kP*qjSo@Kf
zJ>Z+1L{ZSF!1Te+t4!ieZlr8lLX;V=0~*X-t8`0X90L|OjU)w?rx9)HrQ`>b*D5N}
z`T2-l)}v)>DG*M}S%T|(#9xz9%8$Z+>XgQIIC-Ss!cwGb><_P7sC|pIOX#+BgMnn{
zb}{&QBTUvq+n*YT&@Ziy1SPtO+u?Xr-6U7bIbQqvkmO{Q==-@j;G5CjOSW9
z4(Hy0(m9$5J@m)m99l+#pQ^QQ5pdLdSdRL)SPG9n5a1IDwyEUhBr12AS-!UsNHCsx
z%M7=t!VM;%Zg@fV8(S%_l{2(pE{vo-GMVb}&)Bi(&6KbiH+YTDOnMzV^bc1-phR`W
zmh?CN(w->uMjAW&VYq&XEmzBkpIU;}9M_i$(5!gCr1%G)i;F>^zsixy`*vhm5ohPM
zi<-du)yx8OcUI|6D-w~aa_6@fvxV1(2Za#)VQOSUhRxPHwx
zf%t8VSIrN0rq8-8WpHA62Ki@2O00-u~w9a3K`
z(G;=i;23^3c`-SHwn-|vnVO@0QCyL-x_Q?nss7Iw`glgA3@rDn%B~Cvr?)RL74*Ha
z^@glJy17g=$Ilg?9E|v|RO)Wbkhro`e%!#|T)$vzi9&M=K;@#e9ow)~cS|KY0R?NY
zb6brW>cdnl>*youlYc&7abPEtRwy-uubG2?IqzM>TQ$^_qoAh=*`a!W|5
zNG;xD)52>S7dxi%a%qI_JFK)&+-SCf`%2#F0G6RiN-NC+n?UC>xw#|f!g-mk)}
zi;ViKx*rLz?A7OK9k~V(*|2xji{HGf;WR}9(w*(nF=J3H((w`q9MJY6IPn=X7(S35
zV9~yck>cA2_>@d|-~uh)xrz7MJdwWl6ccw^^1At{AXVNF5TJ3T(EzWziwUwx7OFa1
zfejfY|3iJQazh5w2ujCpuR%B=#7X3~?pYDsbddd$KQb3vi7ZHZlp?|DI2-FpFaWDB
zY*$WWfZ}w=xa|@K30|(W*-2OvBc6+06B%F_CH<2H*J$tgI^RoIqK$SN*Brw=7tS4$
zU27oWb4Q&hU_H<+xLvU)n+vL>X^)CkNPD$Cg1T);TsB;Or1`?n;H2ybQmdj&YG|9uP-s<8gEean&mk1B
zn2ncn38e(9H~8E5$N!uu-U#`9_e)57A-3WI7ODJ-dEfU&j!QFT27411q@v=ZQrgz9
z@uXIB3Ih8PAaYgRR`~&IU=Gm7zgI^6O4+@mp;65;SLyg3HE`q0BM1)tGqWLEt%@M)
z2U9^L9VmfnYi5^Ilnd(BOPD7C(RfRN+rBIi~q&>t2SCtJ&}66)bqe
zNV$W46-D*e_$nQ7WS%~JMPXO2&0soI7OA)pe}S%7j{a(=AiIaHnBVj>d?)-9^pq;F
z+&Q)3R-3Vtd91_5LOnF{uQw57PAaJYY?W(z_yxM3u%AQx%2>h~LIz@byhIv@?i<#w
z^p>MnR6^-epgIt0)W<>zQ8~2QZB`4EPL__7g<;MKIXIi*5Af`$Uc@94A*{20jZ0|4
zH1BA>q)}3}fbK3r_J==0DnFQoAl*Y})VPt_Y@{H0uzroiby@i-CXQE3_BKRH@F@;!
zD{~_0_4ZW(RybqH?<={1Rcv&_c1C|QyvulPs?|dORF@{xN}**D^D?1dX}mg|=mTid
zB&9zZAzy0!l?c(r)2CR;p?g{9A7}}3h>>|7N!o8hL6Ll(Ox?ogoD9vvw^GdWpjBpy
zH?K)cib=x3r|KGtQykucF9~J_UU2uN{GLy63U&=nSKs&Hy=1hxq-^oy3STxvPi{&y
ze8F-wA?NGvNnV6PhKo-7yM4gp?Q%O(`hItc1y5;mwwKMUeuwOQ0ECvCMa+gkgj~Ly
z1LyNTBj~9w?n`@Oa^c1PMEz92$3l=urU>Yz=flbpC^J2Sd<3(7Fi+sE50CdlJW2Ml
zx*7KdKAKh9Q7_zKP{&j^@X6Sgg0wKV^}TUbSG=yA^@=K=lq=`B&iD6Ibq#wTCvF4a
zLPBl+Fl@O*urTWytmRy07zCn?^}?4n&HqIK9XgNBCtv<`dJZ5SALU7}Y!uLxO+jSnx7
z4>tXhFP)n!A8lBRFDspEn;H|I8x_J_;1k;X_*wGgGStbEYf4I1ViA=)eAgUVXD;ja
z&?9=_HvMgB%iV
zROfJhf9*CV*cenQfLe<_7{rUeoU8FeTAgJUeyy~?-@JyStL9oKtIkaua=cELRyYbY_YC<@>8#dQ>JX49{b2P*&2m!i=4`KRbgm`5P67Rh)V$r5
zL+GPM(P?4xi_p)I*um~=Z4iK;eM0(c11aJd^XS(fkgUXIIM4!DAv(OX-1f=*8XU3L
z<qCs
zdUP*h-eaYbLn08=OyuqOZ~|YX!zX3ii<<88?kt0^3l@ISPN;5Uc2Qo}JZAovfJXid
zgd^WvV_w&8PRB0aGiuJFN&AW$Ut^8QM}_NPSBStE-%WsK(6_=}EY))s(PZf7z>w7ZX$6(HQ2Nj
zOF(eGgVzd+4%+7je?7uPY|0T^gcYw2ap_k6yfA)LERh*(q+3s=_Cx8GOIj7YQ){_d
zXBSI!mgDT!=G-PhIhn{Avn5Mn_^zAJvgq@OGC|t4B{pL-#>K(6iro@aQ)Uo~ay(;0
zwi34nS0(7WGrvqJ_cNa2B#qiNDN1>6@SD%=()ERye8fU-
z8l8)#Tj4|3jZsM|3KG$l7CpL>pmJ3O5pMCa*yZABH*
z!$@+KVDy9+38xX~Z_-of+cXODzVcMbqG#U4lUZBNp!n5#y@Pb)XZ8`fFDEflgi)Jo
ziAL228h9n18~ZjWqlAbGl}GTsbWLu19@HwS;=RmNZQ)KG?+6lPdZK%iCXF8P}yXh@Ozs_xnsE;mwSX??Fp@fp2Za;d!2drI&mPK
z(3YRMYxEuA#yid@W+8$UJc*52U+Wzaxc-y06i;E+jw)YMvY_Sy>tv-7_l140qq5Py
za=s+w3+tAh(VQNtJYlKIoe1gpi+TF48qshuSeA~5u}1FJ3FXH8mwC>x69&pZdSa&O
zKC!$r8e1W@IO5O{$61O88K+r%^lVhD6Ipq(Yr4AnbtN+;3jGlIuOp}|wd86&pII8Zez|uN
z5TiAGN3B503SCfj@bipzKK|SL8K2`(_ziA?xOfn@@R8|fEumk
zYtS5@p8FSl;TAX(KhT_Z$6?3f&HQ&LcT&1VsR>Em>*TtI!>%dNA5Rk9QV=*7~yY`N^5S-}mKRE$-5+Z;{J^u2uv
zhH_thDV;VRM@C1z&M;i}hGxXq(Y!;eh=K@I^i(8agO#>DHq4}2e99TLb9_N4$a?EC
zG-aU@p}nOuSfUNMiPgsy{)W?Za5FfYFN;F;-fh;f8yBL%`+m$J4*pV(mkopcMl!V~
zqJwaT;<~1Qxquvo3xDdtBI7}&a7(ZXN3azpm|n#{3k&%>m1`@p`QoN~Z7;G>N$|1H
z68+1_;(8M{o%Yj4W(UFPLf#UPR(^$$?Ha*5?D4RzJ*2IN)``~!F^_JYa}Hh@;sYLr
zPsaH5TNpj{Wf!kw*BjqUHEG081*u13b&DJiFxAE8nC>;ZUojTz(lkOc>Gak2K2sw3W0+&%%EU|8zPlxRpEj-{wfdIjg|wUQ@(nyc`G`
z^L2QUTIMeW@tuMepHU5kY`4tuh=GH)sF2Y_NQYU
zN6KwPa_prL>a<;)Vk=O1!N41Dm|epx#?vpDD;T~V=6fN|$yv$TH6ADpp6@Z`Wz1WFctRR+FdL
zV?jK2?sH~?_C>)#;X!?evvOcArnX}aH3!0uz@k5Mw6H!}iM&qh1#Gi|e7HE*ZjR3T
zZdu!59Xk#>=~Su>aa}5J)XfVKCY-mC;Er829u7@4%pKYvS7q1bk7&coBybmB$ZK>0OP&zpi)U$&+-u{%s^w9c9~S*~`Ro$k=-_sT8QNJ8r032WEkcF^QL!rh
z;l#g-1*?K3twXbgo{-6vU>HCh%lp>lj!CL
zaSgFAf9edFNIgY!DoEj1eTix51PejAQZ=Mb%5IDZtVlhY`~a1S5i)v6lOPyn6bPVLQL}EoSQehv$OjIh
z#@bH>CLS4i$-pBh}WvBD1NIK9+NNmfaM
zb+{=esxTUS&S#Lx*R$D+;pVY5Pxq^B4)s@_CwE9rMOtGHhA4{o*fMMc{nI61rAmrS
zZ~{_{<#t|8#m=Iqm+ge>RUDMM{(KvZDo^SE%WfM!bFHLkeYsU0-;H??{6_x|xTqm3
zZfcuR(h|2yh*X2cPD6(i$7%{T!SIl<6gOEhN_4@*QqP8Z$|2S~ROHLl2w^GBOTuD5
zR%`hHw@T)0n!u*f<2=nrz^{h@VaYK62Vhw3g(|7C=d~@kw!st*>{WYl+@JX*?J(%n
zq3Z;zC>b_fZN?7>Y?bSfhw-?5{
z-s!8BMf#gpYC3syXg`>lJWa@HRw<>$-ZP7}jukoj0MVM+W9V9*qddk$ze9@EwyQN<
zA(gfDrh^d!gdpiKC)-M5z~+5)TQd3M+lQmm?bCE%56hta8su?%{&RbEh4x}<%N)v@
zrw+u@Kuw_{d&Rzfgl{V4-3BdiA6?6!V@Eo<2FA>5?9T4k1`C1+5f
z(3u;$bnzEJ-*F-yRIbilJi}%z!dNmImxW
zlQ9p300x>-y9Z-CkgN+En~f}12xnq34AeYhgpe$fFT?Y=<01J-44oArZ+E}?U6IuRrZoH
zAhOGL+$o@H#kP>rBTjR$MEJgv9ish=0j@#T3dm!Jo27=b_7qS93SU4J%{ZFLDyUu^
z+5Jdn^}ZWEpNRR!+WAJEg}RUr1>arhWBhfI{Wr|V4#-k2h>|^&OQ^!S{)e5~#3u@X
z_B%c(21VFkmN?hWjl09bTufk$D2{fA$5LiM!R!+lBi$}pL-r}2mGoyk=aZVzx4hPy
z{i`|Gwo2KprRFP!av6utMIv}Cyg-Fb&iSl1G{?kL%I5cDgC9TaN2gb$4+fZPfXm*1
zC7-V9kxrA{o7PL4RsB*E7FKIF3MOs#6X5hfb1EqmMQo(wOH~*t6eD$Jh#4|88r*N1
zH4blgjzmR0-0vzCimZItun>M07_l+sFknEJU)g^Dq+l<^k&pP3Hke{gGevJ$y{SNa
z&S}`PE^0*g*Js#{;20dyvTJ(g7(p0emvNjB5v8+Qnb~_jLMBG5gjF#C1qmMuI6lW8
z{5>A>uHKkv>;03Q%UoNu-uRTc&KYzEMD2P>m3(X
z82=;UUms@(Rl5N!Vha^x`vGv%!~{9xLm7PMvCfQ3t&41qwkzS4{Ci-UCq@$&#a`s}#SYfiTgS*IwGO
zmxu@vXSDYRQp0yE+(m=8!Hfz5RTBLemsWrBS1ME!7>1PBskzV{6f-`v8kB*c3WT5{
z`M2hHid{4S3|*FnI)D@@rJ<3333C@}7l?zot|v+_VpK)%St2n`&~f>8X1o@BK=(R!
z>dqwj&anM>v4LVyf(nTpmS$c8{k{;2p}9PxBNar$b}PmYgIqG{u~<;H_=XQpJ8JCJcIn`Zx)rw-AB4
zF@yhMN~tu)z|~8C#b_E4m72}FAxgI2xi!>
zR;=#xb1F`Z?K(K^#5z5%T-cI1%_TcC58-;cvAf*<-1el1yZY;=<^3;0^DvZ(2J^1a
z6ro(RFX@UpG;~KUH$5OE8Lmf>B&sJ`lEd{_URnhjNAZKO0@JFuqgdKD(pZG&>XWeoijB}ic&IRP64)8ado^$b$8MZ29;BIb0nPeg{MO2Z+QfeyjG9vyJ0fdvpf`*R_n>zNP6u%
zr%>c>dWB_HM9@KGPpg54e8kJg3*hDv|3K60&{9d&k%C^l{rju)4?A+|xv$V#v{>uj
zBrK?qD(2=TeUsO=tW|_+5pzxJ&ZTuB@@Rf)V=fLbtK}t!dvj0sKW{F8t1K%XlXT)*
zsnqy0A6LXH&!%>>q&QY#knzX;85RPmz
zDb1Q4?CM4p952%68D`qfXJ>vbv%=T!q({}8s6EhGG>gXOy7Xv-4n(FpmZY8aHu$Sf
zhUWrQ+#cI%__i^Dp&i7bSqycwKTFgwc4XXsX(#GG5k1T0`uDAs{LrcVG&=CuLvzgxBg-Vz$vggmfMpXRu
zs1+}k@WZv5FE6-+1E#H
zJ}#i+8_&w$6b9WDW-<3QscG(PD5E-`@Z2RQur#;Z
zi+iX~tPuz2)hOd8TigIB3Rk@^ULm>P{*)jiuKYevNoyVVR@qdqn#j&vw}|+i#@N$?
z*8Q_;2XG;+oj}GWC1}ZNnHxL!7|k0g*R$NEs?{2@x(;NGzhmBqXRc{s
zv(kMx$;gs_tZ#mlmud!|eQrhXvzuvemUlGMJ&xo$`6j=ge4PN!k37h3reUnJp6tbI
zYKM#%j^hhv=M#xH4&U#t4Xs}q=L5NWKJu+~ohE!uk$dawt%F_TVFBa~x*$use!0V1
ziiXUJuT*sjYabAUMd*uF(|i
zw7s)j_gttQnp-|A6x{qdLyyEz_O;R-aeFERqP8hPol0BW*sXM@SP93m2=cl)1r|8|Xh?Ypt-6f$@{mkZMzP|G##W|REyN$BpFcVw$`
zcWcv2Bhm_P)lMG+P$wvrneWbKV
z#W_gz4(W=J>A|1h7P-zN1k0psbZ>d}CC?+?$vi9>GP?}{JYQ_}Bt?`8rjq12@4jo5
z)%u@lRItuOfW+yR7u(#+bvBcJ@p^)prKE5n#Qm2wpF+vWq=(ZL1#(l^qu#Q3T$3m&
zX>iu-CoWbMtYhJM5QbbX8Q(^8lq|=MyP_BJ=Ds0iv-K_LONMBjG?($d5i>gR5h3x&
zkkk1C%qflS&_`nUT3d8k2;^4l>5RUyH*U`ze;WC!NrPm{^t&OKs$4;*dk96YGDVIx
zV}dP5RGKo_xPS72b=V#{3j}m_R}f=!P<}Z>g!dR>K`TmK+{D3SiY+1ed%DejqI^rT
z(+>0~VZ>49idV2vy3MuUItkq1``Au8thpIiF_wduh~a6GDC>@=nASdYKhi3s3tG^{
zN5&rGZ2NAr;y96J-<@`}N=8?|XJpsFrL9E>xINvM8*m=_796K3Xu;MYkS|9%bcQ@q
zHp0>u3>u?0?qfsI4#vypH5<;&*i1V$=Z9*KoT7QF*bNglj)-N>cKl)<=$)!fdtc%lGAl$AyL7#ZSUkV!fw@`Zc*85(drL|PoC8*4-
z7q-{1tC)a4$Sn_boQ@&SMRU#mFs5?m?(p`E$+m|>rTP;*M85wMvcAkxgw;3;?^mtg
zCbZOzI{ZJ@?oemAiDo#rvOdxs3ED71a3nV4DJB%3mbSBoHN`txKS
zI5C<&Xec5byLOcouT%B;Mh+rg2%VQf%$HF&n>M=*2%g}czbRK}YVTCxU|@uiAp85&
zu%I#fDQ^6~!ud%yRw_xeXzZA!yit6stXaGu;5n#Zy)hqWJ2ZrWV!0Rwk4LS9>^P5z
z{pp&A@iF;3&J&{2WC2HMY`6etqStXN*BV5mf6VQW*=!a&FUSA2ZT;pv;fYva{8j2@
zTYIxgJx4wY778AD$|Z7q>&{AxU$ZJbHRu(hDG5qN%B9$0o?k5L3v4_M9#cEkxLBSE
z#&~b~oX{6lbp9bc4pICRg~98x@K`j7w=$8R7*R+qY$64dOf^%ehy;ye)w|#xUyXNBSDig9{ce|A3Df4=SZXV-0nb7sc&54G#`x@o0%2}x1wfK9u;VXLS4#GMyG
z&{?m4og#c)LkI46f;ngBGsrpA5ej1oUp{(ikqP#A1_KkIuU639C`^N#-x
zD|~p|*_xnV_$DcHr$$?(IlpBM22egCMD=;Mh_wp~1G9q*I2@^4rg0Wb~)+>yRgRf7WdWd03!
zM+x8^Gm-xp>2%cne*puGfD!`{V0(;BZZGy!F9Zd({hw+yxqxKoRRqhEEast6WGs^Z
zT}{txU>OSdJI3a}0b`N?)d>^%-*IUE4fvx1R45Yx?kCvfe|vWRH)u>B$cJ9#A0FlY
z(P8mcz|RwA@_%?_`Uhac0cf))2J(JmlmEl>#y>!>TmgquX6}D%BK`*;!v|^*clg5P
zY-4F+>inM*4=<4Q8=w0hdyM{3s5AKgDa7|zAz=IuDO`9AfD=vv2>YQx9|~5u&{%-R
zpBCu&!wMH12PKICgfl+4K=3oE3MKu4XEF;)`o=$#zoDehw`YR;_Neq=X{scX9nN@
zFutTcU*qF%Qu4pn87D(GUZ=c-fuZ?F^PSTH>EmAz~)l|
zLl*?(&&xBQFIO$vzd>jv&mfXZ0`k9CC;S^kSn&+9fP(%uBmNtN33&$9UlJhvWjFxF
zFA3pH>!Cb40PPAJ;V=C-Ky^h3hu{2+)42MN?ia9w@;uv~d3jd^