+Smack includes a built-in debugging console that will let you track all XML traffic between +the client and server. +
+ ++When debugging mode is enabled, a debug window will appear when each new connection is created. +The window will contain the following information: +
+ +
+
++Debugging mode can be enabled in two different ways: +
+ ++ XMPPConection.DEBUG_ENABLED = true;
+ +
+ java SomeApp -Dsmack.debugEnabled=true. +
+If you wish to explicity disable debug mode in your application, including using the command-line parameter, +add the following line to your application before opening new connections: +
+ ++XMPPConnection.DEBUG_ENABLED = false; +
+ ++This document will introduce you to the Smack API and provide an overview of +important classes and concepts. +
+ ++Requirements +
+ +The only requirement for Smack is JDK 1.2 or later. An XML parser is embedded in the smack.jar +file and no other third party libraries are required. + ++Establishing a Connection +
+ +The XMPPConnection class is used to create a connection to an +XMPP server. To create an SSL connection, use the SSLXMPPConnection class. +Below are code examples for making a connection:+ +
+// Create a connection to the jabber.org server.
+XMPPConnection conn1 = new XMPPConnection("jabber.org");
+
+// Create a connection to the jabber.org server on a specific port.
+XMPPConnection conn2 = new XMPPConnection("jabber.org", 5222);
+
+// Create an SSL connection to jabber.org.
+XMPPConnection connection = new SSLXMPPConnection("jabber.org");
+Once you've created a connection, you should login using a username and password +with the XMPPConnection.login(String username, String password) method. +Once you've logged in, you can being chatting with other users by creating +new Chat or GroupChat objects. + +
+Working with the Roster +
+ +CONTENT COMING SOON + ++Packets, the PacketReader, and the PacketWriter +
+ +Each message to the XMPP server from a client is called a packet and is +sent as XML. The org.jivesoftware.smack.packet package contains +classes that encapsulate the different packet types allowed by XMPP (message, +presence, and IQ). Classes such as Chat and GroupChat +provide higher-level constructs that manage creating and sending packets +automatically, but you can also create and send packets directly. Below +is a code example for changing the presence to let people we're unavailable +because we're out fishing:+ +
+// Create a new presence. Pass in false to indicate we're unavailable.
+Presence presence = new Presence(false);
+presence.setStatus("Gone fishing");
+// Send the packet (assume we have a XMPPConnection instance called "con").
+con.getPacketWriter().sendPacket(presence);
++ +Every connection has a PacketReader and PacketWriter. The +packet reader listens for XML data from the server and parses it into +individual packets. You can listen for incoming packets by registering +PacketWatcher objects with the packet reader. The packet writer +is responsible for writing packets to the server. It takes Packet +objects and converts them to XML before sending them over the network. + + +
+ + + \ No newline at end of file diff --git a/documentation/images/debugwindow.gif b/documentation/images/debugwindow.gif new file mode 100644 index 000000000..e53c5dc33 Binary files /dev/null and b/documentation/images/debugwindow.gif differ diff --git a/documentation/index.html b/documentation/index.html new file mode 100644 index 000000000..006a01cae --- /dev/null +++ b/documentation/index.html @@ -0,0 +1,30 @@ + + ++Documentation Contents: +
+ + + + + + + diff --git a/documentation/overview.html b/documentation/overview.html new file mode 100644 index 000000000..56e9b4d4a --- /dev/null +++ b/documentation/overview.html @@ -0,0 +1,55 @@ + + ++ +Smack is a library for communicating with XMPP (Jabber) servers to perform +instant messaging and chat. + +
+Key Advantages: +
+ +
+XMPPConnection connection = new XMPPConnection("jabber.org");
+connection.login("mtucker", "password");
+connection.createChat("jsmith@jivesoftware.com").sendMessage("Howdy!");
++Smack provides an easy mechanism for attaching arbitrary properties to packets. Each property +has a String name, and a value that is a Java primitive (int, long, float, double, boolean) or +any Serializable object (a Java object is Serializable when it implements the Serializable +interface). +
+ ++Using the API +
+ ++All major objects have property support, such as Message objects. The following code +demonstrates how to set properties: +
+ +
+Message message = chat.createMessage();
+// Add a Color object as a property.
+message.setProperty("favoriteColor", new Color(0, 0, 255));
+// Add an int as a property.
+message.setProperty("favoriteNumber", 4);
+chat.sendMessage(message);
++Getting those same properties would use the following code: +
+ +
+Message message = chat.nextMessage();
+// Get a Color object property.
+Color favoriteColor = (Color)message.getProperty("favoriteColor");
+// Get an int property. Note that properties are always returned as
+// Objects, so we must cast the value to an Integer, then convert
+// it to an int.
+int favoriteNumber = ((Integer)message.getProperty("favoriteNumber")).intValue();
++Objects as Properties +
+ ++Using objects as property values is a very powerful and easy way to exchange data. However, +you should keep the following in mind: +
+ ++XML Format +
+ ++The current XML format used to send property data is not a standard, so will likely not be +recognized by clients not using Smack. The XML looks like the following (comments added for +clarity): +
+ ++<!-- All properties are in a x block. --> +<x xmlns="http://www.jivesoftware.com/xmlns/xmpp/properties"> + <!-- First, a property named "prop1" that's an integer. --> + <property> + <name>prop1</name> + <value type="integer">123</value> + <property> + <!-- Next, a Java object that's been serialized and then converted + from binary data to base-64 encoded text. --> + <property> + <name>blah2</name> + <value type="java-object">adf612fna9nab</value> + <property> +</x> +
+The currently supported types are: integer, long, float, +double, boolean, string, and java-object. +
+ + + + + diff --git a/documentation/style.css b/documentation/style.css new file mode 100644 index 000000000..082da56a1 --- /dev/null +++ b/documentation/style.css @@ -0,0 +1,56 @@ +BODY { + font-size : 100%; + background-color : #fff; +} +BODY, TD, TH { + font-family : tahoma, arial, helvetica; + font-size : 0.8em; +} +PRE, TT, CODE { + font-family : courier new, monospaced; + font-size : 1.0em; +} +A:hover { + text-decoration : none; +} +LI { + padding-bottom : 4px; +} +.header { + font-size : 1.4em; + font-weight : bold; + width : 100%; + border-bottom : 1px #ccc solid; + padding-bottom : 2px; +} +.subheader { + font-weight : bold; +} +.footer { + font-size : 0.8em; + color : #999; + text-align : center; + width : 100%; + border-top : 1px #ccc solid; + padding-top : 2px; +} +.code { + border : 1px #ccc solid; + padding : 0em 1.0em 0em 1.0em; + margin : 4px 0px 4px 0px; +} +.nav, .nav A { + font-family : verdana; + font-size : 0.85em; + color : #600; + text-decoration : none; + font-weight : bold; +} +.nav { + width : 100%; + border-bottom : 1px #ccc solid; + padding : 3px 3px 5px 1px; +} +.nav A:hover { + text-decoration : underline; +} \ No newline at end of file