Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: d5acd11085599c1639f7f4d9f0d7afadd7ad11ec (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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
/*******************************************************************************
 * Copyright (c) 2009, 2014 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;

/**
 * A DebugTrace is used to record debug trace statements, based on the current
 * option settings in a corresponding {@link DebugOptions} class. The trace implementation
 * will automatically insert additional contextual information such as the bundle, class, 
 * and method performing the tracing. 
 * <p>
 * Trace statements may be written to a file, or onto standard output, depending on 
 * how the {@link DebugOptions} is configured (See {@link DebugOptions#setFile(java.io.File)}).
 * </p>
 * <p>
 * All methods on this class have an optional <code>option</code> argument.
 * When specified, this argument will cause the tracing to be conditional on the value
 * of {@link DebugOptions#getBooleanOption(String, boolean)}, where the bundle's
 * symbolic name will automatically be prepended to the provided option string. For example,
 * if your bundle symbolic name is "com.acme.bundle", and you provide an option argument
 * of "/debug/parser", the trace will only be printed if the option "com.acme.bundle/debug/parser"
 * has a value of "true".
 * </p>
 * <p>
 * Note that the pipe character ("&#124;") is reserved for internal use. If this character 
 * happens to occur in any of the thread name, the option, the message or an Exception
 * message, it will be escaped to the corresponding HTML representation ("&amp&#35;124&#59;").   
 * </p>
 *  
 * @since 3.5
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface DebugTrace {

	/**
	 * Traces a message for the specified option.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 * @param message The trace message to display
	 */
	public void trace(final String option, final String message);

	/**
	 * Traces a message and exception for the specified option.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 * @param message The trace message to display
	 * @param error The exception to trace
	 */
	public void trace(final String option, final String message, final Throwable error);

	/**
	 * Adds a trace message showing a thread stack dump for the current class and 
	 * method being executed for the specified option.
	 *
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 */
	public void traceDumpStack(final String option);

	/**
	 * Add a trace message level stating that a method is being executed for the specified option.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 */
	public void traceEntry(final String option);

	/**
	 * Add a trace message level stating that a method with the specified argument 
	 * values is being executed for the specified option. The result of {@link String#valueOf(Object)} 
	 * on the methodArgument will be written to the trace file.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 * @param methodArgument
	 *            The single argument for the method being executed
	 */
	public void traceEntry(final String option, final Object methodArgument);

	/**
	 * Add a trace message level stating that a method with the specified arguments 
	 * values is being executed for the specified option. The result of {@link String#valueOf(Object)} 
	 * on each argument will be written to the trace file.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 * @param methodArguments
	 *            A list of object arguments for the method being executed
	 */
	public void traceEntry(final String option, final Object[] methodArguments);

	/**
	 * Add a trace message level stating that a method has completed execution for the specified option.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 */
	public void traceExit(final String option);

	/**
	 * Add a trace message level stating that a method with the specified result value 
	 * has completed execution for the specified option. The result of {@link String#valueOf(Object)} 
	 * on the result object will be written to the trace file.
	 * 
	 * @param option The name of the boolean option that will control whether the
	 * trace statement is printed (e.g., "/debug/myComponent"), or <code>null</code>
	 * @param result The result being returned from the method that was executed
	 */
	public void traceExit(final String option, final Object result);
}

Back to the top