1 package org.e2etrace.trace;
2
3 /*
4 * Copyright 2006 Gunther Popp
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 import org.e2etrace.config.ITraceConfig;
20
21 /**
22 * A trace session manages all trace steps for a single service call.
23 * <p>
24 *
25 * The id of a trace session is the id of the root step (see
26 * <code>getRootStep</code>). This id can be used to deactivate tracing on a
27 * per-session basis (see {@link ITraceConfig}).
28 * <p>
29 *
30 * @author Gunther Popp
31 *
32 */
33 public interface ITraceSession {
34
35 /**
36 * Enters a new trace step with the supplied id.
37 * <p>
38 *
39 * In reality, a trace step covers for example the execution of a single
40 * method. In this case, <code>enterStep</code> must be called when the
41 * method starts and <code>leaveStep</code> when the method ends.
42 * <p>
43 *
44 * To get exact results, each call of <code>enterStep</code> should be
45 * matched by a corresponding call of <code>leaveStep</code>. A trace
46 * session can handle missing <code>leaveStep</code> calls. In this case,
47 * <code>leaveStep</code> will be automatically invoked when the parent step
48 * ends (if any). If no parent exists, no duration will be calculated.
49 * <p>
50 *
51 * @param id ID of the trace step
52 */
53 void enterStep(ITraceStepId id);
54
55 /**
56 * Leaves the trace step with the given id.
57 * <p>
58 *
59 * @param id ID of the trace step
60 */
61 void leaveStep(ITraceStepId id);
62
63 /**
64 * Wrapper for {@link ITraceSession#enterStep(ITraceStepId)} using a
65 * {@link MethodTraceStepId} as TraceStep-IDs.
66 * <p>
67 *
68 * @param clazz Class instance to which the method belongs
69 * @param method Name of the executed method
70 */
71 void enterStep(Class clazz, String method);
72
73 /**
74 * Wrapper for {@link ITraceSession#leaveStep(ITraceStepId)} using a
75 * {@link MethodTraceStepId} as TraceStep-IDs.
76 * <p>
77 *
78 * @param clazz Class instance to which the method belongs
79 * @param method Name of the executed method
80 */
81 void leaveStep(Class clazz, String method);
82
83 /**
84 * Wrapper for {@link ITraceSession#enterStep(ITraceStepId)} using a String as
85 * TraceStep-IDs.
86 * <p>
87 *
88 * @param id String used as id
89 */
90 void enterStep(String id);
91
92 /**
93 * Wrapper for {@link ITraceSession#leaveStep(ITraceStepId)} using a String as
94 * TraceStep-IDs.
95 * <p>
96 *
97 * @param id String used as id
98 */
99 void leaveStep(String id);
100
101 /**
102 * Returns the the root step.
103 * <p>
104 *
105 * The root step is the step that covers the complete service call (i.e. that
106 * has no parent step). The id of the root step is used as id for the complete
107 * trace session.
108 * <p>
109 *
110 * @return root step (null: no trace data has been collected for this session)
111 */
112 ITraceStep getRootStep();
113
114 /**
115 * Returns the active trace step.
116 * <p>
117 *
118 * The active trace step is determined by the last call to
119 * <code>enterStep</code>. If <code>enterStep</code> has not been called
120 * yet, the method returns the root step of the trace session (see
121 * <code>getRootStep</code>).
122 * <p>
123 *
124 * @return active trace step (null: no trace data is collected for this
125 * session)
126 */
127 ITraceStep getCurrentStep();
128
129 /**
130 * Returns the execution time of the complete trace session.
131 * <p>
132 *
133 * Normally for each service call a separate trace session exist. So the
134 * returned duration is the overall execution time of the service call.
135 * <p>
136 *
137 * @return execution time of the trace session
138 */
139 long getDuration();
140
141 /**
142 * Assigns a new trace configuratio to the trace session.
143 * <p>
144 *
145 * @param tc trace configuration
146 */
147 void setConfig(ITraceConfig tc);
148
149 /**
150 * Returns the trace configuration of the session.
151 * <p>
152 *
153 * @return trace configuration
154 */
155 ITraceConfig getConfig();
156
157 }