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}