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.security.AccessController; 29 import java.util.Set; 30 31 import jdk.jfr.internal.Control; 32 33 /** 34 * Base class to extend to create setting controls. 35 * <p> 36 * The following example shows a naive implementation of a setting control for 37 * regular expressions: 38 * 39 * <pre> 40 * <code> 41 * final class RegExpControl extends SettingControl { 42 * private Pattern pattern = Pattern.compile(".*"); 43 * 44 * {@literal @}Override 45 * public void setValue(String value) { 46 * this.pattern = Pattern.compile(value); 47 * } 48 * 49 * {@literal @}Override 50 * public String combine(Set{@literal <}String{@literal >} values) { 51 * return String.join("|", values); 52 * } 53 * 54 * {@literal @}Override 55 * public String getValue() { 56 * return pattern.toString(); 57 * } 58 * 59 * public String matches(String s) { 60 * return pattern.matcher(s).find(); 61 * } 62 * } 63 * </code> 64 * </pre> 65 * 66 * The {@code setValue(String)}, {@code getValue()} and 67 * {@code combine(Set<String>)} methods are invoked when a setting value 68 * changes, which typically happens when a recording is started or stopped. The 69 * {@code combine(Set<String>)} method is invoked to resolve what value to use 70 * when multiple recordings are running at the same time. 71 * <p> 72 * The setting control must have a default constructor that can be invoked when 73 * the event is registered. 74 * <p> 75 * To use a setting control with an event, add a method that returns a 76 * {@code boolean} value and takes the setting control as a parameter. Annotate 77 * the method with the {@code @SettingDefinition} annotation. By default, the 78 * method name is used as the setting name, but the name can be set explicitly 79 * by using the {@code @Name} annotation. If the method returns {@code true}, 80 * the event will be committed. 81 * <p> 82 * It is recommended that the {@code setValue(String)} method updates an 83 * efficient data structure that can be quickly checked when the event is 84 * committed. 85 * <p> 86 * The following example shows how to create an event that uses the 87 * regular expression filter defined above. 88 * 89 * <pre> 90 * <code> 91 * abstract class HTTPRequest extends Event { 92 * {@literal @}Label("Request URI") 93 * protected String uri; 94 * 95 * {@literal @}Label("Servlet URI Filter") 96 * {@literal @}SettingDefinition 97 * protected boolean uriFilter(RegExpControl regExp) { 98 * return regExp.matches(uri); 99 * } 100 * } 101 * 102 * {@literal @}Label("HTTP Get Request") 103 * class HTTPGetRequest extends HTTPRequest { 104 * } 105 * 106 * {@literal @}Label("HTTP Post Request") 107 * class HTTPPostRequest extends HTTPRequest { 108 * } 109 * 110 * class ExampleServlet extends HTTPServlet { 111 * protected void doGet(HttpServletRequest req, HttpServletResponse resp) { 112 * HTTPGetRequest request = new HTTPGetRequest(); 113 * request.begin(); 114 * request.uri = req.getRequestURI(); 115 * ... 116 * request.commit(); 117 * } 118 * 119 * protected void doPost(HttpServletRequest req, HttpServletResponse resp) { 120 * HTTPPostRequest request = new HTTPPostRequest(); 121 * request.begin(); 122 * request.uri = req.getRequestURI(); 123 * ... 124 * request.commit(); 125 * } 126 * } 127 * </code> 128 * </pre> 129 * 130 * The following example shows how an event can be filtered by assigning the 131 * {@code "uriFilter"} setting with the specified regular expressions. 132 * 133 * <pre> 134 * <code> 135 * Recording r = new Recording(); 136 * r.enable("HTTPGetRequest").with("uriFilter", "https://www.example.com/list/.*"); 137 * r.enable("HTTPPostRequest").with("uriFilter", "https://www.example.com/login/.*"); 138 * r.start(); 139 * </code> 140 * </pre> 141 * 142 * 143 * 144 * @see SettingDefinition 145 * 146 * @since 9 147 */ 148 @MetadataDefinition 149 public abstract class SettingControl extends Control { 150 151 /** 152 * Constructor for invocation by subclass constructors. 153 */ SettingControl()154 protected SettingControl() { 155 super(AccessController.getContext()); 156 157 } 158 159 /** 160 * Combines the setting values for all running recordings into one value when 161 * multiple recordings are running at the same time, 162 * <p> 163 * The semantics of how setting values are combined depends on the setting 164 * control that is implemented, but all recordings should get at least all the 165 * events they request. 166 * <p> 167 * This method should have no side effects, because the caller might cache values. 168 * This method should never return {@code null} or throw an exception. If a 169 * value is not valid for this setting control, the value should be ignored. 170 * <p> 171 * Examples: 172 * <p> 173 * if the setting control represents a threshold and three recordings are 174 * running at the same time with the setting values {@code "10 ms"}, 175 * {@code "8 s"}, and {@code "1 ms"}, this method returns {@code "1 ms"} 176 * because it means that all recordings get at least all the requested data. 177 * <p> 178 * If the setting control represents a set of names and two recordings are 179 * running at the same time with the setting values {@code "Smith, Jones"} and {@code "Jones, 180 * Williams"} the returned value is {@code "Smith, Jones, Williams"} because all names would be accepted. 181 * <p> 182 * If the setting control represents a boolean condition and four recordings are 183 * running at the same time with the following values {@code "true"}, {@code "false"}, {@code "false"}, and 184 * {@code "incorrect"}, this method returns {@code "true"}, because all 185 * recordings get at least all the requested data. 186 * 187 * @param settingValues the set of values, not {@code null} 188 * 189 * @return the value to use, not {@code null} 190 */ 191 @Override combine(Set<String> settingValues)192 public abstract String combine(Set<String> settingValues); 193 194 /** 195 * Sets the value for this setting. 196 * <p> 197 * If the setting value is not valid for this setting, this method 198 * does not throw an exception. Instead, the value is ignored. 199 * 200 * @param settingValue the string value, not {@code null} 201 */ 202 @Override setValue(String settingValue)203 public abstract void setValue(String settingValue); 204 205 /** 206 * Returns the currently used value for this setting, not {@code null}. 207 * <p> 208 * The value returned by this method is valid as an argument to both 209 * the {@code setValue(String)} method and {@code combine(Set)} method. 210 * <p> 211 * This method is invoked when an event is registered to obtain the 212 * default value. It is therefore important that a valid value can be 213 * returned immediately after an instance of this class is created. It is 214 * not valid to return {@code null}. 215 * 216 * @return the setting value, not {@code null} 217 */ 218 @Override getValue()219 public abstract String getValue(); 220 } 221