001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.main;
029
030import org.opencms.file.CmsUser;
031import org.opencms.i18n.CmsEncoder;
032import org.opencms.ui.components.CmsRichTextArea;
033
034/**
035 * A single broadcast message, send from one OpenCms user to another.<p>
036 *
037 * To addess a broadcast to another user, it must be placed in the
038 * broadcast queue of that user using for example
039 * {@link org.opencms.main.CmsSessionManager#sendBroadcast(CmsUser, String, CmsUser)}.<p>
040 *
041 * @since 6.0.0
042 */
043public class CmsBroadcast implements Cloneable {
044
045    /** The content mode describes how the text used for a broadcast message should be interpreted. */
046    public enum ContentMode {
047        /** Broadcast message is plaintext and needs to be converted to HTML. */
048        plain,
049        /** Broadcast message is already HTML, but may need to be cleaned up. */
050        html;
051    }
052
053    /** Time interval between displays of repeated messages. */
054    public static long DISPLAY_AGAIN_TIME = 60 * 1000;
055
056    /** The broadcast content. */
057    private String m_message;
058
059    /** The sender of the broadcast. */
060    private CmsUser m_sender;
061
062    /** Time the broadcast was send. */
063    private long m_sendTime;
064
065    /** The content mode. */
066    private ContentMode m_contentMode;
067
068    /**The last display time. */
069    private long m_lastDisplay;
070
071    /** True if message should be repeated. */
072    private boolean m_repeat;
073
074    /**
075     * Creates a new broadcast, with the current system time set as send time.<p>
076     *
077     *
078     *
079     * @param sender the sender of the broadcast
080     * @param message the message to send
081     * @deprecated use the constructors with the content mode instead
082     */
083    @Deprecated
084    public CmsBroadcast(CmsUser sender, String message) {
085
086        this(sender, message, System.currentTimeMillis(), 0L, false);
087    }
088
089    /**
090     * Creates a new broadcast, with the current system time set as send time.<p>
091     *
092     * @param sender the sender of the broadcast
093     * @param message the message to send
094     * @param repeat true if message shoul be repeated
095     * @deprecated use the constructors with the content mode instead
096     */
097    @Deprecated
098    public CmsBroadcast(CmsUser sender, String message, boolean repeat) {
099
100        this(sender, message, System.currentTimeMillis(), 0L, repeat);
101    }
102
103    /**
104     * Creates a new broadcast, with the current system time set as send time.<p>
105     *
106     * @param sender the sender of the broadcast
107     * @param message the message to send
108     * @param repeat true if message should be repeated
109     * @param mode the content mode
110     */
111    public CmsBroadcast(CmsUser sender, String message, boolean repeat, ContentMode mode) {
112
113        this(sender, message, System.currentTimeMillis(), 0L, repeat, mode);
114    }
115
116    /**
117     * Creates a new broadcast, with the current system time set as send time.<p>
118     *
119     * @param sender the sender of the broadcast
120     * @param message the message to send
121     * @param mode the content mode
122     */
123    public CmsBroadcast(CmsUser sender, String message, ContentMode mode) {
124
125        this(sender, message, System.currentTimeMillis(), 0L, false, mode);
126    }
127
128    /**
129     * Creates a new broadcast, with the current system time set as send time.<p>
130     *
131     * @param sender the sender of the broadcast
132     * @param message the message to send
133     * @param sendTime time when broadcast initaly was send
134     * @param lastDisplay  last display time
135     * @param repeat true if message should be repeated
136     *
137     * @deprecated use the constructors with the content mode instead
138     */
139    @Deprecated
140    public CmsBroadcast(CmsUser sender, String message, long sendTime, long lastDisplay, boolean repeat) {
141
142        this(sender, message, sendTime, lastDisplay, repeat, ContentMode.plain);
143
144    }
145
146    /**
147     * Creates a new broadcast, with the current system time set as send time.<p>
148     *
149     * @param sender the sender of the broadcast
150     * @param message the message to send
151     * @param sendTime time when broadcast initaly was send
152     * @param lastDisplay  last display time
153     * @param repeat true if the message should be repeated
154     * @param mode the content mode
155     */
156    @Deprecated
157    public CmsBroadcast(
158        CmsUser sender,
159        String message,
160        long sendTime,
161        long lastDisplay,
162        boolean repeat,
163        ContentMode mode) {
164
165        m_sender = sender;
166        m_message = message;
167        m_sendTime = sendTime;
168        m_lastDisplay = lastDisplay;
169        m_repeat = repeat;
170        m_contentMode = mode;
171    }
172
173    /**
174     * Gets the content mode.
175     *
176     * @return the content mode
177     */
178    public ContentMode getContentMode() {
179
180        return m_contentMode;
181    }
182
183    /**
184     * Gets the last display time.
185     *
186     * @return the last display time
187     */
188    public long getLastDisplay() {
189
190        return m_lastDisplay;
191    }
192
193    /**
194     * Returns the processed broadcast message content as HTML.
195     *
196     * @return the broadcast message content HTML
197     */
198    public String getMessage() {
199
200        String result;
201        switch (m_contentMode) {
202            case html:
203                result = m_message;
204                break;
205            case plain:
206            default:
207                result = htmlForPlain(m_message);
208        }
209        result = CmsRichTextArea.cleanHtml(result, true);
210        return result;
211    }
212
213    /**
214     * Returns the original message text passed in the constructor.
215     *
216     * @return the original message text
217     */
218    public String getRawMessage() {
219
220        return m_message;
221    }
222
223    /**
224     * Returns the time this broadcast was send.<p>
225     *
226     * @return the time this broadcast was send
227     */
228    public long getSendTime() {
229
230        return m_sendTime;
231    }
232
233    /**
234     * Returns the user that was the sender of this broadcast.<p>
235     *
236     * It could be <code>null</code> to signalize a system message.<p>
237     *
238     * @return the user that was the sender of this broadcast
239     */
240    public CmsUser getUser() {
241
242        return m_sender;
243    }
244
245    /**
246     * Returns true if this is a repeating message.
247     *
248     * @return true if this is a repeating message
249     */
250    public boolean isRepeat() {
251
252        return m_repeat;
253    }
254
255    /**
256     * Produces a copy of this object, but with a changed lastDisplay attribute.
257     *
258     * @param lastDisplay the new value for the lastDisplay attribute
259     * @return the copy with the modified time
260     */
261    public CmsBroadcast withLastDisplay(long lastDisplay) {
262
263        CmsBroadcast result;
264        try {
265            result = (CmsBroadcast)(this.clone());
266            result.m_lastDisplay = lastDisplay;
267            return result;
268        } catch (CloneNotSupportedException e) {
269            return null;
270        }
271
272    }
273
274    /**
275     * Escapes special HTML characters and converts newlines to br tags.
276     *
277     * @param message the message to convert
278     * @return the HTML for the message
279     */
280    private String htmlForPlain(String message) {
281
282        String result = CmsEncoder.escapeXml(message);
283        result = result.replace("\n", "<br>");
284        return result;
285
286    }
287}