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.rat;
20
21 import java.lang.annotation.ElementType;
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 import java.lang.annotation.Target;
25 import java.util.function.Consumer;
26
27 import org.apache.commons.cli.Option;
28 import org.apache.rat.utils.DefaultLog;
29
30 import static java.lang.String.format;
31
32 /**
33 * Reporting methods for deprecated objects.
34 */
35 public final class DeprecationReporter {
36
37 /**
38 * Deprecated Command line option consumer.
39 */
40 private DeprecationReporter() {
41 // DO NOT INSTANTIATE
42 }
43
44 /**
45 * The per-thread consumer that is used for deprecation reporting.
46 * <p>
47 * Stored in a {@link ThreadLocal} so that each thread (e.g. parallel Maven
48 * reactor threads) gets its own reporter and does not interfere with
49 * reporters set by other threads.
50 * </p>
51 */
52 private static final ThreadLocal<Consumer<Option>> CONSUMER = ThreadLocal.withInitial(DeprecationReporter::getDefault); // NOSONAR
53
54 /**
55 * Get the default reporter.
56 * @return The default reporter.
57 */
58 public static Consumer<Option> getDefault() {
59 return o -> {
60 StringBuilder buff = new StringBuilder();
61 if (o.getOpt() != null) {
62 buff.append("-").append(o.getOpt());
63 if (o.getLongOpt() != null) {
64 buff.append(", --").append(o.getLongOpt());
65 }
66 } else {
67 buff.append("--").append(o.getLongOpt());
68 }
69 DefaultLog.getInstance().warn(format("Option [%s] used. %s", buff, o.getDeprecated().toString()));
70 };
71 }
72
73 /**
74 * Creates the consumer that will log usage of deprecated operations to the default log.
75 * @return The consumer that will log usage of deprecated operations to the default log.
76 */
77 public static Consumer<Option> getLogReporter() {
78 return CONSUMER.get();
79 }
80
81 /**
82 * Sets the consumer that will do the reporting.
83 * @param consumer The consumer that will do the reporting.
84 */
85 public static void setLogReporter(final Consumer<Option> consumer) {
86 CONSUMER.set(consumer);
87 }
88
89 /**
90 * Resets the consumer to the default consumer.
91 */
92 public static void resetLogReporter() {
93 CONSUMER.set(getDefault());
94 }
95
96 /**
97 * Log Deprecated class use.
98 * @param clazz the Deprecated class to log
99 */
100 public static void logDeprecated(final Class<?> clazz) {
101 if (clazz.getAnnotation(Deprecated.class) != null) {
102 String name = format("class used: %s ", clazz);
103 Info info = clazz.getAnnotation(Info.class);
104 if (info == null) {
105 DefaultLog.getInstance().warn(formatEntry(name, "", false, ""));
106 } else {
107 DefaultLog.getInstance().warn(formatEntry(format(name, clazz), info.since(), info.forRemoval(), info.use()));
108 }
109 }
110 }
111
112 private static String formatEntry(final String prefix, final String since, final boolean forRemoval, final String use) {
113 StringBuilder sb = new StringBuilder("Deprecated " + prefix);
114 if (forRemoval) {
115 sb.append(" Scheduled for removal");
116 if (!since.isEmpty()) {
117 sb.append(" since ").append(since);
118 }
119 sb.append(".");
120 } else if (!since.isEmpty()) {
121 sb.append(" Deprecated since ").append(since).append(".");
122 }
123 if (!use.isEmpty()) {
124 sb.append(" Use ").append(use).append(" instead.");
125 }
126 return sb.toString();
127 }
128
129 /**
130 * Log Deprecated class use.
131 * @param name The name of the deprecated tag
132 * @param since The version where the deprecation was declared.
133 * @param forRemoval If {@code true} then tag is scheduled for removal.
134 * @param use What to use instead.
135 */
136 public static void logDeprecated(final String name, final String since, final boolean forRemoval, final String use) {
137 DefaultLog.getInstance().warn(formatEntry(name, since, forRemoval, use));
138 }
139
140 /**
141 * Annotation to provide deprecation information for Java8.
142 * TODO RAT-528: remove this when Java 8 is no longer supported.
143 */
144 @Target({ElementType.TYPE})
145 @Retention(RetentionPolicy.RUNTIME)
146 public @interface Info {
147 /**
148 * The common name for the component. If not specified the name of the field or class is used.
149 * @return the component name.
150 */
151 String since() default "";
152
153 /**
154 * The description of the component.
155 * @return the component description.
156 */
157 boolean forRemoval() default false;
158 /**
159 * The component type.
160 * @return the component type.
161 */
162 String use() default "";
163 }
164 }