xsocket使用指南官方文档翻译

核心功能

支持面向流通信主要抽象是Connection接口。通过IBlockingConnection或者INonblockingConnection对象进行数据的读写。在record或者bulk状态中，Connection对象提供了对于特定数据类型的几个方便方法。

Connection实现了java.nio包中的GatheringByteChannel和

WritableByteChannel接口，如果InputStream或者OutputStream对象被需要，可以使用java.nio.Channels.newInputStream()和

java.nio.Channels.newOutputStream()包装channel对象，因为经典的流只有在IBlockingConnection映射到经典的InputStream中时才有阻塞行为。

提供的其他类型方法主要是控制连接行为和获取连接信息的方法。比如，远程链接点信息可以获取到，连接的数据冲刷行为可以被控制。这些方法都不是线程安全的。

与IBlockingConnection不同的是，INonBlockingConnection在调用read方法直接返回。将IDataHandler对象赋给INonBlockingConnection对象可以使其在新数据到来时被通知。当对应的事件发生时，IDataHandler对象的回调函数会被调用。除了IDataHandler也存在IConnectionHandler对象。

服务器端在INonblockingConnection接口上处理接入连接。

1、示例：简单TCP服务器

首先定义实现了需要的接口（比如，IDataHandler，IConnectHandler，IIdleTimeoutHandler或者IConnectionTimeoutHandler），这个DataHandler会在从连接上接收到数据时被调用。 classEchoHandler implements IDataHandler { publicbooleanonData(INonBlockingConnectionnbc) throwsIOException, BufferUnderflowException, MaxReadSizeExceededException { String data = nbc.readStringByDelimiter(\nbc.write(data + \return true; } } 然后创建一个服务器实例，并将上面的DataHandler赋给它 // creates the server by passing over the port number & handler IServersrv = new Server(8090, new EchoHandler()); // run it within the current thread. srv.run(); // the call will not return // ... or start it by using a dedicated thread专用线程 srv.start(); // returns after the server has been started 与run方法对应的，服务器的start方法创建一个专用的线程来运行服务器。start方法在内部阻塞知道服务器启动，为了确保服务器在执行其他进一步操作前

被启动，这是比较好的方法。

执行服务器的close方法来优雅的关闭服务器。就像其他面向连接的框架，服务器实现了java.io.Closable接口

2、DataHandler的onData方法的语义分析

IDataHandler的onData方法会在数据分片被接收后直接调用。要注意的是，在网络层，数据可以被分解成若干个TCP片段也可能被组合打包成一个TCP报文。在客户端执行类似于connection.write(“hello”)的写操作，并不意味着一个TCP报文到达服务器端。xSocket通过内部的读缓冲区缓冲接收到的网络数据来隐藏网络行为。

在没有足够数据可用的情况下，数据分片会导致NonBlockingConnection的read方法抛出BufferUnderflowException异常。根据运行模式，在一个挂起的onData方法调用期间没有数据会在网络层被收到。通过使用NONTHREADED模式，xSocket的内部网络I/O线程执行onDataMethod所以不能读取网络层数据。

BufferUnderflowException异常不处理是一个惯用的方法，xSocket会在onData方法返回时处理这个异常。 classEchoHandler implements IDataHandler { // this method will be called each time when data fragments have been received publicbooleanonData(INonBlockingConnectionnbc) throwsIOException, ClosedChannelException, BufferUnderflowException, MaxReadSizeExceededException { // don't handle the BufferUnderflowException, xSocket will swallow it byte[] bytes = nbc.readBytesByLength(500); //... return true; } } 因为没有读到的数据在xSocket的内部缓冲内，onData方法会被再次调用。也就是说，onData方法会在没有新的网络数据包到达时调用，因为xSocket的内部读缓冲区是不空的。这个循环会在内部缓冲区为空或者onData方法读不到数据时结束。xSocket在每次调用onData方法后检查内部读缓冲区是否被修改（新的网络数据到达，或者数据被读出），从而决定是不是要再次调用onData。

当连接关闭时，onData方法也会被调用。与处理缓冲区的underflow异常一样，closedChannelException也是不处理的，实现IDisconnectHandler来检测连接关闭。

3、写阻塞客户端

在客户端，使用IBlockingConnection可以简化套接字处理。与

NonBlockingconnection不同的是，BlockingConnection不支持回调处理。

IBlockingConnectionbc = new BlockingConnection(host, port);

String req = \bc.write(req + \

// read the whole logical part by waiting (blocking) until // the required data have been received

String res = bc.readStringByDelimiter(\

assert (req.equals(res));

4、写非阻塞客户端

执行阻塞客户端的读方法，调用会在数据接收到或者超时事件发生后返回。为了避免这种情况，客户端需要定义处理Handler，当网络事件发生后被调用。（IDataHandler，IDisconnectHandler）

// defining the client handler (here as a anonymous inner class) IDataHandlerclientHandler = new IDataHandler() {

publicbooleanonData(INonBlockingConnectionnbc) throwsIOException,

BufferUnderflowException,

MaxReadSizeExceededException {

// read the whole logical part or throwing a BufferUnderflowException String res = nbc.readStringByDelimiter(\ //... return true; } };

// opening the connection

INonBlockingConnectionnbc = new NonBlockingConnection(host, port, clientHandler);

nbc.write(\

// do something else. Receiving data causes that the client

// handler's onData method will be called (within a dedicated thread) //...

5、使用blocking Connection包装non-blocking Connection

xSocket在内部使用INonblockingConnection实现IBlockingConnection.。也就是说，BlockingConnection是带有阻塞行为的read方法的包装，于是NonblockingConnection可以随时变成BlockingConnection。

INonBlockingConnectionnbc= ...

// wrapping an existing non-blocking connection by a BlockingConnection

IBlockingConnectionbc = new BlockingConnection(nbc); bc.readInt(); //...

6、在服务端包装非阻塞Connection

在多数情况下，NonblockingConnection在服务端使用，如果服务器端需要一个BlockingConnection，可以通过包装NonBlockingConnection的方式创建。包装非阻塞Connection会导致赋给其的Handler在内部被移除。典型的是onConnect方法会在服务端创建一个BlockingConnection。

...

classConnectHandler implements IConnectHandler { < …… 此处隐藏：5499字，全部文档内容请下载后查看。喜欢就下载吧 ……