:register_method:	true
:filter_method:		true
:plugintype:    	filter
:pluginclass:   	Filters
:pluginname:    	example
:pluginnamecap: 	Example
:plugintypecap:   Filter
:sversion:        '0.0.1'

:pluginrepo:      https://github.com/logstash-plugins/logstash-filter-java_filter_example[example filter plugin]

:blockcodec:		true

[[java-filter-plugin]]
=== How to write a Java filter plugin

// Pulls in shared section: Setting Up Environment
include::include/javapluginsetup.asciidoc[]

[float]
=== Code the plugin

The example filter plugin allows one to configure a field in each event that
will be reversed. For example, if the filter were  configured to reverse the
`day_of_week` field, an event with `day_of_week: "Monday"` would be transformed
to `day_of_week: "yadnoM"`. Let's look at the main class in that example filter:
 
[source,java]
-----
@LogstashPlugin(name = "java_filter_example")
public class JavaFilterExample implements Filter {

    public static final PluginConfigSpec<String> SOURCE_CONFIG =
            PluginConfigSpec.stringSetting("source", "message");

    private String id;
    private String sourceField;

    public JavaFilterExample(String id, Configuration config, Context context) {
        this.id = id;
        this.sourceField = config.get(SOURCE_CONFIG);
    }

    @Override
    public Collection<Event> filter(Collection<Event> events, FilterMatchListener matchListener) {
        for (Event e : events) {
            Object f = e.getField(sourceField);
            if (f instanceof String) {
                e.setField(sourceField, StringUtils.reverse((String)f));
                matchListener.filterMatched(e);                
            }
        }
        return events;
    }

    @Override
    public Collection<PluginConfigSpec<?>> configSchema() {
        return Collections.singletonList(SOURCE_CONFIG);
    }
    
    @Override
    public String getId() {
        return this.id;
    }      
}
-----

Let's step through and examine each part of that class.

[float]
==== Class declaration

[source,java]
-----
@LogstashPlugin(name = "java_filter_example")
public class JavaFilterExample implements Filter {
-----

Notes about the class declaration:

* All Java plugins must be annotated with the `@LogstashPlugin` annotation. Additionally:
** The `name` property of the annotation must be supplied and defines the name of the plugin as it will be used
   in the Logstash pipeline definition. For example, this filter would be referenced in the filter section of the
   Logstash pipeline defintion as `filter { java_filter_example => { .... } }`
** The value of the `name` property must match the name of the class excluding casing and underscores.
* The class must implement the `co.elastic.logstash.api.Filter` interface.
* Java plugins may not be created in the `org.logstash` or `co.elastic.logstash` packages to prevent potential
clashes with classes in Logstash itself.

[float]
==== Plugin settings
The snippet below contains both the setting definition and the method referencing it:

[source,java]
-----
public static final PluginConfigSpec<String> SOURCE_CONFIG =
        PluginConfigSpec.stringSetting("source", "message");

@Override
public Collection<PluginConfigSpec<?>> configSchema() {
    return Collections.singletonList(SOURCE_CONFIG);
}
-----

The `PluginConfigSpec` class allows developers to specify the settings that a plugin supports complete with setting 
name, data type, deprecation status, required status, and default value. In this example, the `source` setting defines
the name of the field in each event that will be reversed. It is not a required setting and if it is not explicitly
set, its default value will be `message`.

The `configSchema` method must return a list of all settings that the plugin supports. In a future phase of the
Java plugin project, the Logstash execution engine will validate that all required settings are present and that
no unsupported settings are present.

[float]
==== Constructor and initialization

[source,java]
-----
private String id;
private String sourceField;

public JavaFilterExample(String id, Configuration config, Context context) {
    this.id = id;
    this.sourceField = config.get(SOURCE_CONFIG);
}
-----

All Java filter plugins must have a constructor taking a `String` id and a
`Configuration` and `Context` argument.  This is the constructor that will be
used to instantiate them at runtime. The retrieval and validation of all plugin
settings should occur in this constructor. In this example, the name of the
field to be reversed in each event is  retrieved from its setting and stored in
a local variable so that it can be used later in the `filter` method. 

Any additional initialization may occur in the constructor as well. If there are
any unrecoverable errors encountered in the configuration or initialization of
the filter plugin, a descriptive exception should be thrown. The exception will
be logged and will prevent Logstash from starting.

[float]
==== Filter method

[source,java]
-----
@Override
public Collection<Event> filter(Collection<Event> events, FilterMatchListener matchListener) {
    for (Event e : events) {
        Object f = e.getField(sourceField);
        if (f instanceof String) {
            e.setField(sourceField, StringUtils.reverse((String)f));
            matchListener.filterMatched(e);            
        }
    }
    return events;
-----

Finally, we come to the `filter` method that is invoked by the Logstash
execution engine on batches of events as they flow through the event processing
pipeline. The events to be filtered are supplied in the `events` argument and
the method should return a collection of filtered events. Filters may perform a
variety of actions on events as they flow through the pipeline including:

* Mutation -- Fields in events may be added, removed, or changed by a filter. This
is the most common scenario for  filters that perform various kinds of
enrichment on events. In this scenario, the incoming `events` collection may be
returned unmodified since the events in the collection are mutated in place.

* Deletion -- Events may be removed from the event pipeline by a filter so that
subsequent filters and outputs  do not receive them. In this scenario, the
events to be deleted must be removed from the collection of filtered events
before it is returned. 

* Creation -- A filter may insert new events into the event pipeline that will be
seen only by subsequent filters and outputs. In this scenario, the new events
must be added to the collection of filtered events before it is returned.

* Observation -- Events may pass unchanged by a filter through the event pipeline.
This may be useful in scenarios where a filter performs external actions (e.g.,
updating an external cache) based on the events observed in the event pipeline.
In this scenario, the incoming `events` collection may be returned unmodified
since no changes were made.

In the example above, the value of the `source` field is retrieved from each
event and reversed if it is a string value. Because each event is mutated in
place, the incoming `events` collection can be returned.

The `matchListener` is the mechanism by which filters indicate which events
"match". The common actions for filters  such as `add_field` and `add_tag` are
applied only to events that are designated as "matching". Some filters such as
the https://www.elastic.co/guide/en/logstash/current/plugins-filters-grok.html[grok
filter]
have a clear definition  for what constitutes a matching event and will notify
the listener only for matching events. Other filters such as the 
https://www.elastic.co/guide/en/logstash/current/plugins-filters-uuid.html[UUID
filter]
have no specific match  criteria and should notify the listener for every event
filtered. In this example, the filter notifies the match listener for any event
that had a `String` value in its `source` field and was therefore able to be
reversed.

[float]
==== getId method

[source,java]
-----
@Override
public String getId() {
    return id;
}
-----

For filter plugins, the `getId` method should always return the id that was provided to the plugin through its
constructor at instantiation time.

[float]
==== Unit tests

Lastly, but certainly not least importantly, unit tests are strongly encouraged.
The example filter plugin includes an
https://github.com/logstash-plugins/logstash-filter-java_filter_example/blob/master/src/test/java/org/logstash/javaapi/JavaFilterExampleTest.java)[example
unit test] that you can use as a template for your own.


// Pulls in shared section about Packaging and Deploying
include::include/javapluginpkg.asciidoc[]

[float]
=== Run Logstash with the Java filter plugin

The following is a minimal Logstash configuration that can be used to test that
the Java filter plugin is correctly installed and functioning.
 
[source,java]
-----
input {
  generator { message => "Hello world!" count => 1 }
}
filter {
  java_filter_example {}
}
output {
  stdout { codec => rubydebug }
}
-----

Copy the above Logstash configuration to a file such as `java_filter.conf`.
Start Logstash with:

[source,shell]
-----
bin/logstash -f /path/to/java_filter.conf
-----

NOTE: The Java execution engine, the default execution engine since Logstash 7.0, is required
as Java plugins are not supported in the Ruby execution engine.

The expected Logstash output (excluding initialization) with the configuration
above is:

[source,txt]
-----
{
      "sequence" => 0,
      "@version" => "1",
       "message" => "!dlrow olleH",
    "@timestamp" => yyyy-MM-ddThh:mm:ss.SSSZ,
          "host" => "<yourHostName>"
}
-----

[float]
=== Feedback

If you have any feedback on Java plugin support in Logstash, please comment on our 
https://github.com/elastic/logstash/issues/9215[main Github issue] or post in the 
https://discuss.elastic.co/c/logstash[Logstash forum].

:pluginrepo!:
:sversion!:
:plugintypecap!:
:pluginnamecap!:
:pluginname!:
:pluginclass!:
:plugintype!:
