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 label, 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 "OpenJDK"}).

   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 character stream.

   152      *

   153      * @param reader a {@code Reader} that provides 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 {@code 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, {@code "default"} or

   173      *        {@code "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 Java Virtual Machine (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 }