Module jdk.jfr
Package jdk.jfr

Class SettingControl

java.lang.Object
jdk.jfr.SettingControl
public abstract class SettingControl extends Object
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 boolean 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();

Since:
9
See Also: