001/** 002 * 003 * Copyright 2003-2007 Jive Software. 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.jivesoftware.smackx.iqprivate; 019 020import java.io.IOException; 021import java.util.HashMap; 022import java.util.Map; 023import java.util.WeakHashMap; 024 025import javax.xml.namespace.QName; 026 027import org.jivesoftware.smack.Manager; 028import org.jivesoftware.smack.SmackConfiguration; 029import org.jivesoftware.smack.SmackException.NoResponseException; 030import org.jivesoftware.smack.SmackException.NotConnectedException; 031import org.jivesoftware.smack.XMPPConnection; 032import org.jivesoftware.smack.XMPPException.XMPPErrorException; 033import org.jivesoftware.smack.packet.IQ; 034import org.jivesoftware.smack.packet.IqData; 035import org.jivesoftware.smack.packet.StanzaError.Condition; 036import org.jivesoftware.smack.packet.XmlEnvironment; 037import org.jivesoftware.smack.provider.IqProvider; 038import org.jivesoftware.smack.xml.XmlPullParser; 039import org.jivesoftware.smack.xml.XmlPullParserException; 040 041import org.jivesoftware.smackx.iqprivate.packet.DefaultPrivateData; 042import org.jivesoftware.smackx.iqprivate.packet.PrivateData; 043import org.jivesoftware.smackx.iqprivate.packet.PrivateDataIQ; 044import org.jivesoftware.smackx.iqprivate.provider.PrivateDataProvider; 045 046/** 047 * Manages private data, which is a mechanism to allow users to store arbitrary XML 048 * data on an XMPP server. Each private data chunk is defined by a element name and 049 * XML namespace. Example private data: 050 * 051 * <pre> 052 * <color xmlns="http://example.com/xmpp/color"> 053 * <favorite>blue</blue> 054 * <leastFavorite>puce</leastFavorite> 055 * </color> 056 * </pre> 057 * 058 * {@link PrivateDataProvider} instances are responsible for translating the XML into objects. 059 * If no PrivateDataProvider is registered for a given element name and namespace, then 060 * a {@link DefaultPrivateData} instance will be returned.<p> 061 * 062 * Warning: this is an non-standard protocol documented by 063 * <a href="http://www.xmpp.org/extensions/jep-0049.html">XEP-49</a>. Because this is a 064 * non-standard protocol, it is subject to change. 065 * 066 * @author Matt Tucker 067 */ 068public final class PrivateDataManager extends Manager { 069 private static final Map<XMPPConnection, PrivateDataManager> instances = new WeakHashMap<XMPPConnection, PrivateDataManager>(); 070 071 public static synchronized PrivateDataManager getInstanceFor(XMPPConnection connection) { 072 PrivateDataManager privateDataManager = instances.get(connection); 073 if (privateDataManager == null) { 074 privateDataManager = new PrivateDataManager(connection); 075 } 076 return privateDataManager; 077 } 078 079 /** 080 * Map of provider instances. 081 */ 082 private static final Map<QName, PrivateDataProvider> privateDataProviders = new HashMap<>(); 083 084 /** 085 * Returns the private data provider registered to the specified XML element name and namespace. 086 * For example, if a provider was registered to the element name "prefs" and the 087 * namespace "http://www.xmppclient.com/prefs", then the following stanza would trigger 088 * the provider: 089 * 090 * <pre> 091 * <iq type='result' to='joe@example.com' from='mary@example.com' id='time_1'> 092 * <query xmlns='jabber:iq:private'> 093 * <prefs xmlns='http://www.xmppclient.com/prefs'> 094 * <value1>ABC</value1> 095 * <value2>XYZ</value2> 096 * </prefs> 097 * </query> 098 * </iq></pre> 099 * 100 * <p>Note: this method is generally only called by the internal Smack classes. 101 * 102 * @param elementName the XML element name. 103 * @param namespace the XML namespace. 104 * @return the PrivateData provider. 105 */ 106 public static PrivateDataProvider getPrivateDataProvider(String elementName, String namespace) { 107 QName key = new QName(namespace, elementName); 108 return privateDataProviders.get(key); 109 } 110 111 /** 112 * Adds a private data provider with the specified element name and name space. The provider 113 * will override any providers loaded through the classpath. 114 * 115 * @param elementName the XML element name. 116 * @param namespace the XML namespace. 117 * @param provider the private data provider. 118 */ 119 public static void addPrivateDataProvider(String elementName, String namespace, 120 PrivateDataProvider provider) { 121 QName key = new QName(namespace, elementName); 122 privateDataProviders.put(key, provider); 123 } 124 125 /** 126 * Removes a private data provider with the specified element name and namespace. 127 * 128 * @param elementName The XML element name. 129 * @param namespace The XML namespace. 130 */ 131 public static void removePrivateDataProvider(String elementName, String namespace) { 132 QName key = new QName(namespace, elementName); 133 privateDataProviders.remove(key); 134 } 135 136 /** 137 * Creates a new private data manager. 138 * 139 * @param connection an XMPP connection which must have already undergone a 140 * successful login. 141 */ 142 private PrivateDataManager(XMPPConnection connection) { 143 super(connection); 144 instances.put(connection, this); 145 } 146 147 /** 148 * Returns the private data specified by the given element name and namespace. Each chunk 149 * of private data is uniquely identified by an element name and namespace pair.<p> 150 * 151 * If a PrivateDataProvider is registered for the specified element name/namespace pair then 152 * that provider will determine the specific object type that is returned. If no provider 153 * is registered, a {@link DefaultPrivateData} instance will be returned. 154 * 155 * @param elementName the element name. 156 * @param namespace the namespace. 157 * @return the private data. 158 * @throws XMPPErrorException if there was an XMPP error returned. 159 * @throws NoResponseException if there was no response from the remote entity. 160 * @throws NotConnectedException if the XMPP connection is not connected. 161 * @throws InterruptedException if the calling thread was interrupted. 162 */ 163 public PrivateData getPrivateData(final String elementName, final String namespace) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 164 // Create an IQ packet to get the private data. 165 IQ privateDataGet = new PrivateDataIQ(elementName, namespace); 166 167 PrivateDataIQ response = connection().sendIqRequestAndWaitForResponse( 168 privateDataGet); 169 return response.getPrivateData(); 170 } 171 172 /** 173 * Sets a private data value. Each chunk of private data is uniquely identified by an 174 * element name and namespace pair. If private data has already been set with the 175 * element name and namespace, then the new private data will overwrite the old value. 176 * 177 * @param privateData the private data. 178 * @throws XMPPErrorException if there was an XMPP error returned. 179 * @throws NoResponseException if there was no response from the remote entity. 180 * @throws NotConnectedException if the XMPP connection is not connected. 181 * @throws InterruptedException if the calling thread was interrupted. 182 */ 183 public void setPrivateData(final PrivateData privateData) throws NoResponseException, XMPPErrorException, NotConnectedException, InterruptedException { 184 // Create an IQ packet to set the private data. 185 IQ privateDataSet = new PrivateDataIQ(privateData); 186 187 connection().sendIqRequestAndWaitForResponse(privateDataSet); 188 } 189 190 private static final PrivateData DUMMY_PRIVATE_DATA = new PrivateData() { 191 @Override 192 public String getElementName() { 193 return "smackDummyPrivateData"; 194 } 195 196 @Override 197 public String getNamespace() { 198 return SmackConfiguration.SMACK_URL_STRING; 199 } 200 201 @Override 202 public CharSequence toXML() { 203 return '<' + getElementName() + " xmlns='" + getNamespace() + "'/>"; 204 } 205 }; 206 207 /** 208 * Check if the service supports private data. 209 * 210 * @return true if the service supports private data, false otherwise. 211 * @throws NoResponseException if there was no response from the remote entity. 212 * @throws NotConnectedException if the XMPP connection is not connected. 213 * @throws InterruptedException if the calling thread was interrupted. 214 * @throws XMPPErrorException if there was an XMPP error returned. 215 * @since 4.2 216 */ 217 public boolean isSupported() throws NoResponseException, NotConnectedException, 218 InterruptedException, XMPPErrorException { 219 // This is just a primitive hack, since XEP-49 does not specify a way to determine if the 220 // service supports it 221 try { 222 setPrivateData(DUMMY_PRIVATE_DATA); 223 return true; 224 } 225 catch (XMPPErrorException e) { 226 if (e.getStanzaError().getCondition() == Condition.service_unavailable) { 227 return false; 228 } 229 else { 230 throw e; 231 } 232 } 233 } 234 235 /** 236 * An IQ provider to parse IQ results containing private data. 237 */ 238 public static class PrivateDataIQProvider extends IqProvider<PrivateDataIQ> { 239 240 @Override 241 public PrivateDataIQ parse(XmlPullParser parser, int initialDepth, IqData iqData, XmlEnvironment xmlEnvironment) 242 throws XmlPullParserException, IOException { 243 PrivateData privateData = null; 244 boolean done = false; 245 while (!done) { 246 XmlPullParser.Event eventType = parser.next(); 247 if (eventType == XmlPullParser.Event.START_ELEMENT) { 248 String elementName = parser.getName(); 249 String namespace = parser.getNamespace(); 250 // See if any objects are registered to handle this private data type. 251 PrivateDataProvider provider = getPrivateDataProvider(elementName, namespace); 252 // If there is a registered provider, use it. 253 if (provider != null) { 254 privateData = provider.parsePrivateData(parser); 255 } 256 // Otherwise, use a DefaultPrivateData instance to store the private data. 257 else { 258 DefaultPrivateData data = new DefaultPrivateData(elementName, namespace); 259 boolean finished = false; 260 while (!finished) { 261 XmlPullParser.Event event = parser.next(); 262 if (event == XmlPullParser.Event.START_ELEMENT) { 263 String name = parser.getName(); 264 event = parser.next(); 265 if (event == XmlPullParser.Event.TEXT_CHARACTERS) { 266 String value = parser.getText(); 267 data.setValue(name, value); 268 } 269 else if (event == XmlPullParser.Event.END_ELEMENT) { 270 // If an empty element, set the value with the empty string. 271 data.setValue(name, ""); 272 } 273 } 274 else if (event == XmlPullParser.Event.END_ELEMENT) { 275 if (parser.getName().equals(elementName)) { 276 finished = true; 277 } 278 } 279 } 280 privateData = data; 281 } 282 } 283 else if (eventType == XmlPullParser.Event.END_ELEMENT) { 284 if (parser.getName().equals("query")) { 285 done = true; 286 } 287 } 288 } 289 return new PrivateDataIQ(privateData); 290 } 291 } 292}