mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-25 07:42:06 +01:00
6e08a10186
Code for Jive's packet properties should not be in 'core'. Also de-serializing input from network causes some security implications, it is therefore disabled as default.
123 lines
4.1 KiB
HTML
123 lines
4.1 KiB
HTML
<html>
|
|
<head>
|
|
<title>Smack: Packet Properties - Jive Software</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="header">
|
|
Packet Properties
|
|
</div>
|
|
|
|
<p>
|
|
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).
|
|
</p>
|
|
|
|
<p class="subheader">
|
|
Using the API
|
|
</p>
|
|
|
|
<p>
|
|
All major objects have property support, such as Message objects. The following code
|
|
demonstrates how to set properties:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
Message message = chat.createMessage();
|
|
JivePropertiesExtension jpe = new JivePropertiesExtension();
|
|
<font color="gray"><i>// Add a Color object as a property.</i></font>
|
|
jpe.setProperty(<font color="blue">"favoriteColor"</font>, new Color(0, 0, 255));
|
|
<font color="gray"><i>// Add an int as a property.</i></font>
|
|
jpe.setProperty(<font color="blue">"favoriteNumber"</font>, 4);
|
|
<font color="gray"><i>// Add the JivePropertiesExtension to the message packet</i></font>
|
|
message.addPacketExtension(jpe);
|
|
chat.sendMessage(message);
|
|
</pre></div>
|
|
|
|
<p>
|
|
Getting those same properties would use the following code:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
Message message = chat.nextMessage();
|
|
<font color="gray"><i>// Get the JivePropertiesExtension</i></font>
|
|
JivePropertiesExtension jpe = message.getExtension(JivePropertiesExtension.NAMESPACE);
|
|
<font color="gray"><i>// Get a Color object property.</i></font>
|
|
Color favoriteColor = (Color)jpe.getProperty(<font color="blue">"favoriteColor"</font>);
|
|
<font color="gray"><i>// 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.</i></font>
|
|
int favoriteNumber = ((Integer)jpe.getProperty(<font color="blue">"favoriteNumber"</font>)).intValue();
|
|
</pre></div>
|
|
|
|
<p>
|
|
For convenience <code>JivePropertiesManager</code> contains two helper
|
|
methods namely <code>addProperty(Packet packet, String name, Object
|
|
value)</code> and
|
|
<code>getProperty(Packet packet, String name)</code>.
|
|
</p>
|
|
|
|
<p class="subheader">
|
|
Objects as Properties
|
|
</p>
|
|
|
|
<p>
|
|
Using objects as property values is a very powerful and easy way to exchange data. However,
|
|
you should keep the following in mind:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>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.
|
|
|
|
<li>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.
|
|
|
|
<li>Serialized objects can potentially be quite large, which will use more bandwidth and
|
|
server resources.
|
|
</ul>
|
|
|
|
<p class="subheader">
|
|
XML Format
|
|
</p>
|
|
|
|
<p>
|
|
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):
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
<font color="gray"><i><!-- All properties are in a x block. --></i></font>
|
|
<properties xmlns="http://www.jivesoftware.com/xmlns/xmpp/properties">
|
|
<font color="gray"><i><!-- First, a property named "prop1" that's an integer. --></i></font>
|
|
<property>
|
|
<name>prop1</name>
|
|
<value type="integer">123</value>
|
|
<property>
|
|
<font color="gray"><i><!-- Next, a Java object that's been serialized and then converted
|
|
from binary data to base-64 encoded text. --></i></font>
|
|
<property>
|
|
<name>blah2</name>
|
|
<value type="java-object">adf612fna9nab</value>
|
|
<property>
|
|
</properties>
|
|
</pre></div>
|
|
|
|
<p>
|
|
The currently supported types are: <tt>integer</tt>, <tt>long</tt>, <tt>float</tt>,
|
|
<tt>double</tt>, <tt>boolean</tt>, <tt>string</tt>, and <tt>java-object</tt>.
|
|
</p>
|
|
|
|
<div class="footer">
|
|
Copyright © Jive Software 2002-2008
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|