QuickServer开发手册整理.doc

窗体顶端quickserver开发手册（1）- 介绍 quickserver是一个免费的开源java库，用于快速创建健壮的多线程、多客户端tcp服务器应用程序。使用quickserver，用户可以只集中处理应用程序的逻辑/协议，从而方便的建立功能强大的服务器应用。该程序由akshathkumar shetty设计和实现。 quickserver安装目录下的example中有演示其功能的例子，最新的例子和文档可以通过网站 /或/获得。 该指南适用于所有想要学习和使用quickserver的人，阅读该指南应具备基本的java编程知识，基本的网络和sockets方面的知识也会有所帮助1.为什么需要quickserver？ 无论何种编程语言，socket编程对程序员来说都不是一件容易的事，创建多线程、多客户端的服务器socket更像一场恶梦了。在每个新的软件中处理多 socket连接，我们都要浪费大把时间编写大量重复的代码。quickserver因而诞生使用java创建多线程、多客户端服务器应用。2.基本构造quickserver在应用逻辑上为开发者提供了四个类oclientcommandhandler 处理与客户端的交互使用字符串命令oclientobjecthandler 可选类 处理与客户端的交互使用对象命令oauthenticator 可选类 客户端验证oclientdata 可选类 客户端数据载体（支持类）下面的图表显示了quickserver库的基本构造。quickserver模块上七个辐条表示七个方法：ojava.lang.string info()oint getservicestate()oboolean initservice(java.lang.object config)oboolean startservice()oboolean resumeservice()oboolean suspendservice()oboolean stopservice() 与quickserver模块相连接的四个组件中只有clientcommandhandler是必须的。 quickserverconfig对象由initservice()方法构建。它实现了quickserver，在读取xml配置后，quickserverconfig用于quickserver配置。 clienthandler线程对象用于客户端缓冲池。可选的clientdata类与clienthandler类关联，clienthandler对 象容器参考clientcommandhandler，clientobjecthandler(可选)，authenticator(可选)对象包含在 quickserver主函数中。 注意：上图中并未显示qsadminserver，它是图中quickserver的组成部分。3.主要特点o创建多线程、多客户端tcp服务器应用程序o支持安全服务的创建：ssl, tlso清楚的分离服务、协议、验证逻辑ogui图形界面远程管理支持ocommand shell对服务器的本地管理o无须断开客户端连接的重启或延迟服务o为线程的再利用和大多数的使用对象建立缓冲池o完全的日志支持（java构建）o支持发送和接收字符串、字节、二进制、序列化java对象o在同样的xml中支持能够存贮指定应用数据的xml配置o支持通过ip地址限制服务o支持基于xml的jdbc映射o支持服务配置模式o支持从xml加载/重新加载用于jar包o在quickserver中添加处理hookso指定允许的最大客户端连接数o在通常的tcp连接上支持谈判安全连接o支持鉴别和查询客户端o附带典型例子ftpserver, cmdserver,echowebserver, chatserver4.1.4版的新功能o为quickserver添加安全模式：ssl, tlso添加securemanagerloader管理安全模式o在通常的tcp连接上添加谈判安全连接o添加初始化服务hookso为通信添加二进制模式o为qsadminserver通信添加qsadminapio为quickserver 添加findallclientbykeyo添加connectionlostexception类o改进clienthandler、安全配置o新例子xmladder：一个简单的xml服务，可添加两个整数o新例子pipeserver：一个简单的重定向服务窗体顶端quickserver开发手册（2）- 安装 1. 运行环境quickserver 1.2以上的版本需要(其实在偶看来一个1.4版以上jdk足矣)： 推荐1.4版以上java虚拟机,最低1.3版(未经测试). java logging api（下列之一）o java.util.logging包 jdk 1.4版自带o lumberjack库 / xml 解析器 (下列之一)o sax (面向xml 2.0的api) jdk 1.4版自带o jaxp (面向xml解析的java api) 1.1 jdk 1.4版自带o xerces /xerces2-jo crimson /crimson jakarta公共组件digester, poolo 这些产品包含在apache开发的软件中(/)。jar包都在以下的库中：beanutils, collections, logging. /commons/components.html. apache软件许可证在文件“apache_license.txt”中。2. 安装 目前最新的1.4.1版quickserver可在/download.html下载。安装quickserver，假设安装路径为$install_path。 在classpath中添加$install_pathdistquickserver.jar，在path中添加$install_pathbin。 另外测试socket的通讯软件推荐socktest，在/soft/sockettest 可下载到最新版本。windows自带的telnet也可以进行测试。quickserver开发手册（3）- 构建echoserver 学习怎样使用quickserver库的一个好的方法是学习它提供的例子。在quickserver安装路径下的examples文件夹里有许多典型的例子。 下面的章节里我们模仿其中的一个例子echoserver来构建一个服务器。echoserver是一个简单的tcp服务器，主要功能是将用户发送的字符串加上前缀echo :后返回。虽然这个例子可用性不强，但它是一个对quickserver所有特点的一个很好的示范。我们从构建一个最基本的服务器开始，以后慢慢给它添加新的功能。1.代码 首先实现echoserver最基本的功能：将用户发送的字符串加上前缀echo :后返回。 在本地创建一个文件夹存放需要的代码，如在c:projects中建立echoserver文件夹，然后创建一个类echoserver.java：01 package echoserver;0203 import .*;04 import .server.*;0506 import java.io.*;0708 public class echoserver 09 public static void main(string s) 10 quickserver myserver =11 new quickserver(echoserver.echocommandhandler);12 myserver.setport(4123);13 myserver.setname(echoserver v 1.0);14 try 15 myserver.startserver();16 catch(appexception e)17 system.err.println(error in server : +e);18 19 20 在第10行和第11行定义了一个quickserver对象myserver，通过一个string对象 echoserver.echocommandhandler声明了要加载的类，这个类面向所有客户端做命令处理器，实现了 .server.clientcommandhandler接口，我们即将创建。 第12行设置了一个服务器端口用来做监听，然后设置整个应用的名字（第13行）。最后启动服务（第15行）。 接下来为echoserver创建一个实现.server.clientcommandhandler接口的类echocommandhandler.java，用来处理服务器发送的命令。01 / echocommandhandler.java02 package echoserver;0304 import .*;05 import java.io.*;06 import .server.clientcommandhandler;07 import .server.clienthandler;0809 public class echocommandhandler implements clientcommandhandler 1011 public void gotconnected(clienthandler handler)12 throws sockettimeoutexception, ioexception 13 handler.sendclientmsg(+);14 handler.sendclientmsg(| welcome to echoserver v 1.3 |);15 handler.sendclientmsg(| send quit to exit |);16 handler.sendclientmsg(+);17 18 public void lostconnection(clienthandler handler)19 throws ioexception 20 handler.sendsystemmsg(connection lost : +21 handler.getsocket().getinetaddress();22 23 public void closingconnection(clienthandler handler)24 throws ioexception 25 handler.sendsystemmsg(closing connection : +26 handler.getsocket().getinetaddress();27 2829 public void handlecommand(clienthandler handler, string command)30 throws sockettimeoutexception, ioexception 31 if(command.equals(quit) 32 handler.sendclientmsg(bye ;-);33 handler.closeconnection();34 else 35 handler.sendclientmsg(echo : +command);36 37 38 根据quickserver的要求，这个类必须实现clientcommandhandler接口。 当客户端建立一个连接（11行），gotconnected()方法被调用。在这个方法里面，我们给客户端发送欢迎文本（13-16行），这些文本使用通 过clienthandler的sendclientmsg()方法发送给客户端。我们也会使用clienthandler的 sendsystemmessage()方法显示客户端连接的inetaddress（20-21，25-26行）。 handlercommand()方法是clientcommandhandler接口的核心方法，因为服务器接收客户端发送的任何命令时都要调用该方 法。在我们对这个方法的实现中，我们会检查命令是否为quit（31行），如果是，我们将发送一些提示文本表示服务器即将关闭连接，然后关闭连接 （33行）。否则，将命令加上前缀echo :返回给用户。2.运行和测试o运行命令提示符程序（cmd.exe）o进入代码所在文件夹根目录，如c:projectso编译代码 javac echoserver*.javao若无编译错误，运行服务器： set classpath=%classpath%;d:quickserverdistquickserver.jar;.（类所在文件夹） java echoserver.echoservero您将会看到如下信息：o测试我们的服务器是否可以正常工作。再运行一个cmd程序，进入sockettest.jar所在目录，键入java -jar sockettest.jar命令，弹出一个窗口。在ip address中输入，在port里输入4123，点击connect按钮，将看到窗口中显示如下图的信息。 若使用telnet，可键入命令：open localhost 4123 在message中输入一些字符串，点击send按钮，浏览器将会返回一个加了前缀echo :的字符串。发送quit，服务器断开连接。quickserver开发手册（4）- 添加认证 现在我们给刚刚创建的服务器添加认证功能。 查看.server.quickserver的文档（docs文件夹下）你可以注意到里面有一个方法 public void setauthenticator(java.lang.string authenticator) 阅读文档可知此方法中的authenticator字符串是实现.server.authenticator接口的方法的全名。 authenticator接口有两个实现： .server.quickauthenticator：这个类用来验证连接quickserver的客户端。它只用一个实例处理所有的quickserver验证。（推荐） .server.serverauthenticator：这个类同样用来验证连接quickserver的客户端，但对每一个验证的处理都会创建一个实例。 接下来给echoserver加验证功能。简单点，客户端输入的用户名和密码一致就算验证通过。 首先，在同样的文件夹里创建一个验证类：echoserverquickauthenticator01 package echoserver;0203 import .server.*;04 import java.io.*;0506 public class echoserverquickauthenticator extends quickauthenticator 0708 public boolean askauthorisation(clienthandler clienthandler)09 throws ioexception 10 string username = askstringinput(clienthandler, user name :);11 string password = askstringinput(clienthandler, password :);1213 if(username=null | password =null)14 return false;1516 if(username.equals(password) 17 sendstring(clienthandler, auth ok);18 return true;19 else 20 sendstring(clienthandler, auth failed);21 return false;22 23 24 这个类扩展了.server.quickauthenticator（第6行），在 askauthorisation()方法中（8行），通过askstringinput()方法要求客户端输入用户名和密码，并读入客户端输入的信息 （10-11行）。这个方法继承自quickauthenticator。如果用户名与密码相等，发送正确信息并返回true（16-18行），否则 发送错误信息并返回false（20-21行）。 接下来我们要告诉quickserver使用我们新创建的验证类来做验证器。修改前一章创建的echoserver.java文件，代码如下（粗体为修改的代码）：01 package echoserver;0203 import .*;04 import .server.*;0506 import java.io.*;0708 public class echoserver 0910 public static void main(string s) 1112 quickserver myserver =13 new quickserver(echoserver.echocommandhandler);14 myserver.setauthenticator(15 echoserver.echoserverquickauthenticator);16 myserver.setport(4123);17 myserver.setname(echoserver v 1.0);18 try 19 myserver.startserver();20 catch(appexception e)21 system.err.println(error in server : +e);22 23 24 ok，将修改好的文件编译，按照前一章讲述的方法运行程序。这次当我们点击connect时，浏览器会要求我们输入用户名和密码。如果输入的用户名和密码一致就可以登录。如果输入错误五次以上，浏览器会提示-err max auth try reached并自动断开连接。这个次数和提示信息可以通过quickserver类的setmaxauthtry() 和 setmaxauthtrymsg()修改。 有时在验证过程中我们可能需要中途退出而不是等待验证结束，这时输入quit是不起作用的。我们可以这样修改代码，有两个方法： 一是从echoserverquickauthenticator类中的askauthorisation()方法抛出一个.appexception异常，代码如下： string username = askstringinput(clienthandler, user name :); if (username != null & username.equalsignorecase(quit) sendstring(clienthandler, logged out.); throw new appexception(quit); 或者参考clienthandler，关闭连接，代码如下： string username = askstringinput(clienthandler, user name :); if (username != null & username.equalsignorecase(quit) sendstring(clienthandler, logged out.); clienthandler.closeconnection(); return false; clienthandler对象能够提供很多客户端连接的有用信息，如ip地址。更多信息请参考api文档。注意： o 不要在验证器类中存贮任何客户端相关信息，如果需要，必须存放在clientdata类中-下一章将讲解该部分内容。 o 必须确认askauthorisation()方法是线程安全的。quickserver开发手册（5）- 客户数据 既然不能在clientcommandhandler和serverauthenticator类中保存客户数据，我们使用clientdata类的handlecommand()或askauthorisation()方法来存储所有的客户端信息。 示范一下这个特点有什么用。还是以echoserver为例，当用户发送hello时，我们给他一个问候。如果用户再发送hello，我们提醒他已经发了n次hello。接下来定义clientdata类来存储用户名以及他向服务器发送hello的次数。1.代码1.在echoserver中创建一个echoserverdata类01 /- echoserverdata.java -02package echoserver;0304 import .server.*;05 import java.io.*;0607 public class echoserverdata implements clientdata 08 private int hellocount;09 private string username;1011 public void sethellocount(int count) 12 hellocount = count;13 14 public int gethellocount() 15 return hellocount;16 1718 public void setusername(string username) 19 this.username = username;20 21 public string getusername() 22 return username;23 24 25 /- end of code -2.告诉quickserver用这个echoserverdata来做为它的clientdata类。 修改前面创建的echoserver.java，代码如下：01 package echoserver;0203 import .*;04 import .server.*;0506 import java.io.*;0708 public class echoserver 09 public static void main(string s) 1011 string cmd = echoserver.echocommandhandler;12 string auth = echoserver.echoserverquickauthenticator;13 string data = echoserver.echoserverdata;1415 quickserver myserver = new quickserver(cmd);16 myserver.setauthenticator(auth);17 myserver.setclientdata(data);1819 myserver.setport(4123);20 myserver.setname(echo server v 1.0);21 try 22 myserver.startserver();23 catch(appexception e)24 system.out.println(error in server : +e);25 26 27 上面的代码中，我们将配置信息写入string对象来设置quickserver。 3.修改authenticator类，也就是echoserverauthenticator类，让它在clientdata对象中存储用户名。下面是修改后的代码：01 package echoserver;0203 import .server.*;04 import java.io.*;0506 public class echoserverquickauthenticator extends quickauthenticator 0708 public boolean askauthorisation(clienthandler clienthandler)09 throws ioexception 10 string username = askstringinput(clienthandler, user name :);11 if(username!=null & username.equalsignorecase(quit) 12 sendstring(clienthandler, logged out.);13 /close the connection14 clienthandler.closeconnection();15 return false;16 1718 string password = askstringinput(clienthandler, password :);1920 if(username=null | password =null)21 return false;2223 if(username.equals(password) 24 sendstring(clienthandler, auth ok);25 /store the username in clientdata26 echoserverdata data = (echoserverdata)clienthandler.getclientdata();27 data.setusername(username);28 return true;29 else 30 sendstring(clienthandler, auth failed);31 return false;32 33 34 4.修改clientcommandhandler实现类echocommandhandler。如果用户发送hello，给他一个问候。如果他发送多次hello，告诉他已经发送了n次hello。下面是修改后的代码：01 / echocommandhandler.java02 package echoserver;0304 import .*;05 import java.io.*;06 import .server.clientcommandhandler;07 import .server.clienthandler;0809 public class echocommandhandler implements clientcommandhandler 1011 public void gotconnected(clienthandler handler)12 throws sockettimeoutexception, ioexception 13 handler.sendclientmsg(+);14 handler.sendclientmsg(| welcome to echoserver v 1.0 |);15 handler.sendclientmsg(| note: password = username |);16 handler.sendclientmsg(| send quit to exit |);17 handler.sendclientmsg(+);18 19 public void lostconnection(clienthandler handler)20 throws ioexception 21 handler.sendsystemmsg(connection lost : +22 handler.getsocket().getinetaddress();23 24 public void closingconnection(clienthandler handler)25 throws ioexception 26 handler.sendsystemmsg(closing connection : +27 handler.getsocket().getinetaddress();28 2930 public void handlecommand(clienthandler handler, string command)31 throws sockettimeoutexception, ioexception 32 if(command.equals(quit) 33 handler.sendclientmsg(bye ;-);34 handler.closeconnection();35 if(command.equalsignorecase(hello) 36 echoserverdata data = (echoserverdata) handler.getclientdata();37 data.sethellocount(data.gethellocount()+1);38 if(data.gethellocount()=1) 39 handler.sendclientmsg(hello +data.getusername();40 else 41 handler.sendclientmsg(you told hello +data.gethellocount()+42 times. );43 44 else 45 handler.sendclientmsg(echo : +command);46 47 48 5.编译改好的程序，运行，使用sockettest测试。登录后，发送hello，系统会给一个问候，再次发送hello，它将告诉你发送了多少次hello。4.2创建clientdata池 现在我们知道clientdata可以正常工作了。但是对每一个连接quickserver的客户端都要创建一个新的clientdata对象，可能会造成性能上的瓶颈，尤其对性能要求较高的服务器来说。 我们可以创建一个clientdata池对象，无论客户端什么时候进行连接，都使用同一个对象。首先实现下面的接口： org.quickserver.util.pool.poolableobject 查找quickserver api文档可以发现poolableobject只有两个必须实现的方法： mons.pool.poolableobjectfactory属于通常的工厂方法。 ispoolable()判断对象是否可以成为池对象。poolableobjectfmons.pool.poolableobjectfactory接口包含了以下方法：ovoid activateobject(object obj)：重新初始化一个实例。ovoid destroyobject(object obj)：销毁一个不再需要的实例。oobject makeobject()：创建一个实例。ovoid passivateobject(object obj)：禁止初始化一个实例。oboolean validateobject(object obj)：确定一个实例是否安全。 我们可以扩展一个基于无操作的实现来创建可池化的对象： mons.pool.basepoolableobjectfactory 这个类只有一个抽象方法makeobject()和一个validateobject()方法，它只返回true。 我们来创建一个echoserverpoolabledata类。01 /- echoserverpoolabledata.java -02 package echoserver;0304 import .server.*;05 import java.io.*;0607 public class echoserverpoolabledata08 extends echoserverdata09 implements mons.pool.poolableobjectfactory 1011 public void activateobject(object obj) 12 13 public void destroyobject(object obj) 14 if(obj=null) return;15 passivateobject(obj);16 obj = null;17 18 public object makeobject() 19 return new echoserverpoolabledata();20 21 public void passivateobject(object obj) 22 echoserverpoolabledata pd = (echoserverpoolabledata)obj;23 pd.sethellocount(0);24 pd.setusername(null);25 26 public boolean validateobject(object obj) 27 if(obj=null)28 return false;29 else30 return true;31 32 33 /- end of code - 这个类扩展了我们的echoserverdata，然后我们实现了mons.pool.basepoolableobjectfactory，这个实现是简单的不需要解释了。 现在我们需要告诉quickserver使用这个类来代替原来的clientdata类。 myserver.setclientdata(echoserver.echoserverpoolabledata); 编译修改的程序，可能会报如下错误： package mons.pool does not exist。 这是因为编译器不知道这个类。可以在环境变量中添加d:quickserverdistcommons-pool.jar包，并在运行时 set classpath=%classpath%;d:quickserverdistquickserver.jar; d:quickserverdistcommons-pool.jar;.（类所在文件夹）即可。quickserver开发手册（6）- 远程管理支持我们的echoserver可能需要修改几个服务器配置参数，如超时消息、最多验证数、最大验证时间。quickserver支持这些功能而无须改变代码。1.使用qsadminserver 当我们需要一个管理服务器来控制我们的服务器时，我们不需要修改代码甚至关闭正在运行的服务器。这项服务的实现类是： .qsadmin.qsadminserver 要使用它的功能我们要调用quickserver的startqsadminserver()方法。qsadminserver运行的默认端口是9876，我们可以使用下面两个方法之一修改它： setqsadminserverport(4124); getqsadminserver().getserver().setport(4124); 下面是能够在echoserver 的4124端口运行qsadminserver 的代码：01 package echoserver;0203 import .*;04 import .server.*;0506 import java.io.*;0708 public class echoserver 09 public static void main(string s) 1011 string cmd = echoserver.echocommandhandler;12 string auth = echoserver.echoserverquickauthenticator;13 string data = echoserver.echoserverpoolabledata; /poolable1415 quickserver myserver = new quickserver(cmd);16 myserver.setauthenticator(auth);17 myserver.setclientdata(data);1819 myserver setport(4123);20 myserver.setname(echo server v 1.0);2122 /config qsadminserver23 myserver.setqsadminserverport(4124);24 myserver.getqsadminserver().getserver().setname(echoadmin v 1.0);25 try 26 myserver.startqsadminserver();27 myserver.