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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags