| /******************************************************************************* |
| * Copyright (c) 2009, 2010 IBM Corporation and others. |
| * |
| * This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| ******************************************************************************/ |
| package org.eclipse.e4.core.services.statusreporter; |
| |
| import org.eclipse.core.runtime.IStatus; |
| import org.eclipse.e4.core.services.log.Logger; |
| |
| /** |
| * Handling warnings or errors, with the intent of making the end user aware of these. Strings are |
| * expected to be translated. |
| * |
| * @see Logger |
| */ |
| public abstract class StatusReporter { |
| |
| /** |
| * severity OK |
| */ |
| public static final int OK = IStatus.OK; |
| |
| /** |
| * severity INFO |
| */ |
| public static final int INFO = IStatus.INFO; |
| |
| /** |
| * severity WARNING |
| */ |
| public static final int WARNING = IStatus.WARNING; |
| |
| /** |
| * severity ERROR |
| */ |
| public static final int ERROR = IStatus.ERROR; |
| |
| /** |
| * Style constant indicating that the status should not be acted on. This is used by objects |
| * such as log listeners that do not want to report a status twice. This constant is treated as |
| * a HINT. |
| */ |
| public static final int IGNORE = 0x10; |
| |
| /** |
| * Style constant indicating that the status should be logged only. |
| */ |
| public static final int LOG = 0x20; |
| |
| /** |
| * Style constant indicating that handlers should show a problem to an user without blocking the |
| * calling method while awaiting user response. This is generally done using a non modal Dialog. |
| * This constant is treated as a HINT. |
| */ |
| public static final int SHOW = 0x40; |
| |
| /** |
| * Style constant indicating that the handling should block the calling thread until the status |
| * has been handled. This constant is treated as a HINT, and the caller cannot rely on the fact |
| * that the call will be blocking. However, the caller needs to be prepared for the case where |
| * the call blocks, and potentially runs the event loop (which may change UI state). |
| * <p> |
| * A typical usage of this would be to give the user an opportunity to deal with the status in |
| * some manner. It is therefore likely but not required that a modal dialog is going to be used. |
| * </p> |
| * <p> |
| * The use of <code>BLOCK</code> is not recommended because of its potential to block the |
| * current thread, and the corresponding risk of causing deadlocks. |
| * </p> |
| */ |
| public static final int BLOCK = 0x80; |
| |
| /** |
| * Report the given status, using the given style as a hint. |
| * |
| * @param status |
| * a status object describing an exceptional situation that should be brought to the |
| * attention of the user. |
| * @param style |
| * one of the handling styles (IGNORE, LOG, SHOW, BLOCK). |
| * @param information |
| * any number of additional objects to pass along with the status in order to help |
| * with diagnosing the problem. One possible use of these objects would be to call |
| * their toString() methods. |
| * |
| */ |
| public abstract void report(IStatus status, int style, Object... information); |
| |
| /** |
| * Return a status object with the given severity, message, and optional exception. |
| * |
| * @param severity |
| * one of the severity constants (OK, INFO, WARNING, ERROR). |
| * @param message |
| * a non-null, non-empty localized message describing the unforeseen condition, in as |
| * high-level a way as possible such that an end user can understand the situation |
| * and act upon it. In the case of IGNORE or LOG, the message may be untranslated if |
| * there is reason to believe that the message will primarily be seen by technical |
| * support. |
| * @param exception |
| * an optional exception, or <code>null</code>. |
| */ |
| public abstract IStatus newStatus(int severity, String message, Throwable exception); |
| |
| /** |
| * Convenience method, equivalent to calling |
| * <code>report(newStatus(severity, message, exception), SHOW, information).</code> |
| * |
| * @param severity |
| * one of the severity constants (OK, INFO, WARNING, ERROR). |
| * @param message |
| * a non-null, non-empty localized message describing the unforeseen condition, in as |
| * high-level a way as possible such that an end user can understand the situation |
| * and act upon it. In the case of IGNORE or LOG, the message may be untranslated if |
| * there is reason to believe that the message will primarily be seen by technical |
| * support. |
| * @param exception |
| * an optional exception, or <code>null</code>. |
| * @param information |
| * any number of additional objects to pass along in order to help with diagnosing |
| * the problem. One possible use of these objects may be that their toString() |
| * methods will be called. |
| * |
| */ |
| final public void show(int severity, String message, Throwable exception, Object... information) { |
| report(newStatus(severity, message, exception), SHOW, information); |
| } |
| |
| } |