001/**
002 *
003 * Copyright 2019-2024 Florian Schmaus
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 */
017package org.jivesoftware.smack.packet;
018
019import java.util.List;
020
021import javax.xml.namespace.QName;
022
023import org.jivesoftware.smack.util.XmppElementUtil;
024
025import org.jxmpp.jid.Jid;
026
027public interface StanzaView extends XmlLangElement {
028
029    /**
030     * Returns the unique ID of the stanza. The returned value could be <code>null</code>.
031     *
032     * @return the packet's unique ID or <code>null</code> if the id is not available.
033     */
034    String getStanzaId();
035
036    /**
037     * Returns who the stanza is being sent "to", or <code>null</code> if
038     * the value is not set. The XMPP protocol often makes the "to"
039     * attribute optional, so it does not always need to be set.
040     *
041     * @return who the stanza is being sent to, or <code>null</code> if the
042     *      value has not been set.
043     */
044    Jid getTo();
045
046    /**
047     * Returns who the stanza is being sent "from" or <code>null</code> if
048     * the value is not set. The XMPP protocol often makes the "from"
049     * attribute optional, so it does not always need to be set.
050     *
051     * @return who the stanza is being sent from, or <code>null</code> if the
052     *      value has not been set.
053     */
054    Jid getFrom();
055
056    /**
057     * Returns the error associated with this packet, or <code>null</code> if there are
058     * no errors.
059     *
060     * @return the error sub-packet or <code>null</code> if there isn't an error.
061     */
062    StanzaError getError();
063
064    XmlElement getExtension(QName qname);
065
066    default boolean hasExtension(QName qname) {
067        return getExtension(qname) != null;
068    }
069
070    default boolean hasExtension(Class<? extends ExtensionElement> extensionElementClass) {
071        return getExtension(extensionElementClass) != null;
072    }
073
074    /**
075     * Check if a extension element with the given namespace exists.
076     *
077     * @param namespace the namespace of the extension element to check for.
078     * @return true if a stanza extension exists, false otherwise.
079     */
080    default boolean hasExtension(String namespace) {
081        for (XmlElement packetExtension : getExtensions()) {
082            if (packetExtension.getNamespace().equals(namespace)) {
083                return true;
084            }
085        }
086
087        return false;
088    }
089
090    default <E extends ExtensionElement> E getExtension(Class<E> extensionElementClass) {
091        QName qname = XmppElementUtil.getQNameFor(extensionElementClass);
092        XmlElement extensionElement = getExtension(qname);
093
094        if (extensionElement == null) {
095            return null;
096        }
097
098        return XmppElementUtil.castOrThrow(extensionElement, extensionElementClass);
099    }
100
101    /**
102     * Returns a list of all extension elements of this stanza.
103     *
104     * @return a list of all extension elements of this stanza.
105     */
106    List<XmlElement> getExtensions();
107
108    List<XmlElement> getExtensions(QName qname);
109
110    /**
111     * Return all extension elements of the given type. Returns the empty list if there a none.
112     *
113     * @param <E> the type of extension elements.
114     * @param extensionElementClass the class of the type of extension elements.
115     * @return a list of extension elements of that type, which may be empty.
116     */
117    <E extends ExtensionElement> List<E> getExtensions(Class<E> extensionElementClass);
118}