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: - *
- * 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() - */ - public static final int OK = 0; - - /** 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 #getSeverity() - * @see #matches(int) - */ - public static final int WARNING = 0x02; - - /** 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 #getSeverity() - * @see #matches(int) - * @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, ornull 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 occurredERROR - 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.
- *
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.
- *
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);
-}
#P org.eclipse.osgi
Index: .classpath
===================================================================
RCS file: /cvsroot/rt/org.eclipse.equinox/framework/bundles/org.eclipse.osgi/.classpath,v
retrieving revision 1.19
diff -u -r1.19 .classpath
--- .classpath 6 Aug 2010 19:51:44 -0000 1.19
+++ .classpath 8 Nov 2010 14:11:37 -0000
@@ -12,5 +12,6 @@
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: + *
+ * 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() + */ + public static final int OK = 0; + + /** 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 #getSeverity() + * @see #matches(int) + */ + public static final int WARNING = 0x02; + + /** 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 #getSeverity() + * @see #matches(int) + * @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, ornull 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 occurredERROR - 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.
+ *
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.
+ *
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);
+}
Index: statushandling/org/eclipse/core/runtime/IStatusHandler.java
===================================================================
RCS file: statushandling/org/eclipse/core/runtime/IStatusHandler.java
diff -N statushandling/org/eclipse/core/runtime/IStatusHandler.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ statushandling/org/eclipse/core/runtime/IStatusHandler.java 1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,34 @@
+package org.eclipse.core.runtime;
+
+import java.util.Map;
+
+/*******************************************************************************
+ * Copyright (c) 2010 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+/**
+ * When a status is passed to the {@link IStatusHandlingService},
+ * it will check which {@link IStatusHandler} can be notified (according to {@link IStatusMatcher})
+ * and then notify them about new {@link IStatus}.
+ * @since 3.7
+ * @noextend This interface is not intended to be extended by clients.
+ */
+public interface IStatusHandler {
+
+ /**
+ * This method is called when new {@link IStatus} is reported
+ * and {@link IStatusMatcher#canAccept(IStatus)} returned true.
+ * @param status
+ * @param attributes - attributes passed together with the status.
+ * @return null if the status should not be processed furthermore, or an
+ * instance of IStatus which will be handled further.
+ */
+ public IStatus statusHandled(IStatus status, @SuppressWarnings("rawtypes") Map attributes);
+}
Index: statushandling/org/eclipse/core/runtime/IStatusHandlingService.java
===================================================================
RCS file: statushandling/org/eclipse/core/runtime/IStatusHandlingService.java
diff -N statushandling/org/eclipse/core/runtime/IStatusHandlingService.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ statushandling/org/eclipse/core/runtime/IStatusHandlingService.java 1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,67 @@
+package org.eclipse.core.runtime;
+
+/*******************************************************************************
+ * Copyright (c) 2010 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+import java.util.Map;
+
+/**
+ * This is an interface defining all functionality that is needed to properly handle
+ * statuses that happen anywhere in the framework.
+ *
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @noextend This interface is not intended to be extended by clients.
+ * @experimental
+ * @since 3.7
+ */
+public interface IStatusHandlingService {
+
+ /**
+ * No style specified.
+ */
+ public static final int NONE = 0;
+ /**
+ * The handler is advised to present the status to the user.
+ */
+ public static final int SHOW = 1;
+ /**
+ * The handler is advised to log the status.
+ */
+ public static final int LOG = 2;
+
+ /**
+ * This method should be called when an issue appeared and it must
+ * be handled in any way.
+ *
+ * @param status - the status that needs to be handled
+ * @param style - a style, in which the status needs to be handled.
+ * @param map - optional attributes, which may contain user defined properties
+ */
+ public void handle(IStatus status, int style, @SuppressWarnings("rawtypes") Map map);
+
+ /**
+ * This method should be used to register customer status handler. The handler
+ * may catch the status and break its processing. This is chain of responsibility pattern.
+ * Each {@link IStatusHandler} may be registered only once at a time.
+ * Please refer to {@link IStatusHandler} javadoc for details.
+ *
+ * @param priority the lower priority the faster the handler will be called
+ * @param handler the handler that should be registered
+ * @param matcher a matcher, which will determine if the handler can accept particular status
+ */
+ public void registerStatusHandler(int priority, IStatusHandler handler, IStatusMatcher matcher);
+
+ /**
+ * Removes the handler. The handler will not receive any statuses to handle anymore.
+ * @param handler
+ */
+ public void removeStatusHandler(IStatusHandler handler);
+}
Index: statushandling/org/eclipse/core/runtime/IStatusMatcher.java
===================================================================
RCS file: statushandling/org/eclipse/core/runtime/IStatusMatcher.java
diff -N statushandling/org/eclipse/core/runtime/IStatusMatcher.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ statushandling/org/eclipse/core/runtime/IStatusMatcher.java 1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,30 @@
+package org.eclipse.core.runtime;
+
+/*******************************************************************************
+ * Copyright (c) 2010 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+/**
+ * This class verifies if particular {@link IStatusHandler}
+ * can process particular {@link IStatus}.
+ *
+ * @since 3.7
+ */
+public interface IStatusMatcher {
+
+ /**
+ * This method verifies if particular {@link IStatusHandler}
+ * can process particular {@link IStatus}.
+ *
+ * @param status A status which is processed
+ * @return true if the status can be processed, false otherwise.
+ */
+ public boolean canAccept(IStatus status);
+}
#P org.eclipse.osgi.tests
Index: src/org/eclipse/osgi/tests/eclipseadaptor/AllTests.java
===================================================================
RCS file: /cvsroot/rt/org.eclipse.equinox/framework/bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/eclipseadaptor/AllTests.java,v
retrieving revision 1.1
diff -u -r1.1 AllTests.java
--- src/org/eclipse/osgi/tests/eclipseadaptor/AllTests.java 3 Jun 2005 19:18:04 -0000 1.1
+++ src/org/eclipse/osgi/tests/eclipseadaptor/AllTests.java 8 Nov 2010 14:11:38 -0000
@@ -18,6 +18,7 @@
TestSuite suite = new TestSuite(AllTests.class.getName());
suite.addTest(EnvironmentInfoTest.suite());
suite.addTest(FilePathTest.suite());
+ suite.addTest(StatusHandlingTest.suite());
return suite;
}
}
Index: src/org/eclipse/osgi/tests/eclipseadaptor/StatusHandlingTest.java
===================================================================
RCS file: src/org/eclipse/osgi/tests/eclipseadaptor/StatusHandlingTest.java
diff -N src/org/eclipse/osgi/tests/eclipseadaptor/StatusHandlingTest.java
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ src/org/eclipse/osgi/tests/eclipseadaptor/StatusHandlingTest.java 1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,146 @@
+package org.eclipse.osgi.tests.eclipseadaptor;
+
+import java.util.Map;
+import junit.framework.Test;
+import junit.framework.TestSuite;
+import org.eclipse.core.internal.runtime.DefaultStatusHandlingService;
+import org.eclipse.core.runtime.*;
+import org.eclipse.osgi.tests.OSGiTest;
+
+public class StatusHandlingTest extends OSGiTest {
+ private final class TestHandler implements IStatusHandler {
+ private final boolean[] called;
+
+ private TestHandler(boolean[] called) {
+ this.called = called;
+ }
+
+ public IStatus statusHandled(IStatus status, Map attributes) {
+ called[0] = true;
+ return null;
+ }
+ }
+
+ public static Test suite() {
+ return new TestSuite(StatusHandlingTest.class);
+ }
+
+ private DefaultStatusHandlingService shService;
+ private IStatusMatcher allMatcher = new IStatusMatcher() {
+
+ public boolean canAccept(IStatus status) {
+ return true;
+ }
+
+ };
+
+ private IStatus testStatus = new IStatus() {
+
+ public IStatus[] getChildren() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ public int getCode() {
+ // TODO Auto-generated method stub
+ return 0;
+ }
+
+ public Throwable getException() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ public String getMessage() {
+ return "testMessage";
+ }
+
+ public String getPlugin() {
+ return "testPlugin";
+ }
+
+ public int getSeverity() {
+ return IStatus.ERROR;
+ }
+
+ public boolean isMultiStatus() {
+ return false;
+ }
+
+ public boolean isOK() {
+ return false;
+ }
+
+ public boolean matches(int severityMask) {
+ // TODO Auto-generated method stub
+ return false;
+ }
+
+ };
+
+ protected void setUp() throws Exception {
+ this.shService = new DefaultStatusHandlingService(getContext());
+ super.setUp();
+ }
+
+ public void testStatusHandlingServiceWithOneHandler() {
+ final boolean[] called = new boolean[] {false};
+ IStatusHandler handler = new IStatusHandler() {
+
+ public IStatus statusHandled(IStatus status, Map attributes) {
+ called[0] = true;
+ return null;
+ }
+ };
+ shService.registerStatusHandler(0, handler, allMatcher);
+ shService.handle(testStatus, 0, null);
+ assertTrue("The status handler should be called", called[0]);
+
+ called[0] = false;
+ shService.removeStatusHandler(handler);
+ shService.handle(testStatus, 0, null);
+ assertFalse("The status handler should not be called", called[0]);
+ }
+
+ public void testStatusHandlingServiceWithTwoHandlers() {
+ final boolean[] called = new boolean[] {false};
+ IStatusHandler handler = new TestHandler(called);
+ shService.registerStatusHandler(10, handler, allMatcher);
+ shService.handle(testStatus, 10, null);
+ assertTrue("The status handler should be called", called[0]);
+
+ final boolean[] called2 = new boolean[] {false};
+ IStatusHandler handler2 = new TestHandler(called2);
+ called[0] = false;
+ shService.registerStatusHandler(0, handler2, allMatcher);
+ shService.handle(testStatus, 0, null);
+
+ assertTrue("The more important status handler should be called", called2[0]);
+ assertFalse("The less important status handler should not be called because there is a more important handler which intercepts the status", called[0]);
+
+ shService.removeStatusHandler(handler2);
+ called[0] = false;
+ called2[0] = false;
+ shService.handle(testStatus, 0, null);
+
+ assertFalse("The more important status handler should not be called, because it is unregistered", called2[0]);
+ assertTrue("The less important status handler should be called", called[0]);
+ }
+
+ public void testFailingHandler() {
+ final boolean[] called = new boolean[] {false};
+ IStatusHandler handler = new TestHandler(called);
+ shService.registerStatusHandler(10, handler, allMatcher);
+
+ shService.registerStatusHandler(0, new IStatusHandler() {
+
+ public IStatus statusHandled(IStatus status, Map attributes) {
+ throw new RuntimeException();
+ }
+ }, allMatcher);
+
+ shService.handle(testStatus, 0, null);
+ assertTrue("Errors during status handling should be handled correctly", called[0]);
+
+ }
+}