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