/** * * Copyright 2003-2007 Jive Software. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smack.packet; import static org.jivesoftware.smack.util.StringUtils.requireNotNullOrEmpty; import org.jivesoftware.smack.packet.id.StanzaIdUtil; import org.jivesoftware.smack.util.MultiMap; import org.jivesoftware.smack.util.PacketUtil; import org.jivesoftware.smack.util.XmlStringBuilder; import org.jxmpp.jid.Jid; import org.jxmpp.jid.impl.JidCreate; import org.jxmpp.stringprep.XmppStringprepException; import org.jxmpp.util.XmppStringUtils; import java.util.Collection; import java.util.List; import java.util.Locale; import java.util.Set; /** * Base class for XMPP Stanzas, which are called Stanza(/Packet) in older versions of Smack (i.e. < 4.1). *
* Every stanza has a unique ID (which is automatically generated, but can be overridden). Stanza * IDs are required for IQ stanzas and recommended for presence and message stanzas. Optionally, the * "to" and "from" fields can be set. *
** XMPP Stanzas are {@link Message}, {@link IQ} and {@link Presence}. Which therefore subclass this * class. If you think you need to subclass this class, then you are doing something wrong. *
* * @author Matt Tucker * @see RFC 6120 ยง 8. XML Stanzas */ public abstract class Stanza implements TopLevelStreamElement { public static final String TEXT = "text"; public static final String ITEM = "item"; protected static final String DEFAULT_LANGUAGE = java.util.Locale.getDefault().getLanguage().toLowerCase(Locale.US); private final MultiMap
* Such an attribute is defined for all stanza types. For IQ, see for
* example XEP-50 3.7:
* "The requester SHOULD provide its locale information using the "xml:lang
* " attribute on either the
null
.
*
* @return the packet's unique ID or null
if the id is not available.
*/
public String getStanzaId() {
return id;
}
/**
* Get the Stanza ID.
* @return the stanza id.
* @deprecated use {@link #getStanzaId()} instead.
*/
@Deprecated
public String getPacketID() {
return getStanzaId();
}
/**
* Sets the unique ID of the packet. To indicate that a stanza(/packet) has no id
* pass null
as the packet's id value.
*
* @param id the unique ID for the packet.
*/
public void setStanzaId(String id) {
if (id != null) {
requireNotNullOrEmpty(id, "id must either be null or not the empty String");
}
this.id = id;
}
/**
* Set the stanza ID.
* @param packetID
* @deprecated use {@link #setStanzaId(String)} instead.
*/
@Deprecated
public void setPacketID(String packetID) {
setStanzaId(packetID);
}
/**
* Check if this stanza has an ID set.
*
* @return true if the stanza ID is set, false otherwise.
* @since 4.1
*/
public boolean hasStanzaIdSet() {
// setStanzaId ensures that the id is either null or not empty,
// so we can assume that it is set if it's not null.
return id != null;
}
/**
* Returns who the stanza(/packet) is being sent "to", or null if
* the value is not set. The XMPP protocol often makes the "to"
* attribute optional, so it does not always need to be set.* * @return who the stanza(/packet) is being sent to, or null if the * value has not been set. */ public Jid getTo() { return to; } /** * Sets who the stanza(/packet) is being sent "to". The XMPP protocol often makes * the "to" attribute optional, so it does not always need to be set. * * @param to who the stanza(/packet) is being sent to. * @throws IllegalArgumentException if to is not a valid JID String. * @deprecated use {@link #setTo(Jid)} instead. */ @Deprecated public void setTo(String to) { Jid jid; try { jid = JidCreate.from(to); } catch (XmppStringprepException e) { throw new IllegalArgumentException(e); } setTo(jid); } /** * Sets who the packet is being sent "to". The XMPP protocol often makes * the "to" attribute optional, so it does not always need to be set. * * @param to who the packet is being sent to. */ public void setTo(Jid to) { this.to = to; } /** * Returns who the stanza(/packet) is being sent "from" or null if * the value is not set. The XMPP protocol often makes the "from" * attribute optional, so it does not always need to be set.
*
* @return who the stanza(/packet) is being sent from, or null if the
* value has not been set.
*/
public Jid getFrom() {
return from;
}
/**
* Sets who the stanza(/packet) is being sent "from". The XMPP protocol often
* makes the "from" attribute optional, so it does not always need to
* be set.
*
* @param from who the stanza(/packet) is being sent to.
* @throws IllegalArgumentException if from is not a valid JID String.
* @deprecated use {@link #setFrom(Jid)} instead.
*/
@Deprecated
public void setFrom(String from) {
Jid jid;
try {
jid = JidCreate.from(from);
}
catch (XmppStringprepException e) {
throw new IllegalArgumentException(e);
}
setFrom(jid);
}
/**
* Sets who the packet is being sent "from". The XMPP protocol often
* makes the "from" attribute optional, so it does not always need to
* be set.
*
* @param from who the packet is being sent to.
*/
public void setFrom(Jid from) {
this.from = from;
}
/**
* Returns the error associated with this packet, or null if there are
* no errors.
*
* @return the error sub-packet or null if there isn't an error.
*/
public XMPPError getError() {
return error;
}
/**
* Sets the error for this packet.
*
* @param error the error to associate with this packet.
*/
public void setError(XMPPError error) {
this.error = error;
}
/**
* Returns the xml:lang of this Stanza, or null if one has not been set.
*
* @return the xml:lang of this Stanza, or null.
*/
public String getLanguage() {
return language;
}
/**
* Sets the xml:lang of this Stanza.
*
* @param language the xml:lang of this Stanza.
*/
public void setLanguage(String language) {
this.language = language;
}
/**
* Returns a list of all extension elements of this stanza.
*
* @return a list of all extension elements of this stanza.
*/
public List
* Changes to the returned set will update the stanza(/packet) extensions, if the returned set is not the empty set.
*
* When possible, use {@link #getExtension(String,String)} instead.
*
* The argument elementName
may be null.
*