Starting a startable plugin

A startable plugin begins executing when a specified server run level is reached during server startup. The server run level is specified in the @Availability annotation on the plugin’s class declaration. The annotation accepts an argument of type AvailabilityLevel which specifies the server run level, such as DAEMONS or MULTIUSER. The @Availability annotation is applicable for startable plugins only. Other types of plugins are executed when they are invoked by application code and are independent of the server run level.

By default, a Distributed startable plugin begins executing when the server reaches the NODAEMONS server run level, also called the maintenance system run level. To start the plugin at a different run level, use the @Availability annotation. A Distributed startable plugin can begin executing at any server run level.

A Singleton startable plugin must explicitly specify its server run level in an @Availability annotation. A Singleton startable plugin can begin executing at either the DAEMONS or MULTIUSER server run levels.

The following example code defines a Singleton startable plugin that begins executing at the MULTIUSER run level.

uses gw.api.server.Availability
uses gw.api.server.AvailabilityLevel

@Availability(AvailabilityLevel.MULTIUSER)
class HelloWorldStartablePlugin implements IStartablePlugin {
  ...
}

Whenever a Singleton plugin is started on a server that is not clustered, the plugin is started synchronously when the relevant server run level is reached. A Singleton plugin on a clustered server is started asynchronously, which results in the possibility that the plugin will start slightly after the relevant server run level is reached.

For a startable plugin running on a clustered server, certain events, such as a load balancing request or a failure, can cause it to be spontaneously moved around the cluster. During this time, the plugin can become temporarily unavailable.

Initializing a startable plugin

To initialize a startable plugin, the following plugin methods are called.

  • construct – Constructor called when the plugin object is created
  • start – Called to set up the plugin for subsequent execution. The start method contains an execute callback method which performs the actual plugin operations.

The initialization methods set up the plugin for its subsequent operations which are performed in the execute callback method. The initialization methods must not throw an exception. If exception-throwing initialization code is required then best practice locates such code in the execute callback method.

Registering startable plugins

Register your startable plugin implementation in the Plugins Registry in Studio, similar to how you register standard plugin implementations. In the Project window, navigate to configuration > config > Plugins > registry. Right-click on registry, and select New > Plugin.

In the application user interface, all registered startable plugin implementations are listed on the Server Tools > Startable Services page.

If the plugin’s Disabled checkbox is selected in Studio, the plugin is never started and never appears in the Startable Services user interface.

Manually starting and stopping a startable plugin

If you have administration privileges, you can view the operational status of registered startable plugins on the Server Tools > Startable Services page. In the Action column, use the Start and Stop buttons to start and stop the service that a startable plugin provides. You can modify the PCF files for the Startable Services page to show additional information about your startable plugins, their underlying transport mechanisms, or any other information.

If a server running a startable plugin is terminated in a nonstandard manner then the resources associated with the plugin may not be appropriately released. Examples of nonstandard server terminations include power outages and forcible terminations.

See also