Smack 文档

近期项目中要用到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收集器和监听器。

 

 有点晚了，其余的这两天在补全