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 public static final String TEXT = "text"; 032 public static final 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 public String getStanzaId(); 040 041 /** 042 * 043 * @return the stanza id. 044 * @deprecated use {@link #getStanzaId()} instead. 045 */ 046 @Deprecated 047 public String getPacketID(); 048 049 /** 050 * Sets the unique ID of the packet. To indicate that a stanza(/packet) 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 public void setStanzaId(String id); 056 057 /** 058 * 059 * @param packetID 060 * @deprecated use {@link #setStanzaId(String)} instead. 061 */ 062 @Deprecated 063 public void setPacketID(String packetID); 064 065 /** 066 * Returns who the stanza(/packet) 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(/packet) is being sent to, or <tt>null</tt> if the 071 * value has not been set. 072 */ 073 public String getTo(); 074 075 /** 076 * Sets who the stanza(/packet) 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(/packet) is being sent to. 080 */ 081 public void setTo(String to); 082 083 /** 084 * Returns who the stanza(/packet) 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(/packet) is being sent from, or <tt>null</tt> if the 089 * value has not been set. 090 */ 091 public String getFrom(); 092 093 /** 094 * Sets who the stanza(/packet) 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(/packet) is being sent to. 099 */ 100 public 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 public XMPPError getError(); 109 /** 110 * Sets the error for this packet. 111 * 112 * @param error the error to associate with this packet. 113 */ 114 public void setError(XMPPError 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 public String getLanguage(); 122 123 /** 124 * Sets the xml:lang of this Stanza. 125 * 126 * @param language the xml:lang of this Stanza. 127 */ 128 public void setLanguage(String language); 129 130 /** 131 * Returns a copy of the stanza(/packet) extensions attached to the packet. 132 * 133 * @return the stanza(/packet) extensions. 134 */ 135 public List<ExtensionElement> getExtensions(); 136 137 /** 138 * Return a set of all extensions with the given element name <emph>and</emph> namespace. 139 * <p> 140 * Changes to the returned set will update the stanza(/packet) 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 public Set<ExtensionElement> getExtensions(String elementName, String namespace); 149 150 /** 151 * Returns the first extension of this stanza(/packet) 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(/packet) extension with the given namespace. 158 */ 159 public ExtensionElement getExtension(String namespace); 160 161 /** 162 * Returns the first stanza(/packet) 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(/Packet) 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(/packet) extension. (May be null) 173 * @param namespace the XML element namespace of the stanza(/packet) extension. 174 * @return the extension, or <tt>null</tt> if it doesn't exist. 175 */ 176 public <PE extends ExtensionElement> PE getExtension(String elementName, String namespace); 177 /** 178 * Adds a stanza(/packet) extension to the packet. Does nothing if extension is null. 179 * 180 * @param extension a stanza(/packet) extension. 181 */ 182 public void addExtension(ExtensionElement extension); 183 184 /** 185 * Adds a collection of stanza(/packet) extensions to the packet. Does nothing if extensions is null. 186 * 187 * @param extensions a collection of stanza(/packet) extensions 188 */ 189 public void addExtensions(Collection<ExtensionElement> extensions); 190 191 /** 192 * Check if a stanza(/packet) extension with the given element and namespace exists. 193 * <p> 194 * The argument <code>elementName</code> may be null. 195 * </p> 196 * 197 * @param elementName 198 * @param namespace 199 * @return true if a stanza(/packet) extension exists, false otherwise. 200 */ 201 public boolean hasExtension(String elementName, String namespace); 202 203 /** 204 * Check if a stanza(/packet) extension with the given namespace exists. 205 * 206 * @param namespace 207 * @return true if a stanza(/packet) extension exists, false otherwise. 208 */ 209 public boolean hasExtension(String namespace); 210 211 /** 212 * Remove the stanza(/packet) extension with the given elementName and namespace. 213 * 214 * @param elementName 215 * @param namespace 216 * @return the removed stanza(/packet) extension or null. 217 */ 218 public ExtensionElement removeExtension(String elementName, String namespace); 219 220 /** 221 * Removes a stanza(/packet) extension from the packet. 222 * 223 * @param extension the stanza(/packet) extension to remove. 224 * @return the removed stanza(/packet) extension or null. 225 */ 226 public ExtensionElement removeExtension(ExtensionElement extension); 227 228 @Override 229 // NOTE When Smack is using Java 8, then this method should be moved in Element as "Default Method". 230 public String toString(); 231 232}