org.jivesoftware.smackx.jiveproperties.package-info Maven / Gradle / Ivy
Show all versions of smack-extensions Show documentation
/**
*
* 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.
*
* 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.addStanzaExtension(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(Stanza packet, String name, Object value) and
* getProperty(Stanza 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 Serializable. 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.
*
*/
package org.jivesoftware.smackx.jiveproperties;