Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Watson2010-02-02 17:15:13 +0000
committerThomas Watson2010-02-02 17:15:13 +0000
commit320f8431fee2d0843f11764c38d6c7c9acdfa4a2 (patch)
tree40e4d1b157590470adfcd6783956869455846d4e
parent1c68c4f23d4895919878dbef8e660d240a99cf2f (diff)
downloadrt.equinox.framework-320f8431fee2d0843f11764c38d6c7c9acdfa4a2.tar.gz
rt.equinox.framework-320f8431fee2d0843f11764c38d6c7c9acdfa4a2.tar.xz
rt.equinox.framework-320f8431fee2d0843f11764c38d6c7c9acdfa4a2.zip
Bug 300911 - Disabling tracing does not notify listeners
-rw-r--r--bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/debugoptions/DebugOptionsTestCase.java61
-rw-r--r--bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/debug/FrameworkDebugOptions.java259
-rw-r--r--bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptions.java64
-rw-r--r--bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptionsListener.java8
4 files changed, 245 insertions, 147 deletions
diff --git a/bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/debugoptions/DebugOptionsTestCase.java b/bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/debugoptions/DebugOptionsTestCase.java
index 41e99d914..650e246af 100644
--- a/bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/debugoptions/DebugOptionsTestCase.java
+++ b/bundles/org.eclipse.osgi.tests/src/org/eclipse/osgi/tests/debugoptions/DebugOptionsTestCase.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2009 IBM Corporation and others.
+ * Copyright (c) 2009, 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
@@ -123,11 +123,11 @@ public class DebugOptionsTestCase extends CoreTest {
}
public void testDyanmicEnablement01() {
- listener.clear();
if (debugOptions.isDebugEnabled())
return; // cannot test
debugOptions.setDebugEnabled(true);
assertTrue("Debug is not enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ listener.clear();
Map checkValues = new HashMap();
checkValues.put(getName() + "/debug", "true"); //$NON-NLS-1$ //$NON-NLS-2$
listener.setCheckValues(checkValues);
@@ -137,11 +137,11 @@ public class DebugOptionsTestCase extends CoreTest {
}
public void testDyanmicEnablement02() {
- listener.clear();
if (debugOptions.isDebugEnabled())
return; // cannot test
debugOptions.setDebugEnabled(true);
assertTrue("Debug is not enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ listener.clear();
Map checkValues = new HashMap();
checkValues.put(getName() + "/debug", "false"); //$NON-NLS-1$ //$NON-NLS-2$
listener.setCheckValues(checkValues);
@@ -159,11 +159,13 @@ public class DebugOptionsTestCase extends CoreTest {
anotherProps.put(DebugOptions.LISTENER_SYMBOLICNAME, "anotherListener"); //$NON-NLS-1$
ServiceRegistration anotherReg = OSGiTestsActivator.getContext().registerService(DebugOptionsListener.class.getName(), anotherListener, anotherProps);
assertTrue("Not called", anotherListener.gotCalled()); //$NON-NLS-1$
- anotherListener.clear();
debugOptions.setDebugEnabled(true);
assertTrue("Debug is not enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ listener.clear();
+ anotherListener.clear();
+
Map checkValues = new HashMap();
checkValues.put(getName() + "/debug", "true"); //$NON-NLS-1$ //$NON-NLS-2$
listener.setCheckValues(checkValues);
@@ -188,6 +190,55 @@ public class DebugOptionsTestCase extends CoreTest {
anotherReg.unregister();
}
+ public void testDyanmicEnablement04() {
+ if (debugOptions.isDebugEnabled())
+ return; // cannot test
+ debugOptions.setDebugEnabled(true);
+ listener.clear();
+ assertTrue("Debug is not enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ Map checkValues = new HashMap();
+ checkValues.put(getName() + "/debug", "true"); //$NON-NLS-1$ //$NON-NLS-2$
+ listener.setCheckValues(checkValues);
+ debugOptions.setOption(getName() + "/debug", "true"); //$NON-NLS-1$ //$NON-NLS-2$
+ assertTrue("Listener did not get called", listener.gotCalled()); //$NON-NLS-1$
+ assertNull("Found bad value: " + listener.getIncorrectValue(), listener.getIncorrectValue()); //$NON-NLS-1$
+
+ listener.clear();
+ checkValues.put(getName() + "/debug", null); //$NON-NLS-1$
+ listener.setCheckValues(checkValues);
+ debugOptions.setDebugEnabled(false);
+ assertFalse("Debug is enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ assertTrue("Listener did not get called", listener.gotCalled()); //$NON-NLS-1$
+ assertNull("Found bad value: " + listener.getIncorrectValue(), listener.getIncorrectValue()); //$NON-NLS-1$
+
+ listener.clear();
+ checkValues.put(getName() + "/debug", "true"); //$NON-NLS-1$ //$NON-NLS-2$
+ listener.setCheckValues(checkValues);
+ debugOptions.setDebugEnabled(true);
+ assertTrue("Debug is not enabled", debugOptions.isDebugEnabled()); //$NON-NLS-1$
+ assertTrue("Listener did not get called", listener.gotCalled()); //$NON-NLS-1$
+ assertNull("Found bad value: " + listener.getIncorrectValue(), listener.getIncorrectValue()); //$NON-NLS-1$
+
+ }
+
+ public void testBooleanValues() {
+ if (!debugOptions.isDebugEnabled()) {
+ debugOptions.setDebugEnabled(true);
+ }
+ String testKey = getName() + "/debug";
+ boolean testValue = debugOptions.getBooleanOption(testKey, false);
+ assertFalse(testKey + " is true", testValue);
+ debugOptions.setOption(testKey, "false");
+ testValue = debugOptions.getBooleanOption(testKey, true);
+ assertFalse(testKey + " is true", testValue);
+
+ debugOptions.setOption(testKey, "true");
+ testValue = debugOptions.getBooleanOption(testKey, false);
+ assertTrue(testKey + " is false", testValue);
+ testValue = debugOptions.getBooleanOption(testKey, true);
+ assertTrue(testKey + " is false", testValue);
+ }
+
private TestDebugTrace createDebugTrace(final File traceFile) {
TestDebugTrace debugTrace = null;
@@ -853,7 +904,7 @@ public class DebugOptionsTestCase extends CoreTest {
for (Iterator entries = checkValues.entrySet().iterator(); entries.hasNext();) {
Map.Entry entry = (Entry) entries.next();
String debugValue = options.getOption((String) entry.getKey());
- String error = "Value is inccorect for key: " + entry.getKey() + " " + debugValue; //$NON-NLS-1$//$NON-NLS-2$
+ String error = "Value is incorrect for key: " + entry.getKey() + " " + debugValue; //$NON-NLS-1$//$NON-NLS-2$
if (debugValue == null) {
if (entry.getValue() != null) {
incorrectValue = error;
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/debug/FrameworkDebugOptions.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/debug/FrameworkDebugOptions.java
index 698cf84c2..5c0a137e5 100644
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/debug/FrameworkDebugOptions.java
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/debug/FrameworkDebugOptions.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2003, 2009 IBM Corporation and others.
+ * Copyright (c) 2003, 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
@@ -31,8 +31,12 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
private static final String OSGI_DEBUG = "osgi.debug"; //$NON-NLS-1$
public static final String PROP_TRACEFILE = "osgi.tracefile"; //$NON-NLS-1$
- /** A map of all the options specified for the product */
+ /** monitor used to lock the options maps */
+ private final Object lock = new Object();
+ /** A current map of all the options with values set */
private Properties options = null;
+ /** A map of all the disabled options with values set at the time debug was disabled */
+ private Properties disabledOptions = null;
/** The singleton object of this class */
private static FrameworkDebugOptions singleton = null;
/** The default name of the .options file if loading when the -debug command-line argument is used */
@@ -48,8 +52,48 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
* Internal constructor to create a <code>FrameworkDebugOptions</code> singleton object.
*/
private FrameworkDebugOptions() {
- super();
- loadOptions();
+ // if no debug option was specified, don't even bother to try.
+ // Must ensure that the options slot is null as this is the signal to the
+ // platform that debugging is not enabled.
+ String debugOptionsFilename = FrameworkProperties.getProperty(OSGI_DEBUG);
+ if (debugOptionsFilename == null)
+ return;
+ options = new Properties();
+ URL optionsFile;
+ if (debugOptionsFilename.length() == 0) {
+ // default options location is user.dir (install location may be r/o so
+ // is not a good candidate for a trace options that need to be updatable by
+ // by the user)
+ String userDir = FrameworkProperties.getProperty("user.dir").replace(File.separatorChar, '/'); //$NON-NLS-1$
+ if (!userDir.endsWith("/")) //$NON-NLS-1$
+ userDir += "/"; //$NON-NLS-1$
+ debugOptionsFilename = new File(userDir, OPTIONS).toString();
+ }
+ optionsFile = buildURL(debugOptionsFilename, false);
+ if (optionsFile == null) {
+ System.out.println("Unable to construct URL for options file: " + debugOptionsFilename); //$NON-NLS-1$
+ return;
+ }
+ System.out.print("Debug options:\n " + optionsFile.toExternalForm()); //$NON-NLS-1$
+ try {
+ InputStream input = optionsFile.openStream();
+ try {
+ options.load(input);
+ System.out.println(" loaded"); //$NON-NLS-1$
+ } finally {
+ input.close();
+ }
+ } catch (FileNotFoundException e) {
+ System.out.println(" not found"); //$NON-NLS-1$
+ } catch (IOException e) {
+ System.out.println(" did not parse"); //$NON-NLS-1$
+ e.printStackTrace(System.out);
+ }
+ // trim off all the blanks since properties files don't do that.
+ for (Iterator i = options.keySet().iterator(); i.hasNext();) {
+ Object key = i.next();
+ options.put(key, ((String) options.get(key)).trim());
+ }
}
public void start(BundleContext bc) {
@@ -110,47 +154,26 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
*/
public boolean getBooleanOption(String option, boolean defaultValue) {
String optionValue = getOption(option);
- return (optionValue != null && optionValue.equalsIgnoreCase("true")) || defaultValue; //$NON-NLS-1$
- }
-
- public String[] getOptionsForBundle(String bundleName) {
-
- List optionsList = null;
- if (options != null) {
- optionsList = new ArrayList();
- final Iterator entrySetIterator = options.entrySet().iterator();
- int i = 0;
- String key = null;
- while (entrySetIterator.hasNext()) {
- Map.Entry entry = (Map.Entry) entrySetIterator.next();
- key = (String) entry.getKey();
- int firstOptionPathIndex = key.indexOf("/"); //$NON-NLS-1$
- if (key.substring(0, firstOptionPathIndex).equals(bundleName)) {
- optionsList.add(((String) entry.getKey()) + "=" + ((String) entry.getValue())); //$NON-NLS-1$
- i++;
- }
- }
- }
- if (optionsList == null) {
- optionsList = Collections.EMPTY_LIST;
- }
- // convert the list to an array
- final String[] optionsArray = (String[]) optionsList.toArray(new String[optionsList.size()]);
- return optionsArray;
+ return optionValue != null ? optionValue.equalsIgnoreCase("true") : defaultValue; //$NON-NLS-1$
}
/**
* @see DebugOptions#getOption(String)
*/
public String getOption(String option) {
- return options != null ? options.getProperty(option) : null;
+ return getOption(option, null);
}
/**
* @see DebugOptions#getOption(String, String)
*/
public String getOption(String option, String defaultValue) {
- return options != null ? options.getProperty(option, defaultValue) : defaultValue;
+ synchronized (lock) {
+ if (options != null) {
+ return options.getProperty(option, defaultValue);
+ }
+ }
+ return defaultValue;
}
/**
@@ -172,18 +195,20 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
String[] getAllOptions() {
String[] optionsArray = null;
- if (options != null) {
- optionsArray = new String[options.size()];
- final Iterator entrySetIterator = options.entrySet().iterator();
- int i = 0;
- while (entrySetIterator.hasNext()) {
- Map.Entry entry = (Map.Entry) entrySetIterator.next();
- optionsArray[i] = ((String) entry.getKey()) + "=" + ((String) entry.getValue()); //$NON-NLS-1$
- i++;
+ synchronized (lock) {
+ if (options != null) {
+ optionsArray = new String[options.size()];
+ final Iterator entrySetIterator = options.entrySet().iterator();
+ int i = 0;
+ while (entrySetIterator.hasNext()) {
+ Map.Entry entry = (Map.Entry) entrySetIterator.next();
+ optionsArray[i] = ((String) entry.getKey()) + "=" + ((String) entry.getValue()); //$NON-NLS-1$
+ i++;
+ }
}
}
if (optionsArray == null) {
- optionsArray = new String[1];
+ optionsArray = new String[1]; // TODO this is strange; null is the only element so we can print null in writeSession
}
return optionsArray;
}
@@ -193,12 +218,21 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
* @see org.eclipse.osgi.service.debug.DebugOptions#removeOption(java.lang.String)
*/
public void removeOption(String option) {
-
- if (option != null) {
- this.options.remove(option);
- final int firstSlashIndex = option.indexOf("/"); //$NON-NLS-1$
- final String symbolicName = option.substring(0, firstSlashIndex);
- this.optionsChanged(symbolicName);
+ if (option == null)
+ return;
+ boolean fireChangedEvent = false;
+ synchronized (lock) {
+ if (options != null) {
+ fireChangedEvent = options.remove(option) != null;
+ }
+ }
+ // Send the options change event outside the sync block
+ if (fireChangedEvent) {
+ int firstSlashIndex = option.indexOf("/"); //$NON-NLS-1$
+ if (firstSlashIndex > 0) {
+ String symbolicName = option.substring(0, firstSlashIndex);
+ optionsChanged(symbolicName);
+ }
}
}
@@ -207,71 +241,33 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
* @see org.eclipse.osgi.service.debug.DebugOptions#setOption(java.lang.String, java.lang.String)
*/
public void setOption(String option, String value) {
- if (options != null) {
- // get the current value
- String currentValue = options.getProperty(option);
- boolean optionValueHasChanged = false;
- if (currentValue != null) {
- if (!currentValue.equals(value)) {
- optionValueHasChanged = true;
+ boolean fireChangedEvent = false;
+ synchronized (lock) {
+ if (options != null) {
+ // get the current value
+ String currentValue = options.getProperty(option);
+
+ if (currentValue != null) {
+ if (!currentValue.equals(value)) {
+ fireChangedEvent = true;
+ }
+ } else {
+ if (value != null) {
+ fireChangedEvent = true;
+ }
}
- } else {
- if (value != null) {
- optionValueHasChanged = true;
+ if (fireChangedEvent) {
+ options.put(option, value.trim());
}
}
- if (optionValueHasChanged) {
- options.put(option, value.trim());
- final int firstSlashIndex = option.indexOf("/"); //$NON-NLS-1$
- final String symbolicName = option.substring(0, firstSlashIndex);
- this.optionsChanged(symbolicName);
- }
- }
-
- }
-
- private void loadOptions() {
- // if no debug option was specified, don't even bother to try.
- // Must ensure that the options slot is null as this is the signal to the
- // platform that debugging is not enabled.
- String debugOptionsFilename = FrameworkProperties.getProperty(OSGI_DEBUG);
- if (debugOptionsFilename == null)
- return;
- options = new Properties();
- URL optionsFile;
- if (debugOptionsFilename.length() == 0) {
- // default options location is user.dir (install location may be r/o so
- // is not a good candidate for a trace options that need to be updatable by
- // by the user)
- String userDir = FrameworkProperties.getProperty("user.dir").replace(File.separatorChar, '/'); //$NON-NLS-1$
- if (!userDir.endsWith("/")) //$NON-NLS-1$
- userDir += "/"; //$NON-NLS-1$
- debugOptionsFilename = new File(userDir, OPTIONS).toString();
}
- optionsFile = buildURL(debugOptionsFilename, false);
- if (optionsFile == null) {
- System.out.println("Unable to construct URL for options file: " + debugOptionsFilename); //$NON-NLS-1$
- return;
- }
- System.out.print("Debug options:\n " + optionsFile.toExternalForm()); //$NON-NLS-1$
- try {
- InputStream input = optionsFile.openStream();
- try {
- options.load(input);
- System.out.println(" loaded"); //$NON-NLS-1$
- } finally {
- input.close();
+ // Send the options change event outside the sync block
+ if (fireChangedEvent) {
+ int firstSlashIndex = option.indexOf("/"); //$NON-NLS-1$
+ if (firstSlashIndex > 0) {
+ String symbolicName = option.substring(0, firstSlashIndex);
+ optionsChanged(symbolicName);
}
- } catch (FileNotFoundException e) {
- System.out.println(" not found"); //$NON-NLS-1$
- } catch (IOException e) {
- System.out.println(" did not parse"); //$NON-NLS-1$
- e.printStackTrace(System.out);
- }
- // trim off all the blanks since properties files don't do that.
- for (Iterator i = options.keySet().iterator(); i.hasNext();) {
- Object key = i.next();
- options.put(key, ((String) options.get(key)).trim());
}
}
@@ -280,9 +276,9 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
* @see org.eclipse.osgi.service.debug.DebugOptions#isDebugEnabled()
*/
public boolean isDebugEnabled() {
-
- //return options != null;
- return (FrameworkProperties.getProperty(OSGI_DEBUG) != null);
+ synchronized (lock) {
+ return options != null;
+ }
}
/*
@@ -290,18 +286,41 @@ public class FrameworkDebugOptions implements DebugOptions, ServiceTrackerCustom
* @see org.eclipse.osgi.service.debug.DebugOptions#setDebugEnabled()
*/
public void setDebugEnabled(boolean enabled) {
- if (enabled) {
- if (!this.isDebugEnabled()) {
+ boolean fireChangedEvent = false;
+ synchronized (lock) {
+ if (enabled) {
+ if (options != null)
+ return;
// notify the trace that a new session is started
EclipseDebugTrace.newSession = true;
+
+ // enable platform debugging - there is no .options file
+ FrameworkProperties.setProperty(OSGI_DEBUG, ""); //$NON-NLS-1$
+ if (disabledOptions != null) {
+ options = disabledOptions;
+ disabledOptions = null;
+ // fire changed event to indicate some options were re-enabled
+ fireChangedEvent = true;
+ } else {
+ options = new Properties();
+ }
+ } else {
+ if (options == null)
+ return;
+ // disable platform debugging.
+ FrameworkProperties.clearProperty(OSGI_DEBUG);
+ if (options.size() > 0) {
+ // Save the current options off in case debug is re-enabled
+ disabledOptions = options;
+ // fire changed event to indicate some options were disabled
+ fireChangedEvent = true;
+ }
+ options = null;
}
- // enable platform debugging - there is no .options file
- FrameworkProperties.setProperty(OSGI_DEBUG, ""); //$NON-NLS-1$
- if (this.options == null)
- this.options = new Properties();
- } else {
- // disable platform debugging.
- FrameworkProperties.clearProperty(OSGI_DEBUG);
+ }
+ if (fireChangedEvent) {
+ // (Bug 300911) need to fire event to listeners that options have been disabled
+ optionsChanged("*"); //$NON-NLS-1$
}
}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptions.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptions.java
index 11e7af807..8611c310f 100644
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptions.java
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptions.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2003, 2009 IBM Corporation and others.
+ * Copyright (c) 2003, 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
@@ -31,10 +31,13 @@ public interface DebugOptions {
/**
* Returns the identified option as a boolean value. The specified
- * defaultValue is returned if no such option is found. Options are specified
- * in the general form <i>&lt;Bundle-SymbolicName&gt;/&lt;option-path&gt;</i>.
+ * defaultValue is returned if no such option is found or if debug is not enabled.
+ *
+ * <p>
+ * Options are specified in the general form <i>&lt;Bundle-SymbolicName&gt;/&lt;option-path&gt;</i>.
* For example, <code>org.eclipse.core.runtime/debug</code>
- *
+ * </p>
+ *
* @param option the name of the option to lookup
* @param defaultValue the value to return if no such option is found
* @return the value of the requested debug option or the
@@ -43,11 +46,15 @@ public interface DebugOptions {
public abstract boolean getBooleanOption(String option, boolean defaultValue);
/**
- * Returns the identified option. <code>null</code>
- * is returned if no such option is found. Options are specified
+ * Returns the identified option. A <code>null</code> value
+ * is returned if no such option is found or if debug is not enabled.
+ *
+ * <p>
+ * Options are specified
* in the general form <i>&lt;Bundle-SymbolicName&gt;/&lt;option-path&gt;</i>.
* For example, <code>org.eclipse.core.runtime/debug</code>
- *
+ *</p>
+ *
* @param option the name of the option to lookup
* @return the value of the requested debug option or <code>null</code>
*/
@@ -55,11 +62,14 @@ public interface DebugOptions {
/**
* Returns the identified option. The specified defaultValue is
- * returned if no such option is found or if a NumberFormatException is thrown
- * while converting the option value to an integer. Options are specified
+ * returned if no such option is found or if debug is not enabled.
+ *
+ * <p>
+ * Options are specified
* in the general form <i>&lt;Bundle-SymbolicName&gt;/&lt;option-path&gt;</i>.
* For example, <code>org.eclipse.core.runtime/debug</code>
- *
+ * </p>
+ *
* @param option the name of the option to lookup
* @param defaultValue the value to return if no such option is found
* @return the value of the requested debug option or the
@@ -69,10 +79,16 @@ public interface DebugOptions {
/**
* Returns the identified option as an int value. The specified
- * defaultValue is returned if no such option is found. Options are specified
+ * defaultValue is returned if no such option is found or if a
+ * NumberFormatException is thrown while converting the option value
+ * to an integer or if debug is not enabled.
+ *
+ * <p>
+ * Options are specified
* in the general form <i>&lt;Bundle-SymbolicName&gt;/&lt;option-path&gt;</i>.
* For example, <code>org.eclipse.core.runtime/debug</code>
- *
+ * </p>
+ *
* @param option the name of the option to lookup
* @param defaultValue the value to return if no such option is found
* @return the value of the requested debug option or the
@@ -81,30 +97,40 @@ public interface DebugOptions {
public abstract int getIntegerOption(String option, int defaultValue);
/**
- * Sets the identified option to the identified value.
+ * Sets the identified option to the identified value. If debug is
+ * not enabled then the specified option is not changed.
* @param option the name of the option to set
* @param value the value of the option to set
*/
public abstract void setOption(String option, String value);
/**
- * Removes the identified option
+ * Removes the identified option. If debug is not enabled then
+ * the specified option is not removed.
* @param option the name of the option to remove
* @since 3.5
*/
public abstract void removeOption(String option);
/**
- * Accessor to determine if debugging/tracing is enabled for the product.
- * @return true if debugging/tracing is enabled; Otherwise false is returned.
+ * Returns true if debugging/tracing is currently enabled.
+ * @return true if debugging/tracing is currently enabled; Otherwise false is returned.
* @since 3.5
*/
public abstract boolean isDebugEnabled();
/**
- * Enables or disables debug tracing for the entire application.
- * @param value If <code>true</code>, debugging is enabled, otherwise
- * debugging is disabled
+ * Enables or disables debugging/tracing.
+ * <p>
+ * When debug is disabled all debug options are unset.
+ * When disabling debug the current debug option values are
+ * stored in memory as disabled values. If debug is re-enabled the
+ * disabled values will be set back and enabled. The disabled values
+ * are only stored in memory and if the framework is restarted then
+ * the disabled option values will be lost.
+ * </p>
+ * @param value If <code>true</code>, debug is enabled, otherwise
+ * debug is disabled.
* @since 3.5
*/
public abstract void setDebugEnabled(boolean value);
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptionsListener.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptionsListener.java
index 592bc2d7e..ac6ca3ce7 100644
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptionsListener.java
+++ b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/service/debug/DebugOptionsListener.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2009 IBM Corporation and others.
+ * Copyright (c) 2009, 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
@@ -19,7 +19,9 @@ import java.util.EventListener;
* <p>
* The {@link DebugOptionsListener#optionsChanged(DebugOptions)} method will automatically
* be called upon registration of the debug options listener service. This allows the
- * listener to obtain the initial debug options.
+ * listener to obtain the initial debug options. This initial call to the listener
+ * will happen even if debug is not enabled at the time of registration
+ * ({@link DebugOptions#isDebugEnabled()} will return false in this case).
* </p>
* A debug options listener allows a bundle to cache trace option values in boolean fields for performance
* and code cleanliness. For example:
@@ -55,7 +57,7 @@ public interface DebugOptionsListener extends EventListener {
* Notifies this listener that an option-path for its plug-in has changed.
* This method is also called initially by the DebugOptions implementation
* when the listener is registered as a service. This allows the listener
- * to obtain the initial set of debug options with out the need to
+ * to obtain the initial set of debug options without the need to
* acquire the debug options service.
* @param options a reference to the DebugOptions
*/

Back to the top