1 /*
   2  * Copyright (c) 2016, 2019, 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 8
 147  */
 148 @MetadataDefinition
 149 public abstract class SettingControl extends Control {
 150 
 151     /**
 152      * Constructor for invocation by subclass constructors.
 153      */
 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
 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
 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
 219     public abstract String getValue();
 220 }