001/**
002 *
003 * Copyright 2013-2014 the original author or authors
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.smackx.receipts;
018
019import java.io.IOException;
020
021import javax.xml.namespace.QName;
022
023import org.jivesoftware.smack.packet.ExtensionElement;
024import org.jivesoftware.smack.packet.Message;
025import org.jivesoftware.smack.packet.MessageBuilder;
026import org.jivesoftware.smack.packet.Stanza;
027import org.jivesoftware.smack.packet.XmlEnvironment;
028import org.jivesoftware.smack.provider.ExtensionElementProvider;
029import org.jivesoftware.smack.xml.XmlPullParser;
030import org.jivesoftware.smack.xml.XmlPullParserException;
031
032/**
033 * Represents a <b>message delivery receipt request</b> entry as specified by
034 * <a href="http://xmpp.org/extensions/xep-0184.html">Message Delivery Receipts</a>.
035 *
036 * @author Georg Lukas
037 */
038public class DeliveryReceiptRequest implements ExtensionElement {
039    public static final String ELEMENT = "request";
040    public static final String NAMESPACE = DeliveryReceipt.NAMESPACE;
041    public static final QName QNAME = new QName(NAMESPACE, ELEMENT);
042
043    @Override
044    public String getElementName() {
045        return ELEMENT;
046    }
047
048    @Override
049    public String getNamespace() {
050        return DeliveryReceipt.NAMESPACE;
051    }
052
053    @Override
054    public String toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
055        return "<request xmlns='" + DeliveryReceipt.NAMESPACE + "'/>";
056    }
057
058    /**
059     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
060     *
061     * @param p the packet
062     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
063     * @deprecated use {@link #from(Stanza)} instead
064     */
065    @Deprecated
066    public static DeliveryReceiptRequest getFrom(Stanza p) {
067        return from(p);
068    }
069
070    /**
071     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
072     *
073     * @param packet the packet
074     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
075     */
076    public static DeliveryReceiptRequest from(Stanza packet) {
077        return packet.getExtension(DeliveryReceiptRequest.class);
078    }
079
080    /**
081     * Add a delivery receipt request to an outgoing packet.
082     *
083     * Only message packets may contain receipt requests as of XEP-0184,
084     * therefore only allow Message as the parameter type.
085     *
086     * @param message Message object to add a request to
087     * @return the Message ID which will be used as receipt ID
088     */
089    // TODO: Deprecate in favor of addTo(MessageBuilder) once connection's stanza interceptors use StanzaBuilder.
090    public static String addTo(Message message) {
091        message.throwIfNoStanzaId();
092
093        message.addExtension(new DeliveryReceiptRequest());
094        return message.getStanzaId();
095    }
096
097    /**
098     * Add a delivery receipt request to an outgoing packet.
099     *
100     * Only message packets may contain receipt requests as of XEP-0184,
101     * therefore only allow Message as the parameter type.
102     *
103     * @param messageBuilder Message object to add a request to
104     */
105    public static void addTo(MessageBuilder messageBuilder) {
106        messageBuilder.throwIfNoStanzaId();
107
108        messageBuilder.overrideExtension(new DeliveryReceiptRequest());
109    }
110
111    /**
112     * This Provider parses and returns DeliveryReceiptRequest packets.
113     */
114    public static class Provider extends ExtensionElementProvider<DeliveryReceiptRequest> {
115        @Override
116        public DeliveryReceiptRequest parse(XmlPullParser parser,
117                        int initialDepth, XmlEnvironment xmlEnvironment) throws XmlPullParserException,
118                        IOException {
119            return new DeliveryReceiptRequest();
120        }
121    }
122}