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 }