    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      https://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        /**
    059         * Constructs a new instance.
    060         *
    061         * @deprecated Use {@link #builder()}.
    062         */
    063        @Deprecated
    064        public Builder() {
    065            // empty
    066        }
    067
    068        @Override
    069        public DeprecatedAttributes get() {
    070            return new DeprecatedAttributes(description, since, forRemoval);
    071        }
    072
    073        /**
    074         * Sets the description.
    075         *
    076         * @param description the description.
    077         * @return {@code this} instance.
    078         */
    079        public Builder setDescription(final String description) {
    080            this.description = description;
    081            return this;
    082        }
    083
    084        /**
    085         * Sets whether this option is subject to removal in a future version.
    086         *
    087         * @param forRemoval whether this is subject to removal in a future version.
    088         * @return {@code this} instance.
    089         * @see <a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Deprecated.html#forRemoval()">Deprecated.forRemoval</a>
    090         */
    091        public Builder setForRemoval(final boolean forRemoval) {
    092            this.forRemoval = forRemoval;
    093            return this;
    094        }
    095
    096        /**
    097         * Sets the version in which the option became deprecated.
    098         *
    099         * @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}