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.time.Duration;
  29 import java.util.Map;
  30 
  31 /**
  32  * Convenience class for applying event settings to a recording.
  33  * <p>
  34  * An event setting object for a recording can be obtained by invoking
  35  * the {@link Recording#enable(String)} method which is configured using method
  36  * chaining.
  37  * <p>
  38  * The following example shows how to use the {@code EventSetting} class.
  39  * <pre>
  40  * {@code
  41  * Recording r = new Recording();
  42  * r.enable("com.oracle.jdk.CPULoad")
  43  *    .withPeriod(Duration.ofSeconds(1));
  44  * r.enable("com.oracle.jdk.FileWrite")
  45  *    .withoutStackTrace()
  46  *    .withThreshold(Duration.ofNanos(10));
  47  * r.start();
  48  * Thread.sleep(10_000);
  49  * r.stop();
  50  * r.dump(Files.createTempFile("recording", ".jfr"));
  51  *
  52  * }
  53  * </pre>
  54  * @since 9
  55  */
  56 public abstract class EventSettings {
  57 
  58     // package private
  59     EventSettings() {
  60     }
  61 
  62     /**
  63      * Enables stack traces for the event that is associated with this event setting.
  64      *
  65      * Equivalent to invoking the {@code with("stackTrace", "true")} method.
  66      *
  67      * @return event settings object for further configuration, not {@code null}
  68      */
  69     final public EventSettings withStackTrace() {
  70         return with(StackTrace.NAME, "true");
  71     }
  72 
  73     /**
  74      * Disables stack traces for the event that is associated with this event setting.
  75      *
  76      * Equivalent to invoking the {@code with("stackTrace", "false")} method.
  77      *
  78      * @return event settings object for further configuration, not {@code null}
  79      */
  80     final public EventSettings withoutStackTrace() {
  81         return with(StackTrace.NAME, "false");
  82     }
  83 
  84     /**
  85      * Specifies that a threshold is not used.
  86      * <p>
  87      * This is a convenience method, equivalent to invoking the
  88      * {@code with("threshold", "0 s")} method.
  89      *
  90      * @return event settings object for further configuration, not {@code null}
  91      */
  92     final public EventSettings withoutThreshold() {
  93         return with(Threshold.NAME, "0 s");
  94     }
  95 
  96     /**
  97      * Sets the interval for the event that is associated with this event setting.
  98      *
  99      * @param duration the duration, not {@code null}
 100      *
 101      * @return event settings object for further configuration, not {@code null}
 102      */
 103     final public EventSettings withPeriod(Duration duration) {
 104         return with(Period.NAME, duration.toNanos() + " ns");
 105     }
 106 
 107     /**
 108      * Sets the threshold for the event that is associated with this event setting.
 109      *
 110      * @param duration the duration, or {@code null} if no duration is used
 111      *
 112      * @return event settings object for further configuration, not {@code null}
 113      */
 114     final public EventSettings withThreshold(Duration duration) {
 115         if (duration == null) {
 116             return with(Threshold.NAME, "0 ns");
 117         } else {
 118             return with(Threshold.NAME, duration.toNanos() + " ns");
 119         }
 120     }
 121 
 122     /**
 123      * Sets a setting value for the event that is associated with this event setting.
 124      *
 125      * @param name the name of the setting (for example, {@code "threshold"})
 126      *
 127      * @param value the value to set (for example {@code "20 ms"} not
 128      *        {@code null})
 129      *
 130      * @return event settings object for further configuration, not {@code null}
 131      */
 132     abstract public EventSettings with(String name, String value);
 133 
 134     /**
 135      * Creates a settings {@code Map} for the event that is associated with this
 136      * event setting.
 137      *
 138      * @return a settings {@code Map}, not {@code null}
 139      */
 140     abstract Map<String, String> toMap();
 141 }