/*******************************************************************************
* 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
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.osgi.service.debug;
import java.io.File;
import java.util.Map;
/**
* Used to get debug options settings and creating a new {@link DebugTrace} instance for
* a bundle to use for dynamic tracing.
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 3.1
*/
public interface DebugOptions {
/**
* The service property (named "listener.symbolic.name") which specifies
* the bundle symbolic name of a {@link DebugOptionsListener} service.
*
* @since 3.5
*/
public static String LISTENER_SYMBOLICNAME = "listener.symbolic.name"; //$NON-NLS-1$
/**
* 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.
*
* <p>
* Options are specified in the general form <i><Bundle-SymbolicName>/<option-path></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
* defaultValue if no such option is found.
*/
public abstract boolean getBooleanOption(String option, boolean defaultValue);
/**
* 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><Bundle-SymbolicName>/<option-path></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>
*/
public abstract String getOption(String option);
/**
* Returns the identified option. The specified defaultValue is
* returned if no such option is found or if debug is not enabled.
*
* <p>
* Options are specified
* in the general form <i><Bundle-SymbolicName>/<option-path></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
* defaultValue if no such option is found.
*/
public abstract String getOption(String option, String 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.
*
* <p>
* Options are specified
* in the general form <i><Bundle-SymbolicName>/<option-path></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
* defaultValue if no such option is found.
*/
public abstract int getIntegerOption(String option, int defaultValue);
/**
* Returns a snapshot of the current options. All
* keys and values are of type <code>String</code>. If no
* options are set then an empty map is returned.
* <p>
* If debug is not enabled then the snapshot of the current disabled
* values is returned. See {@link DebugOptions#setDebugEnabled(boolean)}.
* </p>
* @return a snapshot of the current options.
* @since 3.6
*/
public Map<String, String> getOptions();
/**
* 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);
/**
* 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 <code>IllegalArgumentException</code> is thrown if any key or value
* in the specified map is not of type <code>String</code>.
* <p>
* If debug is not enabled then the specified options are saved as
* the disabled values and no notifications will be sent.
* See {@link 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.
* </p>
* @param options the new set of options
* @since 3.6
*/
public abstract void setOptions(Map<String, String> options);
/**
* 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);
/**
* 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 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);
/**
* Sets the current file used to trace messages to.
*
* @param newFile The file to be used for tracing messages.
* @since 3.5
*/
public abstract void setFile(File newFile);
/**
* Returns the trace file if it is set, otherwise <code>null</code> is returned.
*
* @return the trace file if it is set, otherwise <code>null</code> is returned.
* @since 3.5
*/
public abstract File getFile();
/**
* Creates a new <code>DebugTrace</code> instance for the specified bundle symbolic name.
* If a <code>DebugTrace</code> object has already been created for the specified symbolic
* name then the existing <code>DebugTrace</code> object will be returned.
*
* The class name, method name, and line number of any callers to the <code>DebugTrace</code>
* 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.
*
* @param bundleSymbolicName The symbolic name of the bundle that is requesting a
* new instance of a <code>DebugTrace</code>.
* @return A new or existing <code>DebugTrace</code> object for the specified plug-in ID
* @since 3.5
*/
public abstract DebugTrace newDebugTrace(String bundleSymbolicName);
/**
* Create a new <code>DebugTrace</code> instance for the specified bundle symbolic name.
* If a <code>DebugTrace</code> object has already been created for the specified symbolic
* name then the existing <code>DebugTrace</code> object will be returned.
*
* The class name, method name, and line number of any callers to the <code>DebugTrace</code>
* 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.
*
* @param bundleSymbolicName The symbolic name of the bundle that is requesting a
* new instance of a <code>DebugTrace</code>.
* @param traceEntryClass The class that is being used to abstract tracing calls for a bundle.
* @return A new or existing <code>DebugTrace</code> object for the specified plug-in ID
* @since 3.5
*/
public abstract DebugTrace newDebugTrace(String bundleSymbolicName, Class<?> traceEntryClass);
}