1 /*

     2  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package org.graalvm.options;

    26 

    27 import java.util.Objects;

    28 

    29 /**

    30  * Represents metadata for a single option.

    31  *

    32  * @since 1.0

    33  */

    34 public final class OptionDescriptor {

    35 

    36     private final OptionKey<?> key;

    37     private final String name;

    38     private final String help;

    39     private final OptionCategory kind;

    40     private final boolean deprecated;

    41 

    42     OptionDescriptor(OptionKey<?> key, String name, String help, OptionCategory kind, boolean deprecated) {

    43         this.key = key;

    44         this.name = name;

    45         this.help = help;

    46         this.kind = kind;

    47         this.deprecated = deprecated;

    48     }

    49 

    50     /**

    51      * Returns the name of the option that this descriptor represents.

    52      *

    53      * @since 1.0

    54      */

    55     public String getName() {

    56         return name;

    57     }

    58 

    59     /**

    60      * Returns the key for this option.

    61      *

    62      * @since 1.0

    63      */

    64     public OptionKey<?> getKey() {

    65         return key;

    66     }

    67 

    68     /**

    69      * Returns <code>true</code> if this option was marked deprecated. This indicates that the

    70      * option is going to be removed in a future release or its use is not recommended.

    71      *

    72      * @since 1.0

    73      */

    74     public boolean isDeprecated() {

    75         return deprecated;

    76     }

    77 

    78     /**

    79      * Returns the user category of this option.

    80      *

    81      * @since 1.0

    82      */

    83     public OptionCategory getCategory() {

    84         return kind;

    85     }

    86 

    87     /**

    88      * Returns a human-readable description on how to use the option.

    89      *

    90      * @since 1.0

    91      */

    92     public String getHelp() {

    93         return help;

    94     }

    95 

    96     /**

    97      * {@inheritDoc}

    98      *

    99      * @since 1.0

   100      */

   101     @Override

   102     public String toString() {

   103         return "OptionDescriptor [key=" + key + ", help=" + help + ", kind=" + kind + ", deprecated=" + deprecated + "]";

   104     }

   105 

   106     /**

   107      * {@inheritDoc}

   108      *

   109      * @since 1.0

   110      */

   111     @Override

   112     public int hashCode() {

   113         final int prime = 31;

   114         int result = 1;

   115         result = prime * result + (deprecated ? 1231 : 1237);

   116         result = prime * result + ((help == null) ? 0 : help.hashCode());

   117         result = prime * result + ((key == null) ? 0 : key.hashCode());

   118         result = prime * result + ((kind == null) ? 0 : kind.hashCode());

   119         result = prime * result + ((name == null) ? 0 : name.hashCode());

   120         return result;

   121     }

   122 

   123     /**

   124      * {@inheritDoc}

   125      *

   126      * @since 1.0

   127      */

   128     @Override

   129     public boolean equals(Object obj) {

   130         if (this == obj) {

   131             return true;

   132         } else if (obj == null) {

   133             return false;

   134         } else if (getClass() != obj.getClass()) {

   135             return false;

   136         }

   137         OptionDescriptor other = (OptionDescriptor) obj;

   138         return Objects.equals(name, other.name) &&

   139                         Objects.equals(deprecated, other.deprecated) &&

   140                         Objects.equals(help, other.help) &&

   141                         Objects.equals(key, other.key) &&

   142                         Objects.equals(kind, other.kind);

   143     }

   144 

   145     /**

   146      * Creates a new option descriptor builder by key. The option group and name is inferred by the

   147      * key.

   148      *

   149      * @since 1.0

   150      */

   151     public static <T> Builder newBuilder(OptionKey<T> key, String name) {

   152         Objects.requireNonNull(key);

   153         Objects.requireNonNull(name);

   154         return EMPTY.new Builder(key, name);

   155     }

   156 

   157     private static final OptionDescriptor EMPTY = new OptionDescriptor(null, null, null, null, false);

   158 

   159     /**

   160      * Represents an option descriptor builder.

   161      *

   162      * @since 1.0

   163      */

   164     public final class Builder {

   165 

   166         private final OptionKey<?> key;

   167         private final String name;

   168         private boolean deprecated;

   169         private OptionCategory category;

   170         private String help;

   171 

   172         Builder(OptionKey<?> key, String name) {

   173             this.key = key;

   174             this.name = name;

   175         }

   176 

   177         /**

   178          * Defines the user category for this option. The default value is

   179          * {@link OptionCategory#DEBUG}.

   180          *

   181          * @since 1.0

   182          */

   183         public Builder category(@SuppressWarnings("hiding") OptionCategory category) {

   184             Objects.requireNonNull(category);

   185             this.category = category;

   186             return this;

   187         }

   188 

   189         /**

   190          * Defines if this option is deprecated. The default value for deprecated is

   191          * <code>false</code>. This can be used to evolve options between releases.

   192          *

   193          * @since 1.0

   194          */

   195         public Builder deprecated(@SuppressWarnings("hiding") boolean deprecated) {

   196             this.deprecated = deprecated;

   197             return this;

   198         }

   199 

   200         /**

   201          * Specifies a human-readable description on how to use the option.

   202          *

   203          * @since 1.0

   204          */

   205         public Builder help(@SuppressWarnings("hiding") String help) {

   206             Objects.requireNonNull(help);

   207             this.help = help;

   208             return this;

   209         }

   210 

   211         /**

   212          * Builds and returns a new option descriptor.

   213          *

   214          * @since 1.0

   215          */

   216         public OptionDescriptor build() {

   217             return new OptionDescriptor(key, name, help == null ? "" : help, category == null ? OptionCategory.DEBUG : category, deprecated);

   218         }

   219 

   220     }

   221 

   222 }