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.Constants;
22 import org.apache.maven.api.annotations.Nonnull;
23
24 /**
25 * Message builder that supports configurable styling.
26 *
27 * @since 4.0.0
28 * @see MessageBuilderFactory
29 */
30 public interface MessageBuilder extends Appendable {
31
32 /**
33 * Append message content in trace style.
34 * By default, bold magenta
35 *
36 * @param message the message to append
37 * @return the current builder
38 */
39 @Nonnull
40 default MessageBuilder trace(Object message) {
41 return style("." + Constants.MAVEN_STYLE_TRACE_NAME + ":-" + Constants.MAVEN_STYLE_TRACE_DEFAULT, message);
42 }
43
44 /**
45 * Append message content in debug style.
46 * By default, bold cyan
47 *
48 * @param message the message to append
49 * @return the current builder
50 */
51 @Nonnull
52 default MessageBuilder debug(Object message) {
53 return style("." + Constants.MAVEN_STYLE_DEBUG_NAME + ":-" + Constants.MAVEN_STYLE_DEBUG_DEFAULT, message);
54 }
55
56 /**
57 * Append message content in info style.
58 * By default, bold blue
59 *
60 * @param message the message to append
61 * @return the current builder
62 */
63 @Nonnull
64 default MessageBuilder info(Object message) {
65 return style("." + Constants.MAVEN_STYLE_INFO_NAME + ":-" + Constants.MAVEN_STYLE_INFO_DEFAULT, message);
66 }
67
68 /**
69 * Append message content in warning style.
70 * By default, bold yellow
71 *
72 * @param message the message to append
73 * @return the current builder
74 */
75 @Nonnull
76 default MessageBuilder warning(Object message) {
77 return style("." + Constants.MAVEN_STYLE_WARNING_NAME + ":-" + Constants.MAVEN_STYLE_WARNING_DEFAULT, message);
78 }
79
80 /**
81 * Append message content in error style.
82 * By default, bold red
83 *
84 * @param message the message to append
85 * @return the current builder
86 */
87 @Nonnull
88 default MessageBuilder error(Object message) {
89 return style("." + Constants.MAVEN_STYLE_ERROR_NAME + ":-" + Constants.MAVEN_STYLE_ERROR_DEFAULT, message);
90 }
91
92 /**
93 * Append message content in success style.
94 * By default, bold green
95 *
96 * @param message the message to append
97 * @return the current builder
98 */
99 @Nonnull
100 default MessageBuilder success(Object message) {
101 return style("." + Constants.MAVEN_STYLE_SUCCESS_NAME + ":-" + Constants.MAVEN_STYLE_SUCCESS_DEFAULT, message);
102 }
103
104 /**
105 * Append message content in failure style.
106 * By default, bold red
107 *
108 * @param message the message to append
109 * @return the current builder
110 */
111 @Nonnull
112 default MessageBuilder failure(Object message) {
113 return style("." + Constants.MAVEN_STYLE_FAILURE_NAME + ":-" + Constants.MAVEN_STYLE_FAILURE_DEFAULT, message);
114 }
115
116 /**
117 * Append message content in strong style.
118 * By default, bold
119 *
120 * @param message the message to append
121 * @return the current builder
122 */
123 @Nonnull
124 default MessageBuilder strong(Object message) {
125 return style("." + Constants.MAVEN_STYLE_STRONG_NAME + ":-" + Constants.MAVEN_STYLE_STRONG_DEFAULT, message);
126 }
127
128 /**
129 * Append message content in mojo style.
130 * By default, green
131 *
132 * @param message the message to append
133 * @return the current builder
134 */
135 @Nonnull
136 default MessageBuilder mojo(Object message) {
137 return style("." + Constants.MAVEN_STYLE_MOJO_NAME + ":-" + Constants.MAVEN_STYLE_MOJO_DEFAULT, message);
138 }
139
140 /**
141 * Append message content in project style.
142 * By default, cyan
143 *
144 * @param message the message to append
145 * @return the current builder
146 */
147 @Nonnull
148 default MessageBuilder project(Object message) {
149 return style("." + Constants.MAVEN_STYLE_PROJECT_NAME + ":-" + Constants.MAVEN_STYLE_PROJECT_DEFAULT, message);
150 }
151
152 @Nonnull
153 default MessageBuilder style(String style, Object message) {
154 return style(style).a(message).resetStyle();
155 }
156
157 MessageBuilder style(String style);
158
159 MessageBuilder resetStyle();
160
161 //
162 // message building methods modelled after Ansi methods
163 //
164
165 @Nonnull
166 @Override
167 MessageBuilder append(CharSequence cs);
168
169 @Nonnull
170 @Override
171 MessageBuilder append(CharSequence cs, int start, int end);
172
173 @Nonnull
174 @Override
175 MessageBuilder append(char c);
176
177 /**
178 * Append content to the message buffer.
179 *
180 * @param value the content to append
181 * @param offset the index of the first {@code char} to append
182 * @param len the number of {@code char}s to append
183 * @return the current builder
184 */
185 @Nonnull
186 default MessageBuilder a(char[] value, int offset, int len) {
187 return append(String.valueOf(value, offset, len));
188 }
189
190 /**
191 * Append content to the message buffer.
192 *
193 * @param value the content to append
194 * @return the current builder
195 */
196 @Nonnull
197 default MessageBuilder a(char[] value) {
198 return append(String.valueOf(value));
199 }
200
201 /**
202 * Append content to the message buffer.
203 *
204 * @param value the content to append
205 * @param start the starting index of the subsequence to be appended
206 * @param end the end index of the subsequence to be appended
207 * @return the current builder
208 */
209 @Nonnull
210 default MessageBuilder a(CharSequence value, int start, int end) {
211 return append(value, start, end);
212 }
213
214 /**
215 * Append content to the message buffer.
216 *
217 * @param value the content to append
218 * @return the current builder
219 */
220 @Nonnull
221 default MessageBuilder a(CharSequence value) {
222 return append(value);
223 }
224
225 /**
226 * Append content to the message buffer.
227 *
228 * @param value the content to append
229 * @return the current builder
230 */
231 @Nonnull
232 default MessageBuilder a(Object value) {
233 return append(String.valueOf(value));
234 }
235
236 /**
237 * Append newline to the message buffer.
238 *
239 * @return the current builder
240 */
241 @Nonnull
242 default MessageBuilder newline() {
243 return append(System.lineSeparator());
244 }
245
246 /**
247 * Append formatted content to the buffer.
248 * @see String#format(String, Object...)
249 *
250 * @param pattern a <a href="../util/Formatter.html#syntax">format string</a>
251 * @param args arguments referenced by the format specifiers in the format string
252 * @return the current builder
253 */
254 @Nonnull
255 default MessageBuilder format(String pattern, Object... args) {
256 return append(String.format(pattern, args));
257 }
258
259 /**
260 * Set the buffer length.
261 *
262 * @param length the new length
263 * @return the current builder
264 */
265 MessageBuilder setLength(int length);
266
267 /**
268 * Return the built message.
269 *
270 * @return the message
271 */
272 @Nonnull
273 String build();
274 }