1 /*
2 * Copyright (c) 2016, 2018, 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 jdk.jfr;
27
28 import java.io.IOException;
29 import java.io.Reader;
30 import java.nio.file.Files;
31 import java.nio.file.Path;
32 import java.text.ParseException;
33 import java.util.ArrayList;
34 import java.util.Collections;
35 import java.util.LinkedHashMap;
36 import java.util.List;
37 import java.util.Map;
38 import java.util.Objects;
39
40 import jdk.jfr.internal.JVMSupport;
41 import jdk.jfr.internal.jfc.JFC;
42
43 /**
44 * A collection of settings and metadata describing the configuration.
45 *
46 * @since 9
47 */
48 public final class Configuration {
49 private final Map<String, String> settings;
50 private final String label;
51 private final String description;
52 private final String provider;
53 private final String contents;
54 private final String name;
55
56 // package private
57 Configuration(String name, String label, String description, String provider, Map<String, String> settings, String contents) {
58 this.name = name;
59 this.label = label;
60 this.description = description;
61 this.provider = provider;
62 this.settings = settings;
63 this.contents = contents;
64 }
65
66 /**
67 * Returns the settings that specifies how a recording is configured.
68 * <p>
69 * Modifying the returned {@code Map} object doesn't change the
70 * configuration.
71 *
72 * @return settings, not {@code null}
73 */
74 public Map<String, String> getSettings() {
75 return new LinkedHashMap<String, String>(settings);
76 }
77
78 /**
79 * Returns an identifying name (for example, {@code "default" or "profile")}.
80 *
81 * @return the name, or {@code null} if it doesn't exist
82 */
83 public String getName() {
84 return this.name;
85 }
86
87 /**
88 * Returns a human-readable name (for example, {@code "Continuous" or "Profiling"}.
89 *
90 * @return the configuration name, or {@code null} if it doesn't exist
91 */
92 public String getLabel() {
93 return this.label;
94 }
95
96 /**
97 * Returns a short sentence that describes the configuration (for example
98 * {@code "Low
99 * overhead configuration safe for continuous use in production
100 * environments"})
101 *
102 * @return the description, or {@code null} if it doesn't exist
103 */
104 public String getDescription() {
105 return description;
106 }
107
108 /**
109 * Returns who created the configuration (for example {@code "Oracle"}).
110 *
111 * @return the provider, or {@code null} if it doesn't exist
112 */
113 public String getProvider() {
114 return provider;
115 }
116
117 /**
118 * Returns a textual representation of the configuration (for example, the
119 * contents of a JFC file).
120 *
121 * @return contents, or {@code null} if it doesn't exist
122 *
123 * @see Configuration#getContents()
124 */
125 public String getContents() {
126 return contents;
127 }
128
129 /**
130 * Reads a configuration from a file.
131 *
132 * @param path the file that contains the configuration, not {@code null}
133 * @return the read {@link Configuration}, not {@code null}
134 * @throws ParseException if the file can't be parsed
135 * @throws IOException if the file can't be read
136 * @throws SecurityException if a security manager exists and its
137 * {@code checkRead} method denies read access to the file.
138 *
139 * @see java.io.File#getPath()
140 * @see java.lang.SecurityManager#checkRead(java.lang.String)
141 */
142 public static Configuration create(Path path) throws IOException, ParseException {
143 Objects.requireNonNull(path);
144 JVMSupport.ensureWithIOException();
145 try (Reader reader = Files.newBufferedReader(path)) {
146 return JFC.create(JFC.nameFromPath(path), reader);
147 }
148 }
149
150 /**
151 * Reads a configuration from a reader.
152 *
153 * @param reader a reader that contains the configuration contents, not
154 * {@code null}
155 * @return a configuration, not {@code null}
156 * @throws IOException if an I/O error occurs while trying to read contents
157 * from the reader
158 * @throws ParseException if the file can't be parsed
159 */
160 public static Configuration create(Reader reader) throws IOException, ParseException {
161 Objects.requireNonNull(reader);
162 JVMSupport.ensureWithIOException();
163 return JFC.create(null, reader);
164 }
165
166 /**
167 * Returns a predefined configuration.
168 * <p>
169 * See {@link Configuration#getConfigurations()} for available configuration
170 * names.
171 *
172 * @param name the name of the configuration (for example, "default" or
173 * "profile")
174 * @return a configuration, not {@code null}
175 *
176 * @throws IOException if a configuration with the given name does not
177 * exist, or if an I/O error occurs while reading the
178 * configuration file
179 * @throws ParseException if the configuration file can't be parsed
180 */
181 public static Configuration getConfiguration(String name) throws IOException, ParseException {
182 JVMSupport.ensureWithIOException();
183 return JFC.getPredefined(name);
184 }
185
186 /**
187 * Returns an immutable list of predefined configurations for this JVM.
188 *
189 * @return the list of predefined configurations, not {@code null}
190 */
191 public static List<Configuration> getConfigurations() {
192 if (JVMSupport.isNotAvailable()) {
193 return new ArrayList<>();
194 }
195 return Collections.unmodifiableList(JFC.getConfigurations());
196 }
197 }