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 consumer that is used for deprecation reporting.
46 */
47 private static Consumer<Option> consumer = getDefault();
48
49 /**
50 * Get the default reporter.
51 * @return The default reporter.
52 */
53 public static Consumer<Option> getDefault() {
54 return o -> {
55 StringBuilder buff = new StringBuilder();
56 if (o.getOpt() != null) {
57 buff.append("-").append(o.getOpt());
58 if (o.getLongOpt() != null) {
59 buff.append(", --").append(o.getLongOpt());
60 }
61 } else {
62 buff.append("--").append(o.getLongOpt());
63 }
64 DefaultLog.getInstance().warn(format("Option [%s] used. %s", buff, o.getDeprecated().toString()));
65 };
66 }
67
68 /**
69 * Creates the consumer that will log usage of deprecated operations to the default log.
70 * @return The consumer that will log usage of deprecated operations to the default log.
71 */
72 public static Consumer<Option> getLogReporter() {
73 return consumer;
74 }
75
76 /**
77 * Sets the consumer that will do the reporting.
78 * @param consumer The consumer that will do the reporting.
79 */
80 public static void setLogReporter(final Consumer<Option> consumer) {
81 DeprecationReporter.consumer = consumer;
82 }
83
84 /**
85 * Rests the consumer to the default consumer.
86 */
87 public static void resetLogReporter() {
88 DeprecationReporter.consumer = getDefault();
89 }
90
91 /**
92 * Log Deprecated class use.
93 * @param clazz the Deprecated class to log
94 */
95 public static void logDeprecated(final Class<?> clazz) {
96 if (clazz.getAnnotation(Deprecated.class) != null) {
97 String name = format("Deprecated class used: %s ", clazz);
98 Info info = clazz.getAnnotation(Info.class);
99 if (info == null) {
100 DefaultLog.getInstance().warn(formatEntry(name, "", false, ""));
101 } else {
102 DefaultLog.getInstance().warn(formatEntry(format(name, clazz), info.since(), info.forRemoval(), info.use()));
103 }
104 }
105 }
106
107 private static String formatEntry(final String prefix, final String since, final boolean forRemoval, final String use) {
108 StringBuilder sb = new StringBuilder("Deprecated " + prefix);
109 if (forRemoval) {
110 sb.append(" Scheduled for removal");
111 if (!since.isEmpty()) {
112 sb.append(" since ").append(since);
113 }
114 sb.append(".");
115 } else if (!since.isEmpty()) {
116 sb.append(" Deprecated since ").append(since).append(".");
117 }
118 if (!use.isEmpty()) {
119 sb.append(" Use ").append(use).append(" instead.");
120 }
121 return sb.toString();
122 }
123
124 /**
125 * Log Deprecated class use.
126 * @param name The name of the deprecated tag
127 * @param since The version where the deprecation was declared.
128 * @param forRemoval If {@code true} then tag is scheduled for removal.
129 * @param use What to use instead.
130 */
131 public static void logDeprecated(final String name, final String since, final boolean forRemoval, final String use) {
132 DefaultLog.getInstance().warn(formatEntry(name, since, forRemoval, use));
133 }
134
135 /**
136 * Annotation to provide deprecation information for Java8.
137 * TODO remove this when Java 8 no longer supported.
138 */
139 @Target({ElementType.TYPE})
140 @Retention(RetentionPolicy.RUNTIME)
141 public @interface Info {
142 /**
143 * The common name for the component. If not specified the name of the field or class is used.
144 * @return the component name.
145 */
146 String since() default "";
147
148 /**
149 * The description of the component.
150 * @return the component description.
151 */
152 boolean forRemoval() default false;
153 /**
154 * The component type.
155 * @return the component type.
156 */
157 String use() default "";
158 }
159 }