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.cli;
20
21 import java.util.List;
22
23 import org.apache.maven.api.annotations.Experimental;
24 import org.apache.maven.api.annotations.Nonnull;
25 import org.apache.maven.api.annotations.Nullable;
26
27 /**
28 * Defines a simple logging interface for Maven CLI operations. These operations happen "early", when there may
29 * be no logging set up even. Implementations may be "accumulating", in which case {@link #drain()} method should
30 * be used.
31 * <p>
32 * This interface provides methods for logging messages at different severity levels
33 * and supports logging with or without associated exceptions.
34 *
35 * @since 4.0.0
36 */
37 @Experimental
38 public interface Logger {
39
40 /**
41 * Represents the severity levels for log messages.
42 */
43 enum Level {
44 DEBUG,
45 INFO,
46 WARN,
47 ERROR
48 }
49
50 /**
51 * Logs a message at the specified level without an associated exception.
52 *
53 * @param level the severity level of the message
54 * @param message the message to be logged
55 */
56 default void log(@Nonnull Level level, @Nonnull String message) {
57 log(level, message, null);
58 }
59
60 /**
61 * Logs a message at the specified level with an associated exception.
62 *
63 * @param level the severity level of the message
64 * @param message the message to be logged
65 * @param error the associated exception, or null if not applicable
66 */
67 void log(@Nonnull Level level, @Nonnull String message, @Nullable Throwable error);
68
69 /**
70 * Logs a debug message without an associated exception.
71 *
72 * @param message the debug message to be logged
73 */
74 default void debug(String message) {
75 log(Level.DEBUG, message);
76 }
77
78 /**
79 * Logs a debug message with an associated exception.
80 *
81 * @param message the debug message to be logged
82 * @param error the associated exception
83 */
84 default void debug(@Nonnull String message, @Nullable Throwable error) {
85 log(Level.DEBUG, message, error);
86 }
87
88 /**
89 * Logs an info message without an associated exception.
90 *
91 * @param message the info message to be logged
92 */
93 default void info(@Nonnull String message) {
94 log(Level.INFO, message);
95 }
96
97 /**
98 * Logs an info message with an associated exception.
99 *
100 * @param message the info message to be logged
101 * @param error the associated exception
102 */
103 default void info(@Nonnull String message, @Nullable Throwable error) {
104 log(Level.INFO, message, error);
105 }
106
107 /**
108 * Logs a warning message without an associated exception.
109 *
110 * @param message the warning message to be logged
111 */
112 default void warn(@Nonnull String message) {
113 log(Level.WARN, message);
114 }
115
116 /**
117 * Logs a warning message with an associated exception.
118 *
119 * @param message the warning message to be logged
120 * @param error the associated exception
121 */
122 default void warn(@Nonnull String message, @Nullable Throwable error) {
123 log(Level.WARN, message, error);
124 }
125
126 /**
127 * Logs an error message without an associated exception.
128 *
129 * @param message the error message to be logged
130 */
131 default void error(@Nonnull String message) {
132 log(Level.ERROR, message);
133 }
134
135 /**
136 * Logs an error message with an associated exception.
137 *
138 * @param message the error message to be logged
139 * @param error the associated exception
140 */
141 default void error(@Nonnull String message, @Nullable Throwable error) {
142 log(Level.ERROR, message, error);
143 }
144
145 /**
146 * Logger entries returned by {@link #drain()} method.
147 * @param level The logging level, never {@code null}.
148 * @param message The logging message, never {@code null}.
149 * @param error The error, if applicable.
150 */
151 record Entry(@Nonnull Level level, @Nonnull String message, @Nullable Throwable error) {}
152
153 /**
154 * If this is an accumulating log, it will "drain" this instance. It returns the accumulated log entries, and
155 * also "resets" this instance to empty (initial) state.
156 */
157 @Nonnull
158 default List<Entry> drain() {
159 return List.of();
160 }
161 }