1 /*
   2  * Copyright (c) 2005, 2015, 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 
  26 package com.sun.management;
  27 
  28 import com.sun.management.internal.VMOptionCompositeData;
  29 import javax.management.openmbean.CompositeData;
  30 
  31 /**
  32  * Information about a VM option including its value and
  33  * where the value came from which is referred as its
  34  * {@link VMOption.Origin <i>origin</i>}.
  35  * <p>
  36  * Each VM option has a default value.  A VM option can
  37  * be set at VM creation time typically as a command line
  38  * argument to the launcher or an argument passed to the
  39  * VM created using the JNI invocation interface.
  40  * In addition, a VM option may be set via an environment
  41  * variable or a configuration file. A VM option can also
  42  * be set dynamically via a management interface after
  43  * the VM was started.
  44  *
  45  * A {@code VMOption} contains the value of a VM option
  46  * and the origin of that value at the time this {@code VMOption}
  47  * object was constructed.  The value of the VM option
  48  * may be changed after the {@code VMOption} object was constructed,
  49  *
  50  * @see <a href="{@docRoot}/../../../../technotes/guides/vm/index.html">
  51  *         Java Virtual Machine</a>
  52  * @author Mandy Chung
  53  * @since 1.6
  54  */
  55 @jdk.Exported
  56 public class VMOption {
  57     private String name;
  58     private String value;
  59     private boolean writeable;
  60     private Origin origin;
  61 
  62     /**
  63      * Origin of the value of a VM option.  It tells where the
  64      * value of a VM option came from.
  65      *
  66      * @since 1.6
  67      */
  68     @jdk.Exported
  69     public enum Origin {
  70         /**
  71          * The VM option has not been set and its value
  72          * is the default value.
  73          */
  74         DEFAULT,
  75         /**
  76          * The VM option was set at VM creation time typically
  77          * as a command line argument to the launcher or
  78          * an argument passed to the VM created using the
  79          * JNI invocation interface.
  80          */
  81         VM_CREATION,
  82         /**
  83          * The VM option was set via an environment variable.
  84          */
  85         ENVIRON_VAR,
  86         /**
  87          * The VM option was set via a configuration file.
  88          */
  89         CONFIG_FILE,
  90         /**
  91          * The VM option was set via the management interface after the VM
  92          * was started.
  93          */
  94         MANAGEMENT,
  95         /**
  96          * The VM option was set via the VM ergonomic support.
  97          */
  98         ERGONOMIC,
  99         /**
 100          * The VM option was set using the attach framework.
 101          * @since 1.9
 102          */
 103         ATTACH_ON_DEMAND,
 104         /**
 105          * The VM option was set via some other mechanism.
 106          */
 107         OTHER
 108     }
 109 
 110     /**
 111      * Constructs a {@code VMOption}.
 112      *
 113      * @param name Name of a VM option.
 114      * @param value Value of a VM option.
 115      * @param writeable {@code true} if a VM option can be set dynamically,
 116      *                  or {@code false} otherwise.
 117      * @param origin where the value of a VM option came from.
 118      *
 119      * @throws NullPointerException if the name or value is {@code null}
 120      */
 121     public VMOption(String name, String value, boolean writeable, Origin origin) {
 122         this.name = name;
 123         this.value = value;
 124         this.writeable = writeable;
 125         this.origin = origin;
 126     }
 127 
 128     /**
 129      * Constructs a {@code VMOption} object from a
 130      * {@link CompositeData CompositeData}.
 131      */
 132     private VMOption(CompositeData cd) {
 133         // validate the input composite data
 134         VMOptionCompositeData.validateCompositeData(cd);
 135 
 136         this.name = VMOptionCompositeData.getName(cd);
 137         this.value = VMOptionCompositeData.getValue(cd);
 138         this.writeable = VMOptionCompositeData.isWriteable(cd);
 139         this.origin = VMOptionCompositeData.getOrigin(cd);
 140     }
 141 
 142     /**
 143      * Returns the name of this VM option.
 144      *
 145      * @return the name of this VM option.
 146      */
 147     public String getName() {
 148         return name;
 149     }
 150 
 151     /**
 152      * Returns the value of this VM option at the time when
 153      * this {@code VMOption} was created. The value could have been changed.
 154      *
 155      * @return the value of the VM option at the time when
 156      *         this {@code VMOption} was created.
 157      */
 158     public String getValue() {
 159         return value;
 160     }
 161 
 162     /**
 163      * Returns the origin of the value of this VM option. That is,
 164      * where the value of this VM option came from.
 165      *
 166      * @return where the value of this VM option came from.
 167      */
 168     public Origin getOrigin() {
 169         return origin;
 170     }
 171 
 172     /**
 173      * Tests if this VM option is writeable.  If this VM option is writeable,
 174      * it can be set by the {@link HotSpotDiagnosticMXBean#setVMOption
 175      * HotSpotDiagnosticMXBean.setVMOption} method.
 176      *
 177      * @return {@code true} if this VM option is writeable; {@code false}
 178      * otherwise.
 179      */
 180     public boolean isWriteable() {
 181         return writeable;
 182     }
 183 
 184     public String toString() {
 185         return "VM option: " + getName() +
 186                " value: " + value + " " +
 187                " origin: " + origin + " " +
 188                (writeable ? "(read-write)" : "(read-only)");
 189     }
 190 
 191     /**
 192      * Returns a {@code VMOption} object represented by the
 193      * given {@code CompositeData}. The given {@code CompositeData}
 194      * must contain the following attributes:
 195      *
 196      * <blockquote>
 197      * <table border>
 198      * <tr>
 199      *   <th align=left>Attribute Name</th>
 200      *   <th align=left>Type</th>
 201      * </tr>
 202      * <tr>
 203      *   <td>name</td>
 204      *   <td>{@code java.lang.String}</td>
 205      * </tr>
 206      * <tr>
 207      *   <td>value</td>
 208      *   <td>{@code java.lang.String}</td>
 209      * </tr>
 210      * <tr>
 211      *   <td>origin</td>
 212      *   <td>{@code java.lang.String}</td>
 213      * </tr>
 214      * <tr>
 215      *   <td>writeable</td>
 216      *   <td>{@code java.lang.Boolean}</td>
 217      * </tr>
 218      * </table>
 219      * </blockquote>
 220      *
 221      * @param cd {@code CompositeData} representing a {@code VMOption}
 222      *
 223      * @throws IllegalArgumentException if {@code cd} does not
 224      *   represent a {@code VMOption} with the attributes described
 225      *   above.
 226      *
 227      * @return a {@code VMOption} object represented by {@code cd}
 228      *         if {@code cd} is not {@code null};
 229      *         {@code null} otherwise.
 230      */
 231     public static VMOption from(CompositeData cd) {
 232         if (cd == null) {
 233             return null;
 234         }
 235 
 236         if (cd instanceof VMOptionCompositeData) {
 237             return ((VMOptionCompositeData) cd).getVMOption();
 238         } else {
 239             return new VMOption(cd);
 240         }
 241 
 242     }
 243 
 244     // for sun.management.MappedMXBeanType
 245     static CompositeData toCompositeData(VMOption option) {
 246         return VMOptionCompositeData.toCompositeData(option);
 247     }
 248 }