| /*=============================================================================# |
| # Copyright (c) 2018, 2020 Stephan Wahlbrink and others. |
| # |
| # This program and the accompanying materials are made available under the |
| # terms of the Eclipse Public License 2.0 which is available at |
| # https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 |
| # which is available at https://www.apache.org/licenses/LICENSE-2.0. |
| # |
| # SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 |
| # |
| # Contributors: |
| # Stephan Wahlbrink <sw@wahlbrink.eu> - initial API and implementation |
| #=============================================================================*/ |
| |
| package org.eclipse.statet.jcommons.status; |
| |
| import org.eclipse.statet.jcommons.collections.ImList; |
| import org.eclipse.statet.jcommons.lang.NonNullByDefault; |
| import org.eclipse.statet.jcommons.lang.Nullable; |
| |
| |
| /** |
| * A status object represents the outcome of an operation. |
| * |
| * <p>A status carries the following properties: |
| * <ul> |
| * <li>{@link #getSeverity() severity}</li> |
| * <li>{@link #getBundleId() bundle identifier}</li> |
| * <li>{@link #getCode() status code}</li> |
| * <li>{@link #getMessage() message}</li> |
| * <li>{@link #getException() exception (optional)}</li> |
| * </ul> |
| * A {@link #isMultiStatus() multi-status} can contain other status objects as children.</p> |
| * |
| * @see Statuses |
| * @see OkStatus |
| * @see InfoStatus |
| * @see WarningStatus |
| * @see ErrorStatus |
| * @see CancelStatus |
| * @see MultiStatus |
| * @see StatusException |
| */ |
| @NonNullByDefault |
| public interface Status { |
| |
| |
| /** Status severity indicating the status represents the normal case ("everything is fine"). */ |
| byte OK= 0; |
| |
| /** Status severity indicating the status is informational ("fyi"). */ |
| byte INFO= 1 << 0; |
| |
| /** Status severity indicating the status represents a warning. */ |
| byte WARNING= 1 << 1; |
| |
| /** Status severity indicating the status represents an error. */ |
| byte ERROR= 1 << 2; |
| |
| /** Status severity indicating the status represents a cancelation */ |
| byte CANCEL= 1 << 3; |
| |
| |
| /** |
| * Returns the severity. |
| * |
| * <p>Severity is one value of: |
| * <ul> |
| * <li><code>{@link #OK}</code></li> |
| * <li><code>{@link #INFO}</code></li> |
| * <li><code>{@link #WARNING}</code></li> |
| * <li><code>{@link #ERROR}</code></li> |
| * <li><code>{@link #CANCEL}</code></li> |
| * </ul></p> |
| * <p>The severity of a multi-status is defined to be the maximum severity of any of its |
| * children, or <code>OK</code> if it has no children.</p> |
| * |
| * @return the severity |
| */ |
| byte getSeverity(); |
| |
| |
| /** |
| * Returns the unique identifier of the bundle associated with this status. |
| * |
| * @return the unique identifier of the relevant bundle |
| */ |
| String getBundleId(); |
| |
| /** |
| * Returns the bundle specific status code. |
| * |
| * @return the status code |
| */ |
| int getCode(); |
| |
| |
| /** |
| * Returns the message describing the outcome. |
| * |
| * <p>The message is localized to the current locale.</p> |
| * |
| * @return a localized message |
| */ |
| String getMessage(); |
| |
| /** |
| * Returns the relevant low-level exception. |
| * |
| * @return the relevant exception, or <code>null</code> if none |
| */ |
| @Nullable Throwable getException(); |
| |
| |
| /** |
| * Returns whether this status is a multi-status which can contain other status objects as |
| * children. |
| * |
| * @return <code>true</code> if the status is a multi-status, otherwise <code>false</code> |
| * |
| * @see #getChildren() |
| */ |
| boolean isMultiStatus(); |
| |
| /** |
| * Returns a list of status objects contained in this status. |
| * |
| * @return the children |
| * |
| * @see #isMultiStatus() |
| */ |
| ImList<Status> getChildren(); |
| |
| } |