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 /**
20 * Every monitored step in a service call is represented by a trace step.
21 * <p>
22 *
23 * A trace step at minimum consists of a unique id, that identifies the
24 * monitored step within the trace session and the duration (in ms) of the
25 * executed step. An example for such an id is the fully qualified class name
26 * plus the name of the executed method.
27 * <p>
28 *
29 * Additionally, most trace steps have a parent and one to several children.
30 * <p>
31 *
32 * @author Gunther Popp
33 *
34 */
35 public interface ITraceStep {
36
37 /**
38 * Return the id of the trace step.
39 * <p>
40 *
41 * @return trace step id
42 */
43 ITraceStepId getId();
44
45 /**
46 * Enter the trace step and start time measuring.<p>
47 *
48 * This method should only be called once for a trace step. All subsequent calls
49 * will be ignored.
50 */
51 void enter();
52
53 /**
54 * Leave the trace step and calculate the elapsed time since
55 * <code>enter</code> has been called.
56 *
57 * The elapsed time is returned by <code>getDuration()</code>.
58 * <p>
59 *
60 * Leaving a step implies that all children are left, too.
61 * <p>
62 *
63 * This method should only be called once for a trace step. All subsequent calls
64 * will be ignored.
65 */
66 void leave();
67
68 /**
69 * Checks, if the current trace step is active.
70 * <p>
71 *
72 * A step is active between the calls to <code>enter</code> and
73 * <code>leave</code>.
74 *
75 * @return true: The trace step is active.
76 */
77 boolean isActive();
78
79 /**
80 * Returns the isolated duration of this TraceStep.
81 * <p>
82 *
83 * The duration is the time elapsed between the calls to <code>enter</code>
84 * and <code>leave</code> minus the durations of all children.
85 * <p>
86 *
87 * @return duration of this TraceStep in ms (-1: no valid duration exists for
88 * this trace step)
89 */
90 long getIsolatedDuration();
91
92 /**
93 * Returns the duration of this TraceStep and all children.
94 * <p>
95 *
96 * This value reflects the overall execution time of a trace step between the
97 * calls to <code>enter</code> and <code>leave</code> inclusive the
98 * durations of all children.
99 * <p>
100 *
101 * @return accumulated duration in ms
102 */
103 long getDuration();
104
105 /**
106 * Adds a new child to this trace step.
107 * <p>
108 *
109 * The implementation must make sure that the child receives a references to this
110 * trace step. This reference must be returned by <code>getParent()</code>.<p>
111 *
112 * @param child trace step to add as child
113 */
114 void addChild(ITraceStep child);
115
116 /**
117 * Returns the list of children for this trace steps.
118 *
119 * @return Array containing the children
120 */
121 ITraceStep[] getChildren();
122
123 /**
124 * Returns the parent of a TraceStep, if any exists.
125 * <p>
126 *
127 * @return Parent trace step
128 */
129 ITraceStep getParent();
130
131 /**
132 * Set the parent of a TraceStep.
133 * <p>
134 *
135 * This method is invoked when a new child is added using <code>addChild()</code>. It should
136 * never be called manually.<p>
137 * <p>
138 *
139 * @param parent new parent of the child.
140 */
141 void setParent(ITraceStep parent);
142
143 }