001/**
002 *
003 * Copyright 2003-2007 Jive Software.
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 */
017
018package org.jivesoftware.smackx.muc;
019
020import java.util.Date;
021
022import org.jivesoftware.smackx.muc.packet.MUCInitialPresence;
023
024/**
025 * The DiscussionHistory class controls the number of characters or messages to receive
026 * when entering a room. The room will decide the amount of history to return if you don't 
027 * specify a DiscussionHistory while joining a room.<p>
028 * 
029 * You can use some or all of these variable to control the amount of history to receive:   
030 * <ul>
031 *  <li>maxchars -> total number of characters to receive in the history.
032 *  <li>maxstanzas -> total number of messages to receive in the history.
033 *  <li>seconds -> only the messages received in the last "X" seconds will be included in the 
034 * history.
035 *  <li>since -> only the messages received since the datetime specified will be included in 
036 * the history.
037 * </ul>
038 * 
039 * Note: Setting maxchars to 0 indicates that the user requests to receive no history.
040 * 
041 * @author Gaston Dombiak
042 */
043public class DiscussionHistory {
044
045    private int maxChars = -1;
046    private int maxStanzas = -1;
047    private int seconds = -1;
048    private Date since;
049
050    /**
051     * Returns the total number of characters to receive in the history.
052     * 
053     * @return total number of characters to receive in the history.
054     */
055    public int getMaxChars() {
056        return maxChars;
057    }
058
059    /**
060     * Returns the total number of messages to receive in the history.
061     * 
062     * @return the total number of messages to receive in the history.
063     */
064    public int getMaxStanzas() {
065        return maxStanzas;
066    }
067
068    /**
069     * Returns the number of seconds to use to filter the messages received during that time. 
070     * In other words, only the messages received in the last "X" seconds will be included in 
071     * the history.
072     * 
073     * @return the number of seconds to use to filter the messages received during that time.
074     */
075    public int getSeconds() {
076        return seconds;
077    }
078
079    /**
080     * Returns the since date to use to filter the messages received during that time. 
081     * In other words, only the messages received since the datetime specified will be 
082     * included in the history.
083     * 
084     * @return the since date to use to filter the messages received during that time.
085     */
086    public Date getSince() {
087        return since;
088    }
089
090    /**
091     * Sets the total number of characters to receive in the history.
092     * 
093     * @param maxChars the total number of characters to receive in the history.
094     */
095    public void setMaxChars(int maxChars) {
096        this.maxChars = maxChars;
097    }
098
099    /**
100     * Sets the total number of messages to receive in the history.
101     * 
102     * @param maxStanzas the total number of messages to receive in the history.
103     */
104    public void setMaxStanzas(int maxStanzas) {
105        this.maxStanzas = maxStanzas;
106    }
107
108    /**
109     * Sets the number of seconds to use to filter the messages received during that time. 
110     * In other words, only the messages received in the last "X" seconds will be included in 
111     * the history.
112     * 
113     * @param seconds the number of seconds to use to filter the messages received during 
114     * that time.
115     */
116    public void setSeconds(int seconds) {
117        this.seconds = seconds;
118    }
119
120    /**
121     * Sets the since date to use to filter the messages received during that time. 
122     * In other words, only the messages received since the datetime specified will be 
123     * included in the history.
124     * 
125     * @param since the since date to use to filter the messages received during that time.
126     */
127    public void setSince(Date since) {
128        this.since = since;
129    }
130
131    /**
132     * Returns true if the history has been configured with some values.
133     * 
134     * @return true if the history has been configured with some values.
135     */
136    private boolean isConfigured() {
137        return maxChars > -1 || maxStanzas > -1 || seconds > -1 || since != null;
138    }
139
140    /**
141     * Returns the History that manages the amount of discussion history provided on entering a 
142     * room.
143     * 
144     * @return the History that manages the amount of discussion history provided on entering a 
145     * room.
146     */
147    MUCInitialPresence.History getMUCHistory() {
148        // Return null if the history was not properly configured  
149        if (!isConfigured()) {
150            return null;
151        }
152        
153        MUCInitialPresence.History mucHistory = new MUCInitialPresence.History();
154        if (maxChars > -1) {
155            mucHistory.setMaxChars(maxChars);
156        }
157        if (maxStanzas > -1) {
158            mucHistory.setMaxStanzas(maxStanzas);
159        }
160        if (seconds > -1) {
161            mucHistory.setSeconds(seconds);
162        }
163        if (since != null) {
164            mucHistory.setSince(since);
165        }
166        return mucHistory;
167    }
168}