Eclipse Platform Release 3.7

## org.eclipse.osgi.service.debug
Interface DebugOptions

    public interface DebugOptions

Used to get debug options settings and creating a new `DebugTrace` instance for a bundle to use for dynamic tracing.

Since:
  3.1
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

Field Summary
`static String` `LISTENER_SYMBOLICNAME` The service property (named "listener.symbolic.name") which specifies the bundle symbolic name of a `DebugOptionsListener` service.

Method Summary
`boolean` `getBooleanOption(String option, boolean defaultValue)` Returns the identified option as a boolean value.
`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.
`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` `removeOption(String option)` Removes the identified option.
`void` `setDebugEnabled(boolean value)` Enables or disables debugging/tracing.
`void` `setFile(File newFile)` 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> options)` Sets the current option key/value pairs to the specified options.

Field Detail

### LISTENER_SYMBOLICNAME

    static final String LISTENER_SYMBOLICNAME

  The service property (named "listener.symbolic.name") which specifies the bundle symbolic name of a `DebugOptionsListener` service.

  Since:
    3.5
  See Also:
    Constant Field Values

Method Detail

### getBooleanOption

    boolean getBooleanOption(String option,
                             boolean defaultValue)

  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`

  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.

### getOption

    String getOption(String option)

  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`

  Parameters:
    `option` - the name of the option to lookup
  Returns:
    the value of the requested debug option or `null`

### getOption

    String getOption(String option,
                     String defaultValue)

  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`

  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.

### getIntegerOption

    int getIntegerOption(String option,
                         int defaultValue)

  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`

  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.

### getOptions

    Map<String,String> getOptions()

  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 `setDebugEnabled(boolean)`.

  Returns:
    a snapshot of the current options.
  Since:
    3.6

### setOption

    void setOption(String option,
                   String value)

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

  Parameters:
    `option` - the name of the option to set
    `value` - the value of the option to set

### setOptions

    void setOptions(Map<String,String> options)

  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 `setDebugEnabled(boolean)`. If debug is enabled then notifications will be sent to the listeners which have options that have been changed, added or removed.

  Parameters:
    `options` - the new set of options
  Since:
    3.6

### removeOption

    void removeOption(String option)

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

  Parameters:
    `option` - the name of the option to remove
  Since:
    3.5

### isDebugEnabled

    boolean isDebugEnabled()

  Returns true if debugging/tracing is currently enabled.

  Returns:
    true if debugging/tracing is currently enabled; Otherwise false is returned.
  Since:
    3.5

### setDebugEnabled

    void setDebugEnabled(boolean value)

  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.

  Parameters:
    `value` - If `true`, debug is enabled, otherwise debug is disabled.
  Since:
    3.5

### setFile

    void setFile(File newFile)

  Sets the current file used to trace messages to.

  Parameters:
    `newFile` - The file to be used for tracing messages.
  Since:
    3.5

### getFile

    File getFile()

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

  Returns:
    the trace file if it is set, otherwise `null` is returned.
  Since:
    3.5

### newDebugTrace

    DebugTrace newDebugTrace(String bundleSymbolicName)

  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.

  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
  Since:
    3.5

### newDebugTrace

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

  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.

  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
  Since:
    3.5

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.