Clone this wiki locally
Trinidad allows to extend the server as well as the application context with plugins.
These plugins are packaged as gems with a naming convention: trinidad_NAME_extension e.g. "trinidad_mysql_dbpool_extension" (using underscore rather than dashes).
Writing extensions might require some amount of Tomcat (Java) knowledge, don't worry you're only write plain old Ruby code but for advanced extensions an understanding of the underlying APIs might be suitable (esp. the lifecycle interface).
There are three extension points.
The first one is the Tomcat server, that allow us to add global configuration options or even replace the server instance with our custom (most likely delegating) instance. In order to extend the server, the a class that extends
Trinidad::Extensions::ServerExtension is expected to be included within the
Trinidad::Extensions module. This class should implement a configure method accepting a single argument, as the example shows:
module Trinidad module Extensions class SampleServerExtension < ServerExtension def configure(tomcat) # ... end end end end
The tomcat argument is a helper class that allows access to the configured server instance as well as the host and the engine to be used. Besides you might add more contexts (applications) or configure existing contexts from one place. It's suitable for executing "global" code that gets executed once before the server actually starts and is not tied to any particular application. For a real-world example check the Daemon Extension.
The second type of extensions is a web application extension. In this case we're going to provide a
Trinidad::Extensions::WebAppExtension sub-class with a configure method receiving the application context e.g. :
module Trinidad module Extensions class DbpoolWebAppExtension < WebAppExtension def configure(context) # ... end end end end
Tomcat "internally" represents applications as contexts and has a class that wraps all settings and state related to a particular application called StandartContext. Most extensions to be found under the Trinidad organization are in fact web-app extension, for an example refer to one e.g. Valve Extension
The third extension point is the simplest one and provides access to the command line parser. This allows adding additional command line arguments to the
trinidad executable. You're simple extend the
OptionsExtension class and once again override the configure method that gets two arguments, the parser and the default options, so we could add more arguments to the parser and fill default options when those arguments are specified :
module Trinidad module Extensions class FooOptionsExtension < OptionsExtension def configure(parser, default_options) parser.on('--bar') do default_options[:bar] = :bar end end end end end
To enable a command line extension we'll need to load it first using the --load option that gets the extension name. Afterwards we could use the new command line options, as this example shows:
$ jruby -S trinidad --load foo --bar