From 3c3b3d5cdf49d798ab003e69f4433359dc96f1d7 Mon Sep 17 00:00:00 2001 From: Matt Tucker Date: Wed, 20 Aug 2003 16:03:32 +0000 Subject: [PATCH] Javadoc improvements. git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2049 b35dd754-fafc-0310-a699-88a17e54d16e --- .../smackx/PrivateDataManager.java | 39 ++++++++++++++----- .../smackx/packet/DefaultPrivateData.java | 2 +- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/source/org/jivesoftware/smackx/PrivateDataManager.java b/source/org/jivesoftware/smackx/PrivateDataManager.java index 611da74c2..4cbc7fb55 100644 --- a/source/org/jivesoftware/smackx/PrivateDataManager.java +++ b/source/org/jivesoftware/smackx/PrivateDataManager.java @@ -65,7 +65,20 @@ import java.util.Map; import java.util.Hashtable; /** - * Manages private data. + * Manages private data, which is a mechanism to allow users to store arbitrary XML + * data on an XMPP server. Each private data chunk is defined by a element name and + * XML namespace. Example private data: + * + * 
+ * <color xmlns="http://example.com/xmpp/color">
+ *     <favorite>blue</blue>
+ *     <leastFavorite>puce</leastFavorite>
+ * </color>
+ *
+ * + * {@link PrivateDataProvider} instances are responsible for translating the XML into objects. + * If no PrivateDataProvider is registered for a given element name and namespace, then + * a {@link DefaultPrivateData} instance will be returned. * * @author Matt Tucker */ @@ -119,15 +132,21 @@ public class PrivateDataManager { } - private XMPPConnection con; + private XMPPConnection connection; /** - * Creates a new private data manager. + * Creates a new private data manager. The connection must have + * undergone a successful login before being used to construct an instance of + * this class. * - * @param con an XMPPConnection. + * @param connection an XMPP connection which must have already undergone a + * successful login. */ - public PrivateDataManager(XMPPConnection con) { - this.con = con; + public PrivateDataManager(XMPPConnection connection) { + if (!connection.isAuthenticated()) { + throw new IllegalStateException("Must be logged in to XMPP server."); + } + this.connection = connection; } /** @@ -160,10 +179,10 @@ public class PrivateDataManager { // Setup a listener for the reply to the set operation. String packetID = privateDataGet.getPacketID(); - PacketCollector collector = con.createPacketCollector(new PacketIDFilter(packetID)); + PacketCollector collector = connection.createPacketCollector(new PacketIDFilter(packetID)); // Send the private data. - con.sendPacket(privateDataGet); + connection.sendPacket(privateDataGet); // Wait up to five seconds for a response from the server. IQ response = (IQ)collector.nextResult(5000); @@ -200,10 +219,10 @@ public class PrivateDataManager { // Setup a listener for the reply to the set operation. String packetID = privateDataSet.getPacketID(); - PacketCollector collector = con.createPacketCollector(new PacketIDFilter(packetID)); + PacketCollector collector = connection.createPacketCollector(new PacketIDFilter(packetID)); // Send the private data. - con.sendPacket(privateDataSet); + connection.sendPacket(privateDataSet); // Wait up to five seconds for a response from the server. IQ response = (IQ)collector.nextResult(5000); diff --git a/source/org/jivesoftware/smackx/packet/DefaultPrivateData.java b/source/org/jivesoftware/smackx/packet/DefaultPrivateData.java index 40cd1b5f4..66ee7c87d 100644 --- a/source/org/jivesoftware/smackx/packet/DefaultPrivateData.java +++ b/source/org/jivesoftware/smackx/packet/DefaultPrivateData.java @@ -75,7 +75,7 @@ import java.util.HashMap; * In this case, getValue("color") would return "blue", and getValue("food") would * return "pizza". This parsing mechanism mechanism is very simplistic and will not work * as desired in all cases (for example, if some of the elements have attributes. In those - * cases, a custom PrivateDataProvider should be used. + * cases, a custom {@link org.jivesoftware.smackx.provider.PrivateDataProvider} should be used. * * @author Matt Tucker */