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