mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-14 11:42:04 +01:00
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
|
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:
|
||
|
|
|
||
|
|
* When you send a Java object as a property, only clients running Java will be able to interpret the data. So, consider using a series of primitive values to transfer data instead.
|
||
|
|
* Objects sent as property values must implement Serialiable. Additionally, both the sender and receiver must have identical versions of the class, or a serialization exception will occur when de-serializing the object.
|
||
|
|
* Serialized objects can potentially be quite large, which will use more bandwidth and server resources.
|
||
|
|
|
||
|
|
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
|