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.apache.maven.api.services;
20
21 import org.apache.maven.api.annotations.Nullable;
22
23 /**
24 * Represents a hierarchical trace of nested requests within a session, enabling correlation between
25 * session events and their originating operations in the application code. The trace structure
26 * supports the following key features:
27 *
28 * <ul>
29 * <li>Maintains parent-child relationships between requests to track operation nesting</li>
30 * <li>Carries contextual data describing the current request or operation</li>
31 * <li>Supports both internal session operations and client-provided trace information</li>
32 * </ul>
33 *
34 * <p>For internal session operations, the trace typically contains {@code *Request} objects
35 * that represent the current processing state. Client code can also create traces with
36 * application-specific data to provide context when invoking session methods.</p>
37 *
38 * <p>This trace information is particularly useful for:</p>
39 * <ul>
40 * <li>Debugging and troubleshooting request flows</li>
41 * <li>Audit logging of session operations</li>
42 * <li>Performance monitoring of nested operations</li>
43 * </ul>
44 *
45 * @param context The context identifier for this request trace, helping to identify the scope or purpose
46 * of the request. May be null if no specific context is needed.
47 * @param parent The parent request trace that led to this request, establishing the chain of nested
48 * operations. May be null for top-level requests.
49 * @param data Additional data associated with this request trace, typically containing the actual request
50 * object being processed or any application-specific state information. May be null if no
51 * additional data is needed.
52 */
53 public record RequestTrace(@Nullable String context, @Nullable RequestTrace parent, @Nullable Object data) {
54
55 public static final String CONTEXT_PLUGIN = "plugin";
56 public static final String CONTEXT_PROJECT = "project";
57 public static final String CONTEXT_BOOTSTRAP = "bootstrap";
58
59 public RequestTrace(RequestTrace parent, Object data) {
60 this(parent != null ? parent.context() : null, parent, data);
61 }
62 }