KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > IStatus


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.core.runtime;
12
13 /**
14  * A status object represents the outcome of an operation.
15  * All <code>CoreException</code>s carry a status object to indicate
16  * what went wrong. Status objects are also returned by methods needing
17  * to provide details of failures (e.g., validation methods).
18  * <p>
19  * A status carries the following information:
20  * <ul>
21  * <li> plug-in identifier (required)</li>
22  * <li> severity (required)</li>
23  * <li> status code (required)</li>
24  * <li> message (required) - localized to current locale</li>
25  * <li> exception (optional) - for problems stemming from a failure at
26  * a lower level</li>
27  * </ul>
28  * Some status objects, known as multi-statuses, have other status objects
29  * as children.
30  * </p>
31  * <p>
32  * The class <code>Status</code> is the standard public implementation
33  * of status objects; the subclass <code>MultiStatus</code> is the
34  * implements multi-status objects.
35  * </p><p>
36  * This interface can be used without OSGi running.
37  * </p>
38  * @see MultiStatus
39  * @see Status
40  */

41 public interface IStatus {
42
43     /** Status severity constant (value 0) indicating this status represents the nominal case.
44      * This constant is also used as the status code representing the nominal case.
45      * @see #getSeverity()
46      * @see #isOK()
47      */

48     public static final int OK = 0;
49
50     /** Status type severity (bit mask, value 1) indicating this status is informational only.
51      * @see #getSeverity()
52      * @see #matches(int)
53      */

54     public static final int INFO = 0x01;
55
56     /** Status type severity (bit mask, value 2) indicating this status represents a warning.
57      * @see #getSeverity()
58      * @see #matches(int)
59      */

60     public static final int WARNING = 0x02;
61
62     /** Status type severity (bit mask, value 4) indicating this status represents an error.
63      * @see #getSeverity()
64      * @see #matches(int)
65      */

66     public static final int ERROR = 0x04;
67
68     /** Status type severity (bit mask, value 8) indicating this status represents a
69      * cancelation
70      * @see #getSeverity()
71      * @see #matches(int)
72      * @since 3.0
73      */

74     public static final int CANCEL = 0x08;
75
76     /**
77      * Returns a list of status object immediately contained in this
78      * multi-status, or an empty list if this is not a multi-status.
79      *
80      * @return an array of status objects
81      * @see #isMultiStatus()
82      */

83     public IStatus[] getChildren();
84
85     /**
86      * Returns the plug-in-specific status code describing the outcome.
87      *
88      * @return plug-in-specific status code
89      */

90     public int getCode();
91
92     /**
93      * Returns the relevant low-level exception, or <code>null</code> if none.
94      * For example, when an operation fails because of a network communications
95      * failure, this might return the <code>java.io.IOException</code>
96      * describing the exact nature of that failure.
97      *
98      * @return the relevant low-level exception, or <code>null</code> if none
99      */

100     public Throwable JavaDoc getException();
101
102     /**
103      * Returns the message describing the outcome.
104      * The message is localized to the current locale.
105      *
106      * @return a localized message
107      */

108     public String JavaDoc getMessage();
109
110     /**
111      * Returns the unique identifier of the plug-in associated with this status
112      * (this is the plug-in that defines the meaning of the status code).
113      *
114      * @return the unique identifier of the relevant plug-in
115      */

116     public String JavaDoc getPlugin();
117
118     /**
119      * Returns the severity. The severities are as follows (in
120      * descending order):
121      * <ul>
122      * <li><code>CANCEL</code> - cancelation occurred</li>
123      * <li><code>ERROR</code> - a serious error (most severe)</li>
124      * <li><code>WARNING</code> - a warning (less severe)</li>
125      * <li><code>INFO</code> - an informational ("fyi") message (least severe)</li>
126      * <li><code>OK</code> - everything is just fine</li>
127      * </ul>
128      * <p>
129      * The severity of a multi-status is defined to be the maximum
130      * severity of any of its children, or <code>OK</code> if it has
131      * no children.
132      * </p>
133      *
134      * @return the severity: one of <code>OK</code>, <code>ERROR</code>,
135      * <code>INFO</code>, <code>WARNING</code>, or <code>CANCEL</code>
136      * @see #matches(int)
137      */

138     public int getSeverity();
139
140     /**
141      * Returns whether this status is a multi-status.
142      * A multi-status describes the outcome of an operation
143      * involving multiple operands.
144      * <p>
145      * The severity of a multi-status is derived from the severities
146      * of its children; a multi-status with no children is
147      * <code>OK</code> by definition.
148      * A multi-status carries a plug-in identifier, a status code,
149      * a message, and an optional exception. Clients may treat
150      * multi-status objects in a multi-status unaware way.
151      * </p>
152      *
153      * @return <code>true</code> for a multi-status,
154      * <code>false</code> otherwise
155      * @see #getChildren()
156      */

157     public boolean isMultiStatus();
158
159     /**
160      * Returns whether this status indicates everything is okay
161      * (neither info, warning, nor error).
162      *
163      * @return <code>true</code> if this status has severity
164      * <code>OK</code>, and <code>false</code> otherwise
165      */

166     public boolean isOK();
167
168     /**
169      * Returns whether the severity of this status matches the given
170      * severity mask. Note that a status with severity <code>OK</code>
171      * will never match; use <code>isOK</code> instead to detect
172      * a status with a severity of <code>OK</code>.
173      *
174      * @param severityMask a mask formed by bitwise or'ing severity mask
175      * constants (<code>ERROR</code>, <code>WARNING</code>,
176      * <code>INFO</code>, <code>CANCEL</code>)
177      * @return <code>true</code> if there is at least one match,
178      * <code>false</code> if there are no matches
179      * @see #getSeverity()
180      * @see #CANCEL
181      * @see #ERROR
182      * @see #WARNING
183      * @see #INFO
184      */

185     public boolean matches(int severityMask);
186 }
187
Popular Tags