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