001/*
002 *  This file is part of the Jikes RVM project (http://jikesrvm.org).
003 *
004 *  This file is licensed to You under the Eclipse Public License (EPL);
005 *  You may not use this file except in compliance with the License. You
006 *  may obtain a copy of the License at
007 *
008 *      http://www.opensource.org/licenses/eclipse-1.0.php
009 *
010 *  See the COPYRIGHT.txt file distributed with this work for information
011 *  regarding copyright ownership.
012 */
013package org.vmutil.options;
014
015/**
016 * The abstract base class for all options. This class also has
017 * the static interfaces to access the options system to set
018 * option values.
019 * <p>
020 * All options within the system should have a unique name. No
021 * two options shall have a name that is the same when a case
022 * insensitive comparison between the names with spaces removed
023 * is performed. Only basic alphanumeric characters and spaces
024 * are allowed.
025 * <p>
026 * The VM is required to provide a one way mapping function that
027 * takes the name and creates a VM style name, such as mapping
028 * "No Finalizer" to noFinalizer. The VM may not remove any letters
029 * when performing this mapping but may remove spaces and change
030 * the case of any character.
031 */
032public abstract class Option {
033  // Option types
034  public static final int BOOLEAN_OPTION = 1;
035  public static final int STRING_OPTION = 2;
036  public static final int ENUM_OPTION = 3;
037  public static final int INT_OPTION = 4;
038  public static final int PAGES_OPTION = 6;
039  public static final int MICROSECONDS_OPTION = 7;
040  public static final int FLOAT_OPTION = 8;
041  public static final int ADDRESS_OPTION = 9;
042
043  /*
044   * The possible output formats
045   */
046  public static final int READABLE = 0;
047  public static final int RAW = 1;
048  public static final int XML = 2;
049
050  // Per option values
051  private final int type;
052  private final String name;
053  private final String description;
054  private final String key;
055  private Option next;
056
057  protected OptionSet set;
058
059  /**
060   * Construct a new option. This also calls the VM to map the option's
061   * name into a unique option key and links it onto the option list.
062   *
063   * @param set The option set this option belongs to.
064   * @param type The option type as defined in this class.
065   * @param name The unique name of the option.
066   * @param description A short description of the option and purpose.
067   */
068  protected Option(OptionSet set, int type, String name, String description) {
069    this.type = type;
070    this.name = name;
071    this.description = description;
072    this.set = set;
073    this.key = set.register(this, name);
074  }
075
076  /**
077   * Return the VM determined key for an option
078   *
079   * @return The key.
080   */
081  public String getKey() {
082    return this.key;
083  }
084
085  /**
086   * Updates the next pointer in the Option chain.
087   *
088   * @param o the next option in the chain
089   */
090  void setNext(Option o) {
091    next = o;
092  }
093
094  /**
095   * Return the next option in the linked list.
096   *
097   * @return The next option or null if this is the last option.
098   */
099  public Option getNext() {
100    return this.next;
101  }
102
103  /**
104   * Return the name for the option.
105   *
106   * @return The option name.
107   */
108  public String getName() {
109    return this.name;
110  }
111
112  /**
113   * Return the option description.
114   *
115   * @return The option description.
116   */
117  public String getDescription() {
118    return this.description;
119  }
120
121  /**
122   * Return the type of the option.
123   *
124   * @return The option type.
125   */
126  public int getType() {
127    return this.type;
128  }
129
130  /**
131   * This is a validation method that can be implemented by leaf option
132   * classes to provide additional validation. This should not be implemented
133   * at other levels within the hierarchy to avoid confusion. The validate
134   * method works against the current value of the option (post-set).
135   */
136  protected void validate() {}
137
138  /**
139   * A fatal error occurred during the setting of an option. This method
140   * calls into the VM and is required to cause the system to stop.
141   *
142   * @param message The error message associated with the failure.
143   */
144  protected void fail(String message) {
145    set.fail(this, message);
146  }
147
148  /**
149   * Fail if a specified condition is met.
150   *
151   * @param condition The condition that indicates failure.
152   * @param message The error message associated with the failure.
153   */
154  protected void failIf(boolean condition, String message) {
155    if (condition) set.fail(this, message);
156  }
157
158  /**
159   * A non-fatal error occurred during the setting of an option. This method
160   * calls into the VM and shall not cause the system to stop.
161   *
162   * @param message The message associated with the warning.
163   */
164  protected void warn(String message) {
165    set.warn(this, message);
166  }
167
168  /**
169   * Warn if a specified condition is met.
170   *
171   * @param condition The condition that indicates warning.
172   * @param message The message associated with the warning.
173   */
174  protected void warnIf(boolean condition, String message) {
175    if (condition) set.warn(this, message);
176  }
177}
178