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      */

   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 }