Copyright (c) 2000, 2006 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
/*******************************************************************************
* Copyright (c) 2000, 2006 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 CoreException
s 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 Also: - MultiStatus
- Status
/**
* A status object represents the outcome of an operation.
* All <code>CoreException</code>s 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).
* <p>
* A status carries the following information:
* </p>
* <ul>
* <li> plug-in identifier (required)</li>
* <li> severity (required)</li>
* <li> status code (required)</li>
* <li> message (required) - localized to current locale</li>
* <li> exception (optional) - for problems stemming from a failure at
* a lower level</li>
* </ul>
* <p>
* Some status objects, known as multi-statuses, have other status objects
* as children.
* </p>
* <p>
* The class <code>Status</code> is the standard public implementation
* of status objects; the subclass <code>MultiStatus</code> is the
* implements multi-status objects.
* </p><p>
* This interface can be used without OSGi running.
* </p>
* @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 Also: - getSeverity()
- isOK()
- Status.OK_STATUS
/** 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 Also: - getSeverity()
- matches(int)
/** Status type severity (bit mask, value 1) indicating this status is informational only.
* @see #getSeverity()
* @see #matches(int)
*/
public static final int INFO = 0x01;
Status type severity (bit mask, value 2) indicating this status represents a warning.
See Also: - getSeverity()
- matches(int)
/** Status type severity (bit mask, value 2) indicating this status represents a warning.
* @see #getSeverity()
* @see #matches(int)
*/
public static final int WARNING = 0x02;
Status type severity (bit mask, value 4) indicating this status represents an error.
See Also: - getSeverity()
- matches(int)
/** Status type severity (bit mask, value 4) indicating this status represents an error.
* @see #getSeverity()
* @see #matches(int)
*/
public static final int ERROR = 0x04;
Status type severity (bit mask, value 8) indicating this status represents a
cancelation
See Also: - getSeverity()
- matches(int)
- Status.CANCEL_STATUS
Since: 3.0
/** 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.
See Also: Returns: an array of status objects
/**
* 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.
Returns: plug-in-specific status code
/**
* 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.
Returns: the relevant low-level exception, or null
if none
/**
* Returns the relevant low-level exception, or <code>null</code> if none.
* For example, when an operation fails because of a network communications
* failure, this might return the <code>java.io.IOException</code>
* describing the exact nature of that failure.
*
* @return the relevant low-level exception, or <code>null</code> if none
*/
public Throwable getException();
Returns the message describing the outcome.
The message is localized to the current locale.
Returns: a localized message
/**
* 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).
Returns: the unique identifier of the relevant plug-in
/**
* 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.
See Also: Returns: the severity: one of OK
, ERROR
,
INFO
, WARNING
, or CANCEL
/**
* Returns the severity. The severities are as follows (in
* descending order):
* <ul>
* <li><code>CANCEL</code> - cancelation occurred</li>
* <li><code>ERROR</code> - a serious error (most severe)</li>
* <li><code>WARNING</code> - a warning (less severe)</li>
* <li><code>INFO</code> - an informational ("fyi") message (least severe)</li>
* <li><code>OK</code> - everything is just fine</li>
* </ul>
* <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: one of <code>OK</code>, <code>ERROR</code>,
* <code>INFO</code>, <code>WARNING</code>, or <code>CANCEL</code>
* @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.
See Also: Returns: true
for a multi-status,
false
otherwise
/**
* Returns whether this status is a multi-status.
* A multi-status describes the outcome of an operation
* involving multiple operands.
* <p>
* The severity of a multi-status is derived from the severities
* of its children; a multi-status with no children is
* <code>OK</code> 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.
* </p>
*
* @return <code>true</code> for a multi-status,
* <code>false</code> otherwise
* @see #getChildren()
*/
public boolean isMultiStatus();
Returns whether this status indicates everything is okay
(neither info, warning, nor error).
Returns: true
if this status has severity
OK
, and false
otherwise
/**
* Returns whether this status indicates everything is okay
* (neither info, warning, nor error).
*
* @return <code>true</code> if this status has severity
* <code>OK</code>, and <code>false</code> 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
.
Params: - severityMask – a mask formed by bitwise or'ing severity mask
constants (
ERROR
, WARNING
,
INFO
, CANCEL
)
See Also: Returns: true
if there is at least one match,
false
if there are no matches
/**
* Returns whether the severity of this status matches the given
* severity mask. Note that a status with severity <code>OK</code>
* will never match; use <code>isOK</code> instead to detect
* a status with a severity of <code>OK</code>.
*
* @param severityMask a mask formed by bitwise or'ing severity mask
* constants (<code>ERROR</code>, <code>WARNING</code>,
* <code>INFO</code>, <code>CANCEL</code>)
* @return <code>true</code> if there is at least one match,
* <code>false</code> if there are no matches
* @see #getSeverity()
* @see #CANCEL
* @see #ERROR
* @see #WARNING
* @see #INFO
*/
public boolean matches(int severityMask);
}