Packet Properties

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();
JivePropertiesExtension jpe = new JivePropertiesExtension();
// Add a Color object as a property._
jpe.setProperty("favoriteColor", new Color(0, 0, 255));
// Add an int as a property._
jpe.setProperty("favoriteNumber", 4);
// Add the JivePropertiesExtension to the message packet_
message.addPacketExtension(jpe);
chat.sendMessage(message);

Getting those same properties would use the following code:

Message message = chat.nextMessage();
// Get the JivePropertiesExtension_
JivePropertiesExtension jpe = message.getExtension(JivePropertiesExtension.NAMESPACE);
// Get a Color object property._
Color favoriteColor = (Color)jpe.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)jpe.getProperty("favoriteNumber")).intValue();

For convenience JivePropertiesManager contains two helper methods namely addProperty(Packet packet, String name, Object value) and getProperty(Packet packet, String name).

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. -->
<properties 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>
</properties>

The currently supported types are: integer, long, float, double, boolean, string, and java-object.

Copyright (C) Jive Software 2002-2008