1 /*
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16 */
17
18 package org.apache.commons.cli;
19
20 import java.util.function.Supplier;
21
22 /**
23 * Deprecated attributes.
24 * <p>
25 * Note: This class isn't called "Deprecated" to avoid clashing with "java.lang.Deprecated".
26 * </p>
27 * <p>
28 * If you want to serialize this class, use a serialization proxy.
29 * </p>
30 *
31 * @since 1.7.0
32 * @see Deprecated
33 */
34 public final class DeprecatedAttributes {
35
36 /**
37 * Builds {@link DeprecatedAttributes}.
38 */
39 public static class Builder implements Supplier<DeprecatedAttributes> {
40
41 /** The description. */
42 private String description;
43
44 /**
45 * Whether this option is subject to removal in a future version.
46 *
47 * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
48 */
49 private boolean forRemoval;
50
51 /**
52 * The version in which the option became deprecated.
53 *
54 * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.since</a>
55 */
56 private String since;
57
58 @Override
59 public DeprecatedAttributes get() {
60 return new DeprecatedAttributes(description, since, forRemoval);
61 }
62
63 /**
64 * Sets the description.
65 *
66 * @param description the description.
67 * @return {@code this} instance.
68 */
69 public Builder setDescription(final String description) {
70 this.description = description;
71 return this;
72 }
73
74 /**
75 * Whether this option is subject to removal in a future version.
76 *
77 * @param forRemoval whether this is subject to removal in a future version.
78 * @return {@code this} instance.
79 * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
80 */
81 public Builder setForRemoval(final boolean forRemoval) {
82 this.forRemoval = forRemoval;
83 return this;
84 }
85
86 /**
87 * Sets the version in which the option became deprecated.
88 *
89 * @param since the version in which the option became deprecated.
90 * @return {@code this} instance.
91 */
92 public Builder setSince(final String since) {
93 this.since = since;
94 return this;
95 }
96 }
97
98 /**
99 * The default value for a DeprecatedAttributes.
100 */
101 static final DeprecatedAttributes DEFAULT = new DeprecatedAttributes("", "", false);
102
103 /**
104 * The empty string.
105 */
106 private static final String EMPTY_STRING = "";
107
108 /**
109 * Creates a new builder.
110 *
111 * @return a new builder.
112 */
113 public static Builder builder() {
114 return new Builder();
115 }
116
117 /** The description. */
118 private final String description;
119
120 /** Whether this option will be removed. */
121 private final boolean forRemoval;
122
123 /** The version label for removal. */
124 private final String since;
125
126 /**
127 * Constructs a new instance.
128 *
129 * @param description The description.
130 * @param since The version label for removal.
131 * @param forRemoval Whether this option will be removed.
132 */
133 private DeprecatedAttributes(final String description, final String since, final boolean forRemoval) {
134 this.description = toEmpty(description);
135 this.since = toEmpty(since);
136 this.forRemoval = forRemoval;
137 }
138
139 /**
140 * Gets the descriptions.
141 *
142 * @return the descriptions.
143 */
144 public String getDescription() {
145 return description;
146 }
147
148 /**
149 * Gets version in which the option became deprecated.
150 *
151 * @return the version in which the option became deprecated.
152 */
153 public String getSince() {
154 return since;
155 }
156
157 /**
158 * Tests whether this option is subject to removal in a future version.
159 *
160 * @return whether this option is subject to removal in a future version.
161 */
162 public boolean isForRemoval() {
163 return forRemoval;
164 }
165
166 private String toEmpty(final String since) {
167 return since != null ? since : EMPTY_STRING;
168 }
169
170 @Override
171 public String toString() {
172 final StringBuilder builder = new StringBuilder("Deprecated");
173 if (forRemoval) {
174 builder.append(" for removal");
175 }
176 if (!since.isEmpty()) {
177 builder.append(" since ");
178 builder.append(since);
179 }
180 if (!description.isEmpty()) {
181 builder.append(": ");
182 builder.append(description);
183 }
184 return builder.toString();
185 }
186 }