1 /*******************************************************************************
2 * Copyright (c) 2010, 2011 Sonatype, Inc.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Sonatype, Inc. - initial API and implementation
10 *******************************************************************************/
11 package org.eclipse.aether;
12
13 /**
14 * A trace of nested requests that are performed by the repository system. This trace information can be used to
15 * correlate repository events with higher level operations in the application code that eventually caused the events. A
16 * single trace can carry an arbitrary object as data which is meant to describe a request/operation that is currently
17 * executed. For call hierarchies within the repository system itself, this data will usually be the {@code *Request}
18 * object that is currently processed. When invoking methods on the repository system, client code may provide a request
19 * trace that has been prepopulated with whatever data is useful for the application to indicate its state for later
20 * evaluation when processing the repository events.
21 *
22 * @see RepositoryEvent#getTrace()
23 */
24 public class RequestTrace
25 {
26
27 private final RequestTrace parent;
28
29 private final Object data;
30
31 /**
32 * Creates a child of the specified request trace. This method is basically a convenience that will invoke
33 * {@link RequestTrace#newChild(Object) parent.newChild()} when the specified parent trace is not {@code null} or
34 * otherwise instantiante a new root trace.
35 *
36 * @param parent The parent request trace, may be {@code null}.
37 * @param data The data to associate with the child trace, may be {@code null}.
38 * @return The child trace, never {@code null}.
39 */
40 public static RequestTrace newChild( RequestTrace parent, Object data )
41 {
42 if ( parent == null )
43 {
44 return new RequestTrace( data );
45 }
46 return parent.newChild( data );
47 }
48
49 /**
50 * Creates a new root trace with the specified data.
51 *
52 * @param data The data to associate with the trace, may be {@code null}.
53 */
54 public RequestTrace( Object data )
55 {
56 this( null, data );
57 }
58
59 /**
60 * Creates a new trace with the specified data and parent
61 *
62 * @param parent The parent trace, may be {@code null} for a root trace.
63 * @param data The data to associate with the trace, may be {@code null}.
64 */
65 protected RequestTrace( RequestTrace parent, Object data )
66 {
67 this.parent = parent;
68 this.data = data;
69 }
70
71 /**
72 * Gets the data associated with this trace.
73 *
74 * @return The data associated with this trace or {@code null} if none.
75 */
76 public final Object getData()
77 {
78 return data;
79 }
80
81 /**
82 * Gets the parent of this trace.
83 *
84 * @return The parent of this trace or {@code null} if this is the root of the trace stack.
85 */
86 public final RequestTrace getParent()
87 {
88 return parent;
89 }
90
91 /**
92 * Creates a new child of this trace.
93 *
94 * @param data The data to associate with the child, may be {@code null}.
95 * @return The child trace, never {@code null}.
96 */
97 public RequestTrace newChild( Object data )
98 {
99 return new RequestTrace( this, data );
100 }
101
102 @Override
103 public String toString()
104 {
105 return String.valueOf( getData() );
106 }
107
108 }