近期项目中要用到openfire smack 为让自己更快熟悉和别人阅读方便，针对 Smack 4.1.1 api文档翻译
Smack 文档
内容:
- 概述
- 入门指南
- 连接管理
- 消息传递
- Roster and Presence
- 处理传入的 Stanzas
- Provider 架构
- Smack 调试
- Smack 扩展
概述
Smack是一个沟通的Library,用来和XMPP服务器进行实时通信,包括即时消息和群组聊天。
Smack的主要优势
- 简单而易用,且功能强大的API.发送消息给用户可以完成在只有几行代码:
AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org");
connection.connect().login();
Chat chat = ChatManager.getInstanceFor(connection).createChat("[email protected]", new MessageListener() {
public void processMessage(Chat chat, Message message) {
System.out.println("Received message: " + message);
}
});
chat.sendMessage("Howdy!");
- 不像其它类库那样强制你进行包级别的编码. Smack 在Chat和Roster类中提供更加智能的结构层次,让你的编程更有效。
- 不需用你熟悉XMPP XML格式,即使您熟悉 XML。
- 提供简单的设计以进行通讯,Smack可以在每个消息中设置任意数量的属性,包括Java对象的属性。
- Apache许可下的开源类库，这意味着您可以将Smack使用到你的商业或非商业的应用中。
关于 XMPP
XMPP (eXtensible Messaging and Presence Protocol)是一个由Jabber Software Foundation (http://www.xmpp.org)领导的开放的基于XML的协议，并且获得了 IETF的批准。
怎样使用该文档
本文档假设你已经熟悉XMPP即时消息的主要特点。也强烈建议您打开Javadoc API和指导使用,阅读这些文档时作为参考。
入门指南
本文档将会向您介绍Smack API，及简要介绍一些重要的类和概念。
JAR文件和要求
Smack 是很容易嵌入到任何现有Java应用程序中的。这个类库中只有几个JAR包 为应用程序提供更加强大的灵活性：
smack-core.jar -- 提供核心XMPP功能。所有XMPP特性包括XMPP RFCS的一部分。smack-tcp.jar -- 对XMPP支持TCP。包括你通常想要使用XMPPTCPConnection类。smack-extensions.jar -- 在XMPP标准定义的基础上支持许多扩展(XEPs),包括多用户聊天,文件传输,用户搜索等等。这些扩展备份在扩展手册中。smack-experimental.jar -- 在XMPP标准定义的基础上支持实验扩展(XEPs)。这些扩展的API和功能应该被认为是不稳定的。smack-legacy.jar --在XMPP标准定义的定义上支持遗留扩展(XEPs)。smack-bosh.jar -- 对BOSH (XEP-0124)的支持。这样编程应该被定义为测试版。smack-jingle.jar -- 对Jingle支持。但到目前为止经常没有维护。smack-resolver-dnsjava.jar -- 在dnsjava的帮助下支持解析DNS SRV记录。理想的平台,不支持javax。smack-resolver-javax.jar -- 与javax命名空间API一起支持解决DNS SRV记录smack-debug.jar -- 一个有图形界面的增强型调试器。它会在类中允许启动时自动开启。
配置
Smack有一个涉及2个阶段的初始化过程。
- 初始化系统属性 -- 通过类SmackConfiguration可以初始化所有的系统属性。这些属性可以在类中通过getxxx()取到
- 初始化启动类 -- 初始化任何类都要通过实例类,然后调用initialize方法如果继承至SmackInitializer类。如果它不是继承这个接口,那么初始化必须发生在一个静态的方法中，在类加载完成时自动执行。
初始化是通过一个配置文件来完成的。默认情况下,Smack将在Smack.jar中的org.jivesoftware.smack/smack- config.xml上加载。这个特殊的结构包含一个初始化类列表加载。所有需要初始化的Manager类都包含在这个初始化类列表中。
建立连接
XMPPConnection类用来建立到XMPP服务器连接。下面是建立连接的例子：
//为jabber.org 服务器创建一个连接
AbstractXMPPConnection conn1 = new XMPPTCPConnection("username", "password" "jabber.org");
conn1.connect();
//为jabber.org 服务器在一个特定的端口上创建一个连接
XMPPTCPConnectionConfiguration config = XMPPTCPConnectionConfiguration.builder()
.setUsernameAndPassword("username", "password")
.setServiceName("jabber.org")
.setHost("earl.jabber.org")
.setPort("8222")
.build();
AbstractXMPPConnection conn2 = new XMPPTCPConnection(config);
conn2.connect();
注意，在连接服务器时最安全的方式就是默认连接(如果可以的话)包括使用TLS加密。ConnectionConfiguration类提供了高级管理创建连接,如开启和禁用加密能力,观察XMPPConnection完整的管理流程。
一旦你创建了一个连接,你必须和XMPPConnection.login()方法一起登录。当你登录后,你就可以通过创建chat和chatGroup对象来和其他用进行聊天了。
操作Roster
Roster能够让你跟踪其它用户的有效性（存在）。用户可以通过使用像“朋友”和“同事”这样的组来组织用户，这样可以发现每个用户是否在线。
通过使用Roster.getInstanceFor(XMPPConnection)这个方法得到Roster。通过Roster类您可以找到所有Roster entries、他们所属的组以及每个entry当前的存在状态。
读写Stanzas
从客户端以XML格式发送到XMPP服务器的每个消息被称为一个“packet”。org.jivesoftware.smack.packet包中包含了一些类，这些类封装了XMPP所允许的三个不同的基本 packet类型(message, presence, 和 IQ)。 像Chat和GroupChat这样的类提供了更高类别 的构造能够自动地创建和发送packet，但是您也可以直接创建和发送packet。 下面是一个通过改变您的presence来让别人知道您已无效，已经"out fishing"了:
// 创建一个新的presence. 传入false以表明我们已经无效了
Presence presence = new Presence(Presence.Type.unavailable);
presence.setStatus("Gone fishing");
// 发送packet (假设已经有了一个名为"con"的XMPPConnection实例).
con.sendStanza(presence);
Smack提供两种方法读取收到的packet：PacketListener[packet监听器]和PacketCollector[packet收集器]。 二者都是使用StanzaFilter实例来决定哪个packet应该被处理。packet监听器用于事件样式的编程，而packet收集器有一个可以做轮询和阻塞操作的packet的结果队列。所以，当您想对一个有可能随时到来的packet采取一些操作时，使用packet监听器；而当您想等待一个特别的packet到来时，使用 packet收集器。您可以使用XMPPConnection实例创建packet收集器和监听器。
有点晚了，其余的这两天在补全