Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: b67952345b4aa41e49a3ec6ad6348ba485888faa (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
/*******************************************************************************
 * Copyright (c) 2009, 2010 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.osgi.service.debug;

import java.util.EventListener;

/**
 * A debug options listener is notified whenever one of its plug-in option-path entries is 
 * changed.  A listener is registered as an OSGi service using the {@link DebugOptions#LISTENER_SYMBOLICNAME}
 * service property to specify the symbolic name of the debug options listener.
 * <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.  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:
 * <pre>
 * public class Activator implements BundleActivator, DebugOptionsListener {
 * 	public static boolean DEBUG = false;
 * 	public static DebugTrace trace;
 * 	
 * 	public void start(BundleContext context) {
 * 		Hashtable props = new Hashtable(4);
 * 		props.put(DebugOptions.LISTENER_SYMBOLICNAME, "com.mycompany.mybundle");
 * 		context.registerService(DebugOptionsListener.class.getName(), this, props);
 * 	}
 * 
 * 	public void optionsChanged(DebugOptions options) {
 * 		if (trace == null)
 * 			trace = options.newDebugTrace("com.mycompany.mybundle");
 * 		DEBUG = options.getBooleanOption("com.mycompany.mybundle/debug", false);
 * 	}
 * 	
 * 	public void doSomeWork() {
 * 		if (DEBUG)
 * 			trace.trace(null, "Doing some work");
 * 	}
 * 	...
 * } 
 * </pre>
 * @since 3.5
 */
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 without the need to 
	 * acquire the debug options service.
	 * @param options a reference to the DebugOptions
	 */
	public void optionsChanged(DebugOptions options);
}

Back to the top