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