001// Copyright 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.alerts;
016
017import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
018
019/**
020 * Manages {@link Alert}s (using the {@link AlertStorage} SSO.  The behavior of the service switches during
021 * an Ajax request to directly add JavaScript to present the alerts.
022 *
023 * @since 5.3
024 */
025public interface AlertManager
026{
027   /**
028     * Adds an {@link Severity#SUCCESS} alert with the default duration, {@link Duration#SINGLE}.
029     *
030     * @param message to present to the user
031     * @since 5.3.6
032     */
033    void success(String message);
034
035    /**
036     * Adds an {@link Severity#INFO} alert with the default duration, {@link Duration#SINGLE}.
037     *
038     * @param message to present to the user
039     */
040    void info(String message);
041
042    /**
043     * Adds an {@link Severity#WARN} alert with the default duration, {@link Duration#SINGLE}.
044     *
045     * @param message to present to the user
046     */
047    void warn(String message);
048
049    /**
050     * Adds an {@link Severity#ERROR} alert with the default duration, {@link Duration#SINGLE}.
051     *
052     * @param message to present to the user
053     */
054    void error(String message);
055
056    /**
057     * Adds an alert with configurable severity and duration. Message isn't treated
058     * as HTML, being HTML-escaped.
059     *
060     * @param duration controls how long the alert is presented to the user
061     * @param severity controls how the alert is presented to the user
062     * @param message  to present to the user
063     */
064    void alert(Duration duration, Severity severity, String message);
065    
066    /**
067     * Adds an alert with configurable severity and duration.
068     *
069     * @param duration controls how long the alert is presented to the user
070     * @param severity controls how the alert is presented to the user
071     * @param message  to present to the user
072     * @param markup   whether to treat the message as raw HTML (true) or escape it (false).
073     */
074    @IncompatibleChange(details = "Added in 5.4 in order to support HTML in alerts", release = "5.4")
075    void alert(Duration duration, Severity severity, String message, boolean markup);
076    
077}