mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 22:57:16 -04:00
134 lines
4.8 KiB
Text
134 lines
4.8 KiB
Text
[float]
|
|
=== Package and deploy
|
|
|
|
Java plugins are packaged as Ruby gems for dependency management and
|
|
interoperability with Ruby plugins.
|
|
|
|
NOTE: One of the goals for Java plugin support is to eliminate the need for any
|
|
knowledge of Ruby or its toolchain for Java plugin development. Future phases of
|
|
the Java plugin project will automate the packaging of Java plugins as Ruby gems
|
|
so no direct knowledge of or interaction with Ruby will be required. In the
|
|
current phase, Java plugins must still be manually packaged as Ruby gems
|
|
and installed with the `logstash-plugin` utility.
|
|
|
|
[float]
|
|
==== Compile to JAR file
|
|
|
|
The Java plugin should be compiled and assembled into a fat jar with the
|
|
`vendor` task in the Gradle build file. This will package all Java dependencies
|
|
into a single jar and write it to the correct folder for later packaging into a
|
|
Ruby gem.
|
|
|
|
[float]
|
|
==== Manually package as Ruby gem
|
|
|
|
Several Ruby source files are required to package the jar file as a
|
|
Ruby gem. These Ruby files are used only at Logstash startup time to identify
|
|
the Java plugin and are not used during runtime event processing.
|
|
|
|
NOTE: These Ruby source files will be automatically generated in a future release.
|
|
|
|
**+logstash-{plugintype}-<{plugintype}-name>.gemspec+**
|
|
|
|
[source,txt]
|
|
[subs="attributes"]
|
|
-----
|
|
Gem::Specification.new do |s|
|
|
s.name = 'logstash-{plugintype}-java_{plugintype}_example'
|
|
s.version = PLUGIN_VERSION
|
|
s.licenses = ['Apache-2.0']
|
|
s.summary = "Example {plugintype} using Java plugin API"
|
|
s.description = ""
|
|
s.authors = ['Elasticsearch']
|
|
s.email = 'info@elastic.co'
|
|
s.homepage = "http://www.elastic.co/guide/en/logstash/current/index.html"
|
|
s.require_paths = ['lib', 'vendor/jar-dependencies']
|
|
|
|
# Files
|
|
s.files = Dir["lib/**/*","spec/**/*","*.gemspec","*.md","CONTRIBUTORS","Gemfile","LICENSE","NOTICE.TXT", "vendor/jar-dependencies/**/*.jar", "vendor/jar-dependencies/**/*.rb", "VERSION", "docs/**/*"]
|
|
|
|
# Special flag to let us know this is actually a logstash plugin
|
|
s.metadata = { 'logstash_plugin' => 'true', 'logstash_group' => '{plugintype}'}
|
|
|
|
# Gem dependencies
|
|
s.add_runtime_dependency "logstash-core-plugin-api", ">= 1.60", "<= 2.99"
|
|
s.add_runtime_dependency 'jar-dependencies'
|
|
|
|
s.add_development_dependency 'logstash-devutils'
|
|
end
|
|
-----
|
|
|
|
You can use this file with the following modifications:
|
|
|
|
* `s.name` must follow the +logstash-pass:attributes[{plugintype}]-<{plugintype}-name>+ pattern
|
|
* `s.version` must match the `project.version` specified in the `build.gradle` file.
|
|
Both versions should be set to be read from the `VERSION` file in this example.
|
|
|
|
**+lib/logstash/{plugintype}s/<{plugintype}-name>.rb+**
|
|
|
|
[source,ruby]
|
|
[subs="attributes"]
|
|
-----
|
|
# encoding: utf-8
|
|
require "logstash/{plugintype}s/base"
|
|
require "logstash/namespace"
|
|
require "logstash-{plugintype}-java_{plugintype}_example_jars"
|
|
require "java"
|
|
|
|
class LogStash::{plugintype}s::Java{plugintypecap}Example < LogStash::{pluginclass}::Base
|
|
config_name "java_{plugintype}_example"
|
|
|
|
def self.javaClass() org.logstash.javaapi.Java{plugintypecap}Example.java_class; end
|
|
end
|
|
-----
|
|
|
|
Modify these items in the file above:
|
|
|
|
* Change the name to correspond with the {plugintype} name.
|
|
* Change +require "logstash-{plugintype}-java_{plugintype}_example_jars"+ to reference the appropriate "jars" file
|
|
as described below.
|
|
* Change +class LogStash::{pluginclass}::Java{plugintypecap}Example < LogStash::{pluginclass}::Base+ to provide a unique and
|
|
descriptive Ruby class name.
|
|
* Change +config_name "java_{plugintype}_example"+ to match the name of the plugin as specified in the `name` property of
|
|
the `@LogstashPlugin` annotation.
|
|
* Change +def self.javaClass() org.logstash.javaapi.Java{plugintypecap}Example.java_class; end+ to return the
|
|
class of the Java {plugintype}.
|
|
|
|
**+lib/logstash-{plugintype}-<{plugintype}-name>_jars.rb+**
|
|
|
|
[source,txt]
|
|
[subs="attributes"]
|
|
-----
|
|
require 'jar_dependencies'
|
|
require_jar('org.logstash.javaapi', 'logstash-{plugintype}-java_{plugintype}_example', {sversion})
|
|
-----
|
|
|
|
In the file above:
|
|
|
|
* Rename the file to correspond to the {plugintype} name.
|
|
* Change the `require_jar` directive to correspond to the `group` specified in the
|
|
Gradle build file, the name of the {plugintype} JAR file, and the version as
|
|
specified in both the gemspec and Gradle build file.
|
|
|
|
After you have created the previous files and the plugin JAR file, build the gem using the
|
|
following command:
|
|
|
|
[source,shell]
|
|
[subs="attributes"]
|
|
-----
|
|
gem build logstash-{plugintype}-<{plugintype}-name>.gemspec
|
|
-----
|
|
|
|
[float]
|
|
==== Installing the Java plugin in Logstash
|
|
|
|
After you have packaged your Java plugin as a Ruby gem, you can install it in
|
|
Logstash with this command:
|
|
|
|
[source,shell]
|
|
-----
|
|
bin/logstash-plugin install --no-verify --local /path/to/javaPlugin.gem
|
|
-----
|
|
|
|
For Windows platforms: Substitute backslashes for forward slashes as appropriate in the command.
|
|
|