    001/*
    002  Licensed to the Apache Software Foundation (ASF) under one or more
    003  contributor license agreements.  See the NOTICE file distributed with
    004  this work for additional information regarding copyright ownership.
    005  The ASF licenses this file to You under the Apache License, Version 2.0
    006  (the "License"); you may not use this file except in compliance with
    007  the License.  You may obtain a copy of the License at
    008
    009      http://www.apache.org/licenses/LICENSE-2.0
    010
    011  Unless required by applicable law or agreed to in writing, software
    012  distributed under the License is distributed on an "AS IS" BASIS,
    013  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014  See the License for the specific language governing permissions and
    015  limitations under the License.
    016 */
    017
    018package org.apache.commons.cli;
    019
    020import java.util.function.Supplier;
    021
    022/**
    023 * Deprecated attributes.
    024 * <p>
    025 * Note: This class isn't called "Deprecated" to avoid clashing with "java.lang.Deprecated".
    026 * </p>
    027 * <p>
    028 * If you want to serialize this class, use a serialization proxy.
    029 * </p>
    030 *
    031 * @since 1.7.0
    032 * @see Deprecated
    033 */
    034public final class DeprecatedAttributes {
    035
    036    /**
    037     * Builds {@link DeprecatedAttributes}.
    038     */
    039    public static class Builder implements Supplier<DeprecatedAttributes> {
    040
    041        /** The description. */
    042        private String description;
    043
    044        /**
    045         * Whether this option is subject to removal in a future version.
    046         *
    047         * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
    048         */
    049        private boolean forRemoval;
    050
    051        /**
    052         * The version in which the option became deprecated.
    053         *
    054         * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.since</a>
    055         */
    056        private String since;
    057
    058        @Override
    059        public DeprecatedAttributes get() {
    060            return new DeprecatedAttributes(description, since, forRemoval);
    061        }
    062
    063        /**
    064         * Sets the description.
    065         *
    066         * @param description the description.
    067         * @return this.
    068         */
    069        public Builder setDescription(final String description) {
    070            this.description = description;
    071            return this;
    072        }
    073
    074        /**
    075         * Whether this option is subject to removal in a future version.
    076         *
    077         * @param forRemoval whether this is subject to removal in a future version.
    078         * @return this.
    079         * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
    080         */
    081        public Builder setForRemoval(final boolean forRemoval) {
    082            this.forRemoval = forRemoval;
    083            return this;
    084        }
    085
    086        /**
    087         * Sets the version in which the option became deprecated.
    088         *
    089         * @param since the version in which the option became deprecated.
    090         * @return this.
    091         */
    092        public Builder setSince(final String since) {
    093            this.since = since;
    094            return this;
    095        }
    096    }
    097
    098    /**
    099     * 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}