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.smack.packet; 019 020import java.util.Collection; 021import java.util.List; 022import java.util.Set; 023 024/** 025 * Deprecated interface of pre Smack 4.1 Stanzas. 026 * @deprecated use {@link Stanza} instead 027 */ 028@Deprecated 029public interface Packet extends TopLevelStreamElement { 030 031 String TEXT = "text"; 032 String ITEM = "item"; 033 034 /** 035 * Returns the unique ID of the stanza. The returned value could be <code>null</code>. 036 * 037 * @return the packet's unique ID or <code>null</code> if the id is not available. 038 */ 039 String getStanzaId(); 040 041 /** 042 * Get the stanza id. 043 * @return the stanza id. 044 * @deprecated use {@link #getStanzaId()} instead. 045 */ 046 @Deprecated 047 String getPacketID(); 048 049 /** 050 * Sets the unique ID of the packet. To indicate that a stanza has no id 051 * pass <code>null</code> as the packet's id value. 052 * 053 * @param id the unique ID for the packet. 054 */ 055 void setStanzaId(String id); 056 057 /** 058 * Set the stanza ID. 059 * @param packetID 060 * @deprecated use {@link #setStanzaId(String)} instead. 061 */ 062 @Deprecated 063 void setPacketID(String packetID); 064 065 /** 066 * Returns who the stanza is being sent "to", or <tt>null</tt> if 067 * the value is not set. The XMPP protocol often makes the "to" 068 * attribute optional, so it does not always need to be set.<p> 069 * 070 * @return who the stanza is being sent to, or <tt>null</tt> if the 071 * value has not been set. 072 */ 073 String getTo(); 074 075 /** 076 * Sets who the stanza is being sent "to". The XMPP protocol often makes 077 * the "to" attribute optional, so it does not always need to be set. 078 * 079 * @param to who the stanza is being sent to. 080 */ 081 void setTo(String to); 082 083 /** 084 * Returns who the stanza is being sent "from" or <tt>null</tt> if 085 * the value is not set. The XMPP protocol often makes the "from" 086 * attribute optional, so it does not always need to be set.<p> 087 * 088 * @return who the stanza is being sent from, or <tt>null</tt> if the 089 * value has not been set. 090 */ 091 String getFrom(); 092 093 /** 094 * Sets who the stanza is being sent "from". The XMPP protocol often 095 * makes the "from" attribute optional, so it does not always need to 096 * be set. 097 * 098 * @param from who the stanza is being sent to. 099 */ 100 void setFrom(String from); 101 102 /** 103 * Returns the error associated with this packet, or <tt>null</tt> if there are 104 * no errors. 105 * 106 * @return the error sub-packet or <tt>null</tt> if there isn't an error. 107 */ 108 StanzaError getError(); 109 /** 110 * Sets the error for this packet. 111 * 112 * @param error the error to associate with this packet. 113 */ 114 void setError(StanzaError error); 115 116 /** 117 * Returns the xml:lang of this Stanza, or null if one has not been set. 118 * 119 * @return the xml:lang of this Stanza, or null. 120 */ 121 String getLanguage(); 122 123 /** 124 * Sets the xml:lang of this Stanza. 125 * 126 * @param language the xml:lang of this Stanza. 127 */ 128 void setLanguage(String language); 129 130 /** 131 * Returns a copy of the stanza extensions attached to the packet. 132 * 133 * @return the stanza extensions. 134 */ 135 List<ExtensionElement> getExtensions(); 136 137 /** 138 * Return a set of all extensions with the given element name <i>and</i> namespace. 139 * <p> 140 * Changes to the returned set will update the stanza extensions, if the returned set is not the empty set. 141 * </p> 142 * 143 * @param elementName the element name, must not be null. 144 * @param namespace the namespace of the element(s), must not be null. 145 * @return a set of all matching extensions. 146 * @since 4.1 147 */ 148 Set<ExtensionElement> getExtensions(String elementName, String namespace); 149 150 /** 151 * Returns the first extension of this stanza that has the given namespace. 152 * <p> 153 * When possible, use {@link #getExtension(String,String)} instead. 154 * </p> 155 * 156 * @param namespace the namespace of the extension that is desired. 157 * @return the stanza extension with the given namespace. 158 */ 159 ExtensionElement getExtension(String namespace); 160 161 /** 162 * Returns the first stanza extension that matches the specified element name and 163 * namespace, or <tt>null</tt> if it doesn't exist. If the provided elementName is null, 164 * only the namespace is matched. Stanza extensions are 165 * are arbitrary XML sub-documents in standard XMPP packets. By default, a 166 * DefaultPacketExtension instance will be returned for each extension. However, 167 * PacketExtensionProvider instances can be registered with the 168 * {@link org.jivesoftware.smack.provider.ProviderManager ProviderManager} 169 * class to handle custom parsing. In that case, the type of the Object 170 * will be determined by the provider. 171 * 172 * @param elementName the XML element name of the stanza extension. (May be null) 173 * @param namespace the XML element namespace of the stanza extension. 174 * @param <PE> type of the ExtensionElement. 175 * @return the extension, or <tt>null</tt> if it doesn't exist. 176 */ 177 <PE extends ExtensionElement> PE getExtension(String elementName, String namespace); 178 /** 179 * Adds a stanza extension to the packet. Does nothing if extension is null. 180 * 181 * @param extension a stanza extension. 182 */ 183 void addExtension(ExtensionElement extension); 184 185 /** 186 * Adds a collection of stanza extensions to the packet. Does nothing if extensions is null. 187 * 188 * @param extensions a collection of stanza extensions 189 */ 190 void addExtensions(Collection<ExtensionElement> extensions); 191 192 /** 193 * Check if a stanza extension with the given element and namespace exists. 194 * <p> 195 * The argument <code>elementName</code> may be null. 196 * </p> 197 * 198 * @param elementName 199 * @param namespace 200 * @return true if a stanza extension exists, false otherwise. 201 */ 202 boolean hasExtension(String elementName, String namespace); 203 204 /** 205 * Check if a stanza extension with the given namespace exists. 206 * 207 * @param namespace 208 * @return true if a stanza extension exists, false otherwise. 209 */ 210 boolean hasExtension(String namespace); 211 212 /** 213 * Remove the stanza extension with the given elementName and namespace. 214 * 215 * @param elementName 216 * @param namespace 217 * @return the removed stanza extension or null. 218 */ 219 ExtensionElement removeExtension(String elementName, String namespace); 220 221 /** 222 * Removes a stanza extension from the packet. 223 * 224 * @param extension the stanza extension to remove. 225 * @return the removed stanza extension or null. 226 */ 227 ExtensionElement removeExtension(ExtensionElement extension); 228 229 @Override 230 // NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method". 231 String toString(); 232 233}