View Javadoc
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 }