001/**
002 *
003 * Copyright 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.delay.packet;
018
019import java.util.Date;
020
021import javax.xml.namespace.QName;
022
023import org.jivesoftware.smack.packet.ExtensionElement;
024import org.jivesoftware.smack.packet.Stanza;
025import org.jivesoftware.smack.util.XmlStringBuilder;
026
027import org.jxmpp.util.XmppDateTime;
028
029/**
030 * Represents timestamp information about data stored for later delivery. A DelayInformation will
031 * always includes the timestamp when the stanza was originally sent and may include more
032 * information such as the JID of the entity that originally sent the stanza as well as the reason
033 * for the delay.<p>
034 *
035 * For more information see <a href="http://xmpp.org/extensions/xep-0091.html">XEP-0091</a>
036 * and <a href="http://xmpp.org/extensions/xep-0203.html">XEP-0203</a>.
037 *
038 * @author Gaston Dombiak
039 * @author Florian Schmaus
040 */
041public class DelayInformation implements ExtensionElement {
042    public static final String ELEMENT = "delay";
043    public static final String NAMESPACE = "urn:xmpp:delay";
044    public static final QName QNAME = new QName(NAMESPACE, ELEMENT);
045
046    private final Date stamp;
047    private final String from;
048    private final String reason;
049
050    /**
051     * Creates a new instance with the specified timestamp.
052     * @param stamp the timestamp
053     * @param from sender
054     * @param reason reason of delay.
055     */
056    public DelayInformation(Date stamp, String from, String reason) {
057        this.stamp = stamp;
058        this.from = from;
059        this.reason = reason;
060    }
061
062    public DelayInformation(Date stamp) {
063        this(stamp, null, null);
064    }
065
066    /**
067     * Returns the JID of the entity that originally sent the stanza or that delayed the
068     * delivery of the stanza or <code>null</code> if this information is not available.
069     *
070     * @return the JID of the entity that originally sent the stanza or that delayed the
071     *         delivery of the packet.
072     */
073    public String getFrom() {
074        return from;
075    }
076
077    /**
078     * Returns the timestamp when the stanza was originally sent. The returned Date is
079     * be understood as UTC.
080     *
081     * @return the timestamp when the stanza was originally sent.
082     */
083    public Date getStamp() {
084        return stamp;
085    }
086
087    /**
088     * Returns a natural-language description of the reason for the delay or <code>null</code> if
089     * this information is not available.
090     *
091     * @return a natural-language description of the reason for the delay or <code>null</code>.
092     */
093    public String getReason() {
094        return reason;
095    }
096
097    @Override
098    public String getElementName() {
099        return ELEMENT;
100    }
101
102    @Override
103    public String getNamespace() {
104        return NAMESPACE;
105    }
106
107    @Override
108    public XmlStringBuilder toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
109        XmlStringBuilder xml = new XmlStringBuilder(this, enclosingNamespace);
110        xml.attribute("stamp", XmppDateTime.formatXEP0082Date(stamp));
111        xml.optAttribute("from", from);
112        xml.optTextChild(reason, this);
113        return xml;
114    }
115
116    /**
117     * Return delay information from the given stanza.
118     *
119     * @param packet TODO javadoc me please
120     * @return the DelayInformation or null
121     * @deprecated use {@link #from(Stanza)} instead
122     */
123    @Deprecated
124    public static DelayInformation getFrom(Stanza packet) {
125        return from(packet);
126    }
127
128    /**
129     * Return delay information from the given stanza.
130     *
131     * @param packet TODO javadoc me please
132     * @return the DelayInformation or null
133     */
134    public static DelayInformation from(Stanza packet) {
135        return packet.getExtension(DelayInformation.class);
136    }
137}