1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. 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,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.eclipse.aether;
20
21 /**
22 * A trace of nested requests that are performed by the repository system. This trace information can be used to
23 * correlate repository events with higher level operations in the application code that eventually caused the events. A
24 * single trace can carry an arbitrary object as data which is meant to describe a request/operation that is currently
25 * executed. For call hierarchies within the repository system itself, this data will usually be the {@code *Request}
26 * object that is currently processed. When invoking methods on the repository system, client code may provide a request
27 * trace that has been prepopulated with whatever data is useful for the application to indicate its state for later
28 * evaluation when processing the repository events.
29 *
30 * @see RepositoryEvent#getTrace()
31 */
32 public class RequestTrace {
33
34 private final RequestTrace parent;
35
36 private final Object data;
37
38 /**
39 * Creates a child of the specified request trace. This method is basically a convenience that will invoke
40 * {@link RequestTrace#newChild(Object) parent.newChild()} when the specified parent trace is not {@code null} or
41 * otherwise instantiante a new root trace.
42 *
43 * @param parent The parent request trace, may be {@code null}.
44 * @param data The data to associate with the child trace, may be {@code null}.
45 * @return The child trace, never {@code null}.
46 */
47 public static RequestTrace newChild(RequestTrace parent, Object data) {
48 if (parent == null) {
49 return new RequestTrace(data);
50 }
51 return parent.newChild(data);
52 }
53
54 /**
55 * Creates a new root trace with the specified data.
56 *
57 * @param data The data to associate with the trace, may be {@code null}.
58 */
59 public RequestTrace(Object data) {
60 this(null, data);
61 }
62
63 /**
64 * Creates a new trace with the specified data and parent
65 *
66 * @param parent The parent trace, may be {@code null} for a root trace.
67 * @param data The data to associate with the trace, may be {@code null}.
68 */
69 protected RequestTrace(RequestTrace parent, Object data) {
70 this.parent = parent;
71 this.data = data;
72 }
73
74 /**
75 * Gets the data associated with this trace.
76 *
77 * @return The data associated with this trace or {@code null} if none.
78 */
79 public final Object getData() {
80 return data;
81 }
82
83 /**
84 * Gets the parent of this trace.
85 *
86 * @return The parent of this trace or {@code null} if this is the root of the trace stack.
87 */
88 public final RequestTrace getParent() {
89 return parent;
90 }
91
92 /**
93 * Creates a new child of this trace.
94 *
95 * @param data The data to associate with the child, may be {@code null}.
96 * @return The child trace, never {@code null}.
97 */
98 public RequestTrace newChild(Object data) {
99 return new RequestTrace(this, data);
100 }
101
102 @Override
103 public String toString() {
104 return String.valueOf(getData());
105 }
106 }