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         https://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          /**
59           * Constructs a new instance.
60           *
61           * @deprecated Use {@link #builder()}.
62           */
63          @Deprecated
64          public Builder() {
65              // empty
66          }
67  
68          @Override
69          public DeprecatedAttributes get() {
70              return new DeprecatedAttributes(description, since, forRemoval);
71          }
72  
73          /**
74           * Sets the description.
75           *
76           * @param description the description.
77           * @return {@code this} instance.
78           */
79          public Builder setDescription(final String description) {
80              this.description = description;
81              return this;
82          }
83  
84          /**
85           * Sets whether this option is subject to removal in a future version.
86           *
87           * @param forRemoval whether this is subject to removal in a future version.
88           * @return {@code this} instance.
89           * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
90           */
91          public Builder setForRemoval(final boolean forRemoval) {
92              this.forRemoval = forRemoval;
93              return this;
94          }
95  
96          /**
97           * Sets the version in which the option became deprecated.
98           *
99           * @param since the version in which the option became deprecated.
100          * @return {@code this} instance.
101          */
102         public Builder setSince(final String since) {
103             this.since = since;
104             return this;
105         }
106     }
107 
108     /**
109      * The default value for a DeprecatedAttributes.
110      */
111     static final DeprecatedAttributes DEFAULT = new DeprecatedAttributes("", "", false);
112 
113     /**
114      * The empty string.
115      */
116     private static final String EMPTY_STRING = "";
117 
118     /**
119      * Creates a new builder.
120      *
121      * @return a new builder.
122      */
123     public static Builder builder() {
124         return new Builder();
125     }
126 
127     /** The description. */
128     private final String description;
129 
130     /** Whether this option will be removed. */
131     private final boolean forRemoval;
132 
133     /** The version label for removal. */
134     private final String since;
135 
136     /**
137      * Constructs a new instance.
138      *
139      * @param description The description.
140      * @param since       The version label for removal.
141      * @param forRemoval  Whether this option will be removed.
142      */
143     private DeprecatedAttributes(final String description, final String since, final boolean forRemoval) {
144         this.description = toEmpty(description);
145         this.since = toEmpty(since);
146         this.forRemoval = forRemoval;
147     }
148 
149     /**
150      * Gets the descriptions.
151      *
152      * @return the descriptions.
153      */
154     public String getDescription() {
155         return description;
156     }
157 
158     /**
159      * Gets version in which the option became deprecated.
160      *
161      * @return the version in which the option became deprecated.
162      */
163     public String getSince() {
164         return since;
165     }
166 
167     /**
168      * Tests whether this option is subject to removal in a future version.
169      *
170      * @return whether this option is subject to removal in a future version.
171      */
172     public boolean isForRemoval() {
173         return forRemoval;
174     }
175 
176     private String toEmpty(final String since) {
177         return since != null ? since : EMPTY_STRING;
178     }
179 
180     @Override
181     public String toString() {
182         final StringBuilder builder = new StringBuilder("Deprecated");
183         if (forRemoval) {
184             builder.append(" for removal");
185         }
186         if (!since.isEmpty()) {
187             builder.append(" since ");
188             builder.append(since);
189         }
190         if (!description.isEmpty()) {
191             builder.append(": ");
192             builder.append(description);
193         }
194         return builder.toString();
195     }
196 }