Extensions
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.
## Server ExtensionThe 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.
## WebApp ExtensionThe 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
## Options ExtensionThe 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