Skip to content
This repository

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 Extension

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.

WebApp 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

Options 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
Something went wrong with that request. Please try again.