mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-06-23 20:04:51 +02:00
c9a9982cef
While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
107 lines
4.5 KiB
Java
107 lines
4.5 KiB
Java
/**
|
|
*
|
|
* Copyright 2015 Florian Schmaus
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
/**
|
|
* Smacks implementation for attaching arbitrary properties to packets according to
|
|
* https://docs.jivesoftware.com/smack/latest/documentation/properties.html.
|
|
* <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>
|
|
* <h2 id="using-the-api">Using the API</h2>
|
|
* <p>
|
|
* All major objects have property support, such as Message objects. The following code demonstrates how to set
|
|
* properties:
|
|
* </p>
|
|
*
|
|
* <pre>
|
|
* <code>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.addStanzaExtension(jpe);
|
|
chat.sendMessage(message);</code>
|
|
* </pre>
|
|
* <p>
|
|
* Getting those same properties would use the following code:
|
|
* </p>
|
|
*
|
|
* <pre>
|
|
* <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();
|
|
* </code>
|
|
* </pre>
|
|
* <p>
|
|
* For convenience <code>JivePropertiesManager</code> contains two helper methods namely
|
|
* <code>addProperty(Stanza packet, String name, Object value)</code> and
|
|
* <code>getProperty(Stanza packet, String name)</code>.
|
|
* </p>
|
|
* <h2 id="objects-as-properties">Objects as Properties</h2>
|
|
* <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>
|
|
* <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>
|
|
* <li>Serialized objects can potentially be quite large, which will use more bandwidth and server resources.</li>
|
|
* </ul>
|
|
* <h2 id="xml-format">XML Format</h2>
|
|
* <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>
|
|
*
|
|
* <pre>
|
|
* <code>
|
|
* <!-- 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>
|
|
* </code>
|
|
* </pre>
|
|
* <p>
|
|
* The currently supported types are: <code>integer</code>, <code>long</code>, <code>float</code>, <code>double</code>,
|
|
* <code>boolean</code>, <code>string</code>, and <code>java-object</code>.
|
|
* </p>
|
|
*/
|
|
package org.jivesoftware.smackx.jiveproperties;
|