org.eclipse.osgi.framework.debug

Class FrameworkDebugOptions

java.lang.Object

org.eclipse.osgi.framework.debug.FrameworkDebugOptions

All Implemented Interfaces:

DebugOptions, ServiceTrackerCustomizer<DebugOptionsListener,DebugOptionsListener>

public class FrameworkDebugOptions
extends Object
implements DebugOptions, ServiceTrackerCustomizer<DebugOptionsListener,DebugOptionsListener>

The DebugOptions implementation class that allows accessing the list of debug options specified for the application as well as creating DebugTrace objects for the purpose of having dynamic enablement of debug tracing.

Since:

3.1

Field Summary

Fields

Modifier and Type	Field and Description
protected static Map<String,DebugTrace>	debugTraceCache A cache of all of the bundles DebugTrace in the format -->
protected File	outFile The File object to store messages.
static String	PROP_TRACEFILE
protected boolean	verboseDebug Is verbose debugging enabled? Changing this value causes a new tracing session to start.

Fields inherited from interface org.eclipse.osgi.service.debug.DebugOptions

LISTENER_SYMBOLICNAME

Method Summary

Methods

Modifier and Type	Method and Description
DebugOptionsListener	addingService(ServiceReference<DebugOptionsListener> reference) A service is being added to the ServiceTracker.
boolean	getBooleanOption(String option, boolean defaultValue) Returns the identified option as a boolean value.
static FrameworkDebugOptions	getDefault() Returns the singleton instance of FrameworkDebugOptions.
File	getFile() Returns the trace file if it is set, otherwise null is returned.
int	getIntegerOption(String option, int defaultValue) Returns the identified option as an int value.
String	getOption(String option) Returns the identified option.
String	getOption(String option, String defaultValue) Returns the identified option.
Map<String,String>	getOptions() Returns a snapshot of the current options.
boolean	isDebugEnabled() Returns true if debugging/tracing is currently enabled.
void	modifiedService(ServiceReference<DebugOptionsListener> reference, DebugOptionsListener service) A service tracked by the ServiceTracker has been modified.
DebugTrace	newDebugTrace(String bundleSymbolicName) Creates a new DebugTrace instance for the specified bundle symbolic name.
DebugTrace	newDebugTrace(String bundleSymbolicName, Class<?> traceEntryClass) Create a new DebugTrace instance for the specified bundle symbolic name.
void	removedService(ServiceReference<DebugOptionsListener> reference, DebugOptionsListener service) A service tracked by the ServiceTracker has been removed.
void	removeOption(String option) Removes the identified option.
void	setDebugEnabled(boolean enabled) Enables or disables debugging/tracing.
void	setFile(File traceFile) Sets the current file used to trace messages to.
void	setOption(String option, String value) Sets the identified option to the identified value.
void	setOptions(Map<String,String> ops) Sets the current option key/value pairs to the specified options.
void	setVerbose(boolean verbose)
void	start(BundleContext bc)
void	stop(BundleContext bc)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_TRACEFILE

public static final String PROP_TRACEFILE

See Also:

Constant Field Values

debugTraceCache

protected static final Map<String,DebugTrace> debugTraceCache

A cache of all of the bundles DebugTrace in the format -->

outFile

protected File outFile

The File object to store messages. This value may be null.

verboseDebug

protected boolean verboseDebug

Is verbose debugging enabled? Changing this value causes a new tracing session to start.

Method Detail

start

public void start(BundleContext bc)

stop

public void stop(BundleContext bc)

getDefault

public static FrameworkDebugOptions getDefault()

Returns the singleton instance of FrameworkDebugOptions.

Returns:

the instance of FrameworkDebugOptions

getBooleanOption

public boolean getBooleanOption(String option,
                       boolean defaultValue)

Description copied from interface: DebugOptions

Returns the identified option as a boolean value. The specified defaultValue is returned if no such option is found or if debug is not enabled.

Options are specified in the general form <Bundle-SymbolicName>/<option-path>. For example, org.eclipse.core.runtime/debug

Specified by:

getBooleanOption in interface DebugOptions

Parameters:

option - the name of the option to lookup

defaultValue - the value to return if no such option is found

Returns:

the value of the requested debug option or the defaultValue if no such option is found.

See Also:

DebugOptions.getBooleanOption(String, boolean)

getOption

public String getOption(String option)

Description copied from interface: DebugOptions

Returns the identified option. A null value is returned if no such option is found or if debug is not enabled.

Options are specified in the general form <Bundle-SymbolicName>/<option-path>. For example, org.eclipse.core.runtime/debug

Specified by:

getOption in interface DebugOptions

Parameters:

option - the name of the option to lookup

Returns:

the value of the requested debug option or null

See Also:

DebugOptions.getOption(String)

getOption

public String getOption(String option,
               String defaultValue)

Description copied from interface: DebugOptions

Returns the identified option. The specified defaultValue is returned if no such option is found or if debug is not enabled.

Options are specified in the general form <Bundle-SymbolicName>/<option-path>. For example, org.eclipse.core.runtime/debug

Specified by:

getOption in interface DebugOptions

Parameters:

option - the name of the option to lookup

defaultValue - the value to return if no such option is found

Returns:

the value of the requested debug option or the defaultValue if no such option is found.

See Also:

DebugOptions.getOption(String, String)

getIntegerOption

public int getIntegerOption(String option,
                   int defaultValue)

Description copied from interface: DebugOptions

Returns the identified option as an int value. 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 or if debug is not enabled.

Options are specified in the general form <Bundle-SymbolicName>/<option-path>. For example, org.eclipse.core.runtime/debug

Specified by:

getIntegerOption in interface DebugOptions

Parameters:

option - the name of the option to lookup

defaultValue - the value to return if no such option is found

Returns:

the value of the requested debug option or the defaultValue if no such option is found.

See Also:

DebugOptions.getIntegerOption(String, int)

getOptions

public Map<String,String> getOptions()

Description copied from interface: DebugOptions

Returns a snapshot of the current options. All keys and values are of type String. If no options are set then an empty map is returned.

If debug is not enabled then the snapshot of the current disabled values is returned. See DebugOptions.setDebugEnabled(boolean).

Specified by:

getOptions in interface DebugOptions

Returns:

a snapshot of the current options.

removeOption

public void removeOption(String option)

Description copied from interface: DebugOptions

Removes the identified option. If debug is not enabled then the specified option is not removed.

Specified by:

removeOption in interface DebugOptions

Parameters:

option - the name of the option to remove

setOption

public void setOption(String option,
             String value)

Description copied from interface: DebugOptions

Sets the identified option to the identified value. If debug is not enabled then the specified option is not changed.

Specified by:

setOption in interface DebugOptions

Parameters:

option - the name of the option to set

value - the value of the option to set

setOptions

public void setOptions(Map<String,String> ops)

Description copied from interface: DebugOptions

Sets the current option key/value pairs to the specified options. The specified map replaces all keys and values of the current debug options. An IllegalArgumentException is thrown if any key or value in the specified map is not of type String.

If debug is not enabled then the specified options are saved as the disabled values and no notifications will be sent. See DebugOptions.setDebugEnabled(boolean). If debug is enabled then notifications will be sent to the listeners which have options that have been changed, added or removed.

Specified by:

setOptions in interface DebugOptions

Parameters:

ops - the new set of options

isDebugEnabled

public boolean isDebugEnabled()

Description copied from interface: DebugOptions

Returns true if debugging/tracing is currently enabled.

Specified by:

isDebugEnabled in interface DebugOptions

Returns:

true if debugging/tracing is currently enabled; Otherwise false is returned.

setDebugEnabled

public void setDebugEnabled(boolean enabled)

Description copied from interface: DebugOptions

Enables or disables debugging/tracing.

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.

Specified by:

setDebugEnabled in interface DebugOptions

Parameters:

enabled - If true, debug is enabled, otherwise debug is disabled.

newDebugTrace

public final DebugTrace newDebugTrace(String bundleSymbolicName)

Description copied from interface: DebugOptions

Creates a new DebugTrace instance for the specified bundle symbolic name. If a DebugTrace object has already been created for the specified symbolic name then the existing DebugTrace object will be returned. The class name, method name, and line number of any callers to the DebugTrace API will automatically be determined by parsing the stack trace of the executing thread. These attributes will be set based on the first caller of this API.

Specified by:

newDebugTrace in interface DebugOptions

Parameters:

bundleSymbolicName - The symbolic name of the bundle that is requesting a new instance of a DebugTrace.

Returns:

A new or existing DebugTrace object for the specified plug-in ID

newDebugTrace

public final DebugTrace newDebugTrace(String bundleSymbolicName,
                       Class<?> traceEntryClass)

Description copied from interface: DebugOptions

Create a new DebugTrace instance for the specified bundle symbolic name. If a DebugTrace object has already been created for the specified symbolic name then the existing DebugTrace object will be returned. The class name, method name, and line number of any callers to the DebugTrace API will automatically be determined by parsing the stack trace of the executing thread. The values of these attributes will be based on the last invocation to the specified traceEntryClass found in the parsed stack trace.

Specified by:

newDebugTrace in interface DebugOptions

Parameters:

bundleSymbolicName - The symbolic name of the bundle that is requesting a new instance of a DebugTrace.

traceEntryClass - The class that is being used to abstract tracing calls for a bundle.

Returns:

A new or existing DebugTrace object for the specified plug-in ID

getFile

public final File getFile()

Description copied from interface: DebugOptions

Returns the trace file if it is set, otherwise null is returned.

Specified by:

getFile in interface DebugOptions

Returns:

the trace file if it is set, otherwise null is returned.

setFile

public void setFile(File traceFile)

Description copied from interface: DebugOptions

Sets the current file used to trace messages to.

Specified by:

setFile in interface DebugOptions

Parameters:

traceFile - The file to be used for tracing messages.

setVerbose

public void setVerbose(boolean verbose)

addingService

public DebugOptionsListener addingService(ServiceReference<DebugOptionsListener> reference)

Description copied from interface: ServiceTrackerCustomizer

A service is being added to the ServiceTracker.

This method is called before a service which matched the search parameters of the ServiceTracker is added to the ServiceTracker. This method should return the service object to be tracked for the specified ServiceReference. The returned service object is stored in the ServiceTracker and is available from the getService and getServices methods.

Specified by:

addingService in interface ServiceTrackerCustomizer<DebugOptionsListener,DebugOptionsListener>

Parameters:

reference - The reference to the service being added to the ServiceTracker.

Returns:

The service object to be tracked for the specified referenced service or null if the specified referenced service should not be tracked.

modifiedService

public void modifiedService(ServiceReference<DebugOptionsListener> reference,
                   DebugOptionsListener service)

Description copied from interface: ServiceTrackerCustomizer

A service tracked by the ServiceTracker has been modified.

This method is called when a service being tracked by the ServiceTracker has had it properties modified.

Specified by:

modifiedService in interface ServiceTrackerCustomizer<DebugOptionsListener,DebugOptionsListener>

Parameters:

reference - The reference to the service that has been modified.

service - The service object for the specified referenced service.

removedService

public void removedService(ServiceReference<DebugOptionsListener> reference,
                  DebugOptionsListener service)

Description copied from interface: ServiceTrackerCustomizer

A service tracked by the ServiceTracker has been removed.

This method is called after a service is no longer being tracked by the ServiceTracker.

Specified by:

removedService in interface ServiceTrackerCustomizer<DebugOptionsListener,DebugOptionsListener>

Parameters:

reference - The reference to the service that has been removed.

service - The service object for the specified referenced service.