org.eclipse.core.runtime.IStatus Maven / Gradle / Ivy

/*******************************************************************************
 * Copyright (c) 2000, 2021 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.core.runtime;

/**
 * A status object represents the outcome of an operation.
 * All CoreExceptions carry a status object to indicate 
 * what went wrong. Status objects are also returned by methods needing 
 * to provide details of failures (e.g., validation methods).
 * 
 * A status carries the following information:
 * 
 * 
 *  plug-in identifier (required)
 *  severity (required)
 *  status code (required)
 *  message (required) - localized to current locale
 *  exception (optional) - for problems stemming from a failure at
 *    a lower level
 * 
 * 
 * Some status objects, known as multi-statuses, have other status objects 
 * as children.
 * 
 * 
 * The class Status is the standard public implementation
 * of status objects; the subclass MultiStatus is the
 * implements multi-status objects.
 * 

 * This interface can be used without OSGi running.
 * 
 * @see MultiStatus
 * @see Status
 */
public interface IStatus {

	/** Status severity constant (value 0) indicating this status represents the nominal case.
	 * This constant is also used as the status code representing the nominal case.
	 * @see #getSeverity()
	 * @see #isOK()
	 * @see Status#OK_STATUS
	 */
	public static final int OK = 0;

	/** Status type severity (bit mask, value 1) indicating this status is informational only.
	 * @see #getSeverity()
	 * @see #matches(int)
	 * @see Status#info(String)
	 */
	public static final int INFO = 0x01;

	/** Status type severity (bit mask, value 2) indicating this status represents a warning.
	 * @see #getSeverity()
	 * @see #matches(int)
	 * @see Status#warning(String)
	 * @see Status#warning(String, Throwable)
	 */
	public static final int WARNING = 0x02;

	/** Status type severity (bit mask, value 4) indicating this status represents an error.
	 * @see #getSeverity()
	 * @see #matches(int)
	 * @see Status#error(String)
	 * @see Status#error(String, Throwable)
	 */
	public static final int ERROR = 0x04;

	/** Status type severity (bit mask, value 8) indicating this status represents a
	 * cancelation
	 * @see #getSeverity()
	 * @see #matches(int)
	 * @see Status#CANCEL_STATUS
	 * @since 3.0
	 */
	public static final int CANCEL = 0x08;

	/**
	 * Returns a list of status object immediately contained in this
	 * multi-status, or an empty list if this is not a multi-status.
	 *
	 * @return an array of status objects
	 * @see #isMultiStatus()
	 */
	public IStatus[] getChildren();

	/**
	 * Returns the plug-in-specific status code describing the outcome.
	 *
	 * @return plug-in-specific status code
	 */
	public int getCode();

	/**
	 * Returns the relevant low-level exception, or null if none. 
	 * For example, when an operation fails because of a network communications
	 * failure, this might return the java.io.IOException
	 * describing the exact nature of that failure.
	 *
	 * @return the relevant low-level exception, or null if none
	 */
	public Throwable getException();

	/**
	 * Returns the message describing the outcome.
	 * The message is localized to the current locale.
	 *
	 * @return a localized message
	 */
	public String getMessage();

	/**
	 * Returns the unique identifier of the plug-in associated with this status
	 * (this is the plug-in that defines the meaning of the status code).
	 *
	 * @return the unique identifier of the relevant plug-in
	 */
	public String getPlugin();

	/**
	 * Returns the severity. The severities are as follows (in
	 * descending order):
	 * 
	 * CANCEL - cancelation occurred
	 * ERROR - a serious error (most severe)
	 * WARNING - a warning (less severe)
	 * INFO - an informational ("fyi") message (least severe)
	 * OK - everything is just fine
	 * 
	 * 
	 * The severity of a multi-status is defined to be the maximum
	 * severity of any of its children, or OK if it has
	 * no children.
	 * 
	 *
	 * @return the severity: one of OK, ERROR, 
	 * INFO, WARNING,  or CANCEL
	 * @see #matches(int)
	 */
	public int getSeverity();

	/**
	 * Returns whether this status is a multi-status.
	 * A multi-status describes the outcome of an operation
	 * involving multiple operands.
	 * 
	 * The severity of a multi-status is derived from the severities
	 * of its children; a multi-status with no children is
	 * OK by definition.
	 * A multi-status carries a plug-in identifier, a status code,
	 * a message, and an optional exception. Clients may treat
	 * multi-status objects in a multi-status unaware way.
	 * 
	 *
	 * @return true for a multi-status, 
	 *    false otherwise
	 * @see #getChildren()
	 */
	public boolean isMultiStatus();

	/**
	 * Returns whether this status indicates everything is okay
	 * (neither info, warning, nor error).
	 *
	 * @return true if this status has severity
	 *    OK, and false otherwise
	 */
	public boolean isOK();

	/**
	 * Returns whether the severity of this status matches the given
	 * severity mask. Note that a status with severity OK
	 * will never match; use isOK instead to detect
	 * a status with a severity of OK.
	 *
	 * @param severityMask a mask formed by bitwise or'ing severity mask
	 *    constants (ERROR, WARNING,
	 *    INFO, CANCEL)
	 * @return true if there is at least one match, 
	 *    false if there are no matches
	 * @see #getSeverity()
	 * @see #CANCEL
	 * @see #ERROR
	 * @see #WARNING
	 * @see #INFO
	 */
	public boolean matches(int severityMask);
}