/*
* Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.jfr;
import java.security.AccessController;
import java.util.Set;
import jdk.jfr.internal.Control;
Base class to extend to create setting controls.
The following example shows a naive implementation of a setting control for
regular expressions:
final class RegExpControl extends SettingControl { private Pattern pattern = Pattern.compile(".*"); @Override public void setValue(String value) { this.pattern = Pattern.compile(value); } @Override public String combine(Set<String> values) { return String.join("|", values); } @Override public String getValue() { return pattern.toString(); } public String matches(String s) { return pattern.matcher(s).find(); } }
The setValue(String), getValue() and combine(Set<String>) methods are invoked when a setting value changes, which typically happens when a recording is started or stopped. The combine(Set<String>) method is invoked to resolve what value to use when multiple recordings are running at the same time.
The setting control must have a default constructor that can be invoked when
the event is registered.
To use a setting control with an event, add a method that returns a boolean value and takes the setting control as a parameter. Annotate the method with the @SettingDefinition annotation. By default, the method name is used as the setting name, but the name can be set explicitly by using the @Name annotation. If the method returns true, the event will be committed.
It is recommended that the setValue(String) method updates an efficient data structure that can be quickly checked when the event is committed.
The following example shows how to create an event that uses the
regular expression filter defined above.
abstract class HTTPRequest extends Event { @Label("Request URI") protected String uri; @Label("Servlet URI Filter") @SettingDefinition protected boolean uriFilter(RegExpControl regExp) { return regExp.matches(uri); } } @Label("HTTP Get Request") class HTTPGetRequest extends HTTPRequest { } @Label("HTTP Post Request") class HTTPPostRequest extends HTTPRequest { } class ExampleServlet extends HTTPServlet { protected void doGet(HttpServletRequest req, HttpServletResponse resp) { HTTPGetRequest request = new HTTPGetRequest(); request.begin(); request.uri = req.getRequestURI(); ... request.commit(); } protected void doPost(HttpServletRequest req, HttpServletResponse resp) { HTTPPostRequest request = new HTTPPostRequest(); request.begin(); request.uri = req.getRequestURI(); ... request.commit(); } }
The following example shows how an event can be filtered by assigning the "uriFilter" setting with the specified regular expressions.
Recording r = new Recording();
r.enable("HTTPGetRequest").with("uriFilter", "https://www.example.com/list/.*");
r.enable("HTTPPostRequest").with("uriFilter", "https://www.example.com/login/.*");
r.start();
See Also: Since: 9
/**
* Base class to extend to create setting controls.
* <p>
* The following example shows a naive implementation of a setting control for
* regular expressions:
*
* <pre>
* <code>
* final class RegExpControl extends SettingControl {
* private Pattern pattern = Pattern.compile(".*");
*
* {@literal @}Override
* public void setValue(String value) {
* this.pattern = Pattern.compile(value);
* }
*
* {@literal @}Override
* public String combine(Set{@literal <}String{@literal >} values) {
* return String.join("|", values);
* }
*
* {@literal @}Override
* public String getValue() {
* return pattern.toString();
* }
*
* public String matches(String s) {
* return pattern.matcher(s).find();
* }
* }
* </code>
* </pre>
*
* The {@code setValue(String)}, {@code getValue()} and
* {@code combine(Set<String>)} methods are invoked when a setting value
* changes, which typically happens when a recording is started or stopped. The
* {@code combine(Set<String>)} method is invoked to resolve what value to use
* when multiple recordings are running at the same time.
* <p>
* The setting control must have a default constructor that can be invoked when
* the event is registered.
* <p>
* To use a setting control with an event, add a method that returns a
* {@code boolean} value and takes the setting control as a parameter. Annotate
* the method with the {@code @SettingDefinition} annotation. By default, the
* method name is used as the setting name, but the name can be set explicitly
* by using the {@code @Name} annotation. If the method returns {@code true},
* the event will be committed.
* <p>
* It is recommended that the {@code setValue(String)} method updates an
* efficient data structure that can be quickly checked when the event is
* committed.
* <p>
* The following example shows how to create an event that uses the
* regular expression filter defined above.
*
* <pre>
* <code>
* abstract class HTTPRequest extends Event {
* {@literal @}Label("Request URI")
* protected String uri;
*
* {@literal @}Label("Servlet URI Filter")
* {@literal @}SettingDefinition
* protected boolean uriFilter(RegExpControl regExp) {
* return regExp.matches(uri);
* }
* }
*
* {@literal @}Label("HTTP Get Request")
* class HTTPGetRequest extends HTTPRequest {
* }
*
* {@literal @}Label("HTTP Post Request")
* class HTTPPostRequest extends HTTPRequest {
* }
*
* class ExampleServlet extends HTTPServlet {
* protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
* HTTPGetRequest request = new HTTPGetRequest();
* request.begin();
* request.uri = req.getRequestURI();
* ...
* request.commit();
* }
*
* protected void doPost(HttpServletRequest req, HttpServletResponse resp) {
* HTTPPostRequest request = new HTTPPostRequest();
* request.begin();
* request.uri = req.getRequestURI();
* ...
* request.commit();
* }
* }
* </code>
* </pre>
*
* The following example shows how an event can be filtered by assigning the
* {@code "uriFilter"} setting with the specified regular expressions.
*
* <pre>
* <code>
* Recording r = new Recording();
* r.enable("HTTPGetRequest").with("uriFilter", "https://www.example.com/list/.*");
* r.enable("HTTPPostRequest").with("uriFilter", "https://www.example.com/login/.*");
* r.start();
* </code>
* </pre>
*
*
*
* @see SettingDefinition
*
* @since 9
*/
@MetadataDefinition
public abstract class SettingControl extends Control {
Constructor for invocation by subclass constructors.
/**
* Constructor for invocation by subclass constructors.
*/
protected SettingControl() {
super(AccessController.getContext());
}
Combines the setting values for all running recordings into one value when
multiple recordings are running at the same time,
The semantics of how setting values are combined depends on the setting
control that is implemented, but all recordings should get at least all the
events they request.
This method should have no side effects, because the caller might cache values. This method should never return null or throw an exception. If a value is not valid for this setting control, the value should be ignored.
Examples:
if the setting control represents a threshold and three recordings are running at the same time with the setting values "10 ms", "8 s", and "1 ms", this method returns "1 ms" because it means that all recordings get at least all the requested data.
If the setting control represents a set of names and two recordings are running at the same time with the setting values "Smith, Jones" and "Jones,
Williams" the returned value is "Smith, Jones, Williams" because all names would be accepted.
If the setting control represents a boolean condition and four recordings are running at the same time with the following values "true", "false", "false", and "incorrect", this method returns "true", because all recordings get at least all the requested data.
Params: - settingValues – the set of values, not
null
Returns: the value to use, not null
/**
* Combines the setting values for all running recordings into one value when
* multiple recordings are running at the same time,
* <p>
* The semantics of how setting values are combined depends on the setting
* control that is implemented, but all recordings should get at least all the
* events they request.
* <p>
* This method should have no side effects, because the caller might cache values.
* This method should never return {@code null} or throw an exception. If a
* value is not valid for this setting control, the value should be ignored.
* <p>
* Examples:
* <p>
* if the setting control represents a threshold and three recordings are
* running at the same time with the setting values {@code "10 ms"},
* {@code "8 s"}, and {@code "1 ms"}, this method returns {@code "1 ms"}
* because it means that all recordings get at least all the requested data.
* <p>
* If the setting control represents a set of names and two recordings are
* running at the same time with the setting values {@code "Smith, Jones"} and {@code "Jones,
* Williams"} the returned value is {@code "Smith, Jones, Williams"} because all names would be accepted.
* <p>
* If the setting control represents a boolean condition and four recordings are
* running at the same time with the following values {@code "true"}, {@code "false"}, {@code "false"}, and
* {@code "incorrect"}, this method returns {@code "true"}, because all
* recordings get at least all the requested data.
*
* @param settingValues the set of values, not {@code null}
*
* @return the value to use, not {@code null}
*/
@Override
public abstract String combine(Set<String> settingValues);
Sets the value for this setting.
If the setting value is not valid for this setting, this method
does not throw an exception. Instead, the value is ignored.
Params: - settingValue – the string value, not
null
/**
* Sets the value for this setting.
* <p>
* If the setting value is not valid for this setting, this method
* does not throw an exception. Instead, the value is ignored.
*
* @param settingValue the string value, not {@code null}
*/
@Override
public abstract void setValue(String settingValue);
Returns the currently used value for this setting, not null. The value returned by this method is valid as an argument to both the setValue(String) method and combine(Set) method.
This method is invoked when an event is registered to obtain the default value. It is therefore important that a valid value can be returned immediately after an instance of this class is created. It is not valid to return null.
Returns: the setting value, not null
/**
* Returns the currently used value for this setting, not {@code null}.
* <p>
* The value returned by this method is valid as an argument to both
* the {@code setValue(String)} method and {@code combine(Set)} method.
* <p>
* This method is invoked when an event is registered to obtain the
* default value. It is therefore important that a valid value can be
* returned immediately after an instance of this class is created. It is
* not valid to return {@code null}.
*
* @return the setting value, not {@code null}
*/
@Override
public abstract String getValue();
}