5. Turtles Configuration Reference

5.1. Plugin Set Definition Reference

A plugin set definition looks like the following:

---
kind: PluginSet
id: <<plugin set identifier>>
name: <<plugin set display name>>
builder:
  type: <<buildertype>>
  <<...type-specific plugin set builder configuration...>>

The object is defined as follows:

kind

Type:

string

Required:

yes

The constant PluginSet, indicating a plugin set definition.

id

Type:

string

Required:

yes

An identifier for the plugin set [1]. Example: our-plugin-set.

name

Type:

string

Required:

yes

A display name for the plugin set. Example: Our Plugin Set.

builder

Type:

Plugin Set Builder Specification object

Required:

yes

A Plugin Set Builder Specification for the plugin set (see below).

5.1.1. Plugin Set Builder Specification

Because there are two types of plugin set builders, the Maven plugin set builder and the deprecated legacy Ant plugin set builder, there are two types of plugin set builder specifications, identified by their type property:

type	Name
maven	Maven Plugin Set Builder Specification
ant	Legacy Ant Plugin Set Builder Specification (deprecated)

5.1.1.1. Maven Plugin Set Builder Specification

Note

This plugin set builder has additional prerequisites. See Maven Plugin Set Builder Prerequisites.

A Maven plugin set builder specification looks like the following:

type: maven
main: src/main/java  # optional
test: src/test/java  # optional

The object is defined as follows:

type

Type:

string

Required:

yes

The constant maven, indicating a Maven plugin set builder specification. Designates a plugin set that is built using Maven with the parent POM org.lockss:lockss-plugins-parent-pom.

main

Type:

string

Required:

no

Default:

src/main/java

The path to the plugins' source code. A relative path is understood to be relative to the plugin set definition file. Optional (src/main/java by default).

test

Type:

string

Required:

no

Default:

src/test/java

The path to the plugins' unit tests. A relative path is understood to be relative to the plugin set definition file. Optional (src/test/java by default).

5.1.1.2. Legacy Ant Plugin Set Builder Specification

Warning

This plugin set builder is deprecated.

Note

This plugin set builder has additional prerequisites. See Legacy Ant Plugin Set Builder Prerequisites.

A legacy Ant plugin set builder specification looks like the following:

type: ant
main: plugins/src       # optional
test: plugins/test/src  # optional

The object is defined as follows:

type

Type:

string

Required:

yes

The constant ant, indicating a legacy Ant plugin set builder specification. Designates a plugin set that is built using Ant with the LOCKSS Program's legacy Ant build (from the LOCKSS 1.x system).

main

Type:

string

Required:

no

Default:

plugins/src

The path to the plugins' unit tests. A relative path is understood to be relative to the plugin set definition file. Optional (src/main/java by default).

test

Type:

string

Required:

no

Default:

plugins/test/src

The path to the plugins' unit tests. A relative path is understood to be relative to the plugin set definition file. Optional (plugins/test/src by default).

5.2. Plugin Set Catalog Definition Reference

A plugin set catalog definition looks like the following:

---
kind: PluginSetCatalog
plugin-set-files:
  - <<plugin set definition file path 1>>
  - <<plugin set definition file path 2>>
  - ...

The object is defined as follows:

kind

Type:

string

Required:

yes

The constant PluginSetCatalog, indicating a plugin set catalog definition.

plugin-set-files

Type:

list of strings

Required:

yes

A non-empty list of plugin set definition file paths. Paths that are relative are understood to be relative to the plugin set catalog definition file.

5.3. Plugin Registry Definition Reference

A plugin registry definition looks like the following:

---
kind: PluginRegistry
id: <<plugin registry identifier>>
name: <<plugin registry display name>>
layout:
  type: <<plugin registry layout type>>
  <<...type-specific plugin registry layout configuration...>>
layers:
  - id: <<plugin registry layer identifier>>
    name: <<plugin registry layer display name>>
    path: <<plugin registry layer directory path>>
  -  <<...other plugin registry layers...>>
plugin-identifiers:
  - org.ourproject.plugin.plugin1.Plugin1
  - org.ourproject.plugin.plugin2.Plugin2
  - <<...other plugin identifiers...>>
suppressed-plugin-identifiers:
  - org.ourproject.plugin.plugin8.Plugin8
  - org.ourproject.plugin.plugin9.Plugin9
  - <<...other plugin identifiers...>>

The object is defined as follows:

kind

Type:

string

Required:

yes

The constant PluginRegistry, indicating a plugin registry definition.

id

Type:

string

Required:

yes

An identifier for the plugin registry [1]. Example: our-plugin-registry.

name

Type:

string

Required:

yes

A display name for the plugin registry. Example: Our Plugin Registry.

layout

Type:

Plugin Registry Layout Specification object

Required:

yes

A Plugin Registry Layout Specification for this plugin registry.

layers

Type:

list of Plugin Registry Layer Specification objects

Required:

yes

A non-empty list of Plugin Registry Layer Specifications.

plugin-identifiers

Type:

list of strings

Required:

yes

A non-empty list of plugin identifiers in this plugin registry.

suppressed-plugin-identifiers

Type:

list of strings

Required:

no

An optional list of plugin identifiers that have been retired from this plugin registry. Turtles does not currently do anything actionable with this information, but it can be useful for plugin registry maintainers to document. Optional.

5.3.1. Plugin Registry Layout Specification

Turtles supports two kinds of plugin registry layouts, the directory plugin registry layout and the RCS plugin registry layout, identified by their type property:

type	Name
directory	Directory Plugin Registry Layout Specification
rcs	RCS Plugin Registry Layout Specification

5.3.1.1. Directory Plugin Registry Layout Specification

In a directory plugin registry layout, the plugin JAR files of each layer simply go together in a flat directory structure, for instance:

/var/www/props.ourproject.org/plugins/
+-- testing/
|   +-- org.ourproject.plugin.plugin1.Plugin1.jar
|   +-- org.ourproject.plugin.plugin2.Plugin2.jar
|   +-- ...
+-- production/
    +-- org.ourproject.plugin.plugin1.Plugin1.jar
    +-- org.ourproject.plugin.plugin2.Plugin2.jar
    +-- ...

A directory plugin registry layout specification looks like the following:

type: directory
file-naming-convention: identifier  # optional

The object is defined as follows:

type

Type:

string

Required:

yes

The constant directory, indicating a directory plugin registry layout.

file-naming-convention

Type:

string

Required:

no

Default:

identifier

A file naming convention for the JAR files. Optional (identifier by default). The three available file naming conventions and their effect on the plugin identifier org.ourproject.plugin.plugin1.Plugin1 are:

file-naming-convention	Effect
abbreviated	Plugin1.jar
identifier (default)	org.ourproject.plugin.plugin1.Plugin1.jar
underscore	org_ourproject_plugin_plugin1_Plugin1.jar

5.3.1.2. RCS Plugin Registry Layout Specification

Note

This plugin registry layout has additional prerequisites. See RCS Plugin Registry Layout Prerequisites.

In an RCS plugin registry layout specification, the plugin JAR files of each layer go together in a flat directory structure, just like in a directory plugin registry layout, but additionally, each layer has an RCS subdirectory and RCS is used to save a record of successive plugin versions. The resulting file structure would look like the following:

/var/www/props.ourproject.org/plugins/
+-- testing/
|   +-- RCS/
|   |   +-- org.ourproject.plugin.plugin1.Plugin1.jar,v
|   |   +-- org.ourproject.plugin.plugin2.Plugin2.jar,v
|   |   +-- ...
|   +-- org.ourproject.plugin.plugin1.Plugin1.jar
|   +-- org.ourproject.plugin.plugin2.Plugin2.jar
|   +-- ...
+-- production/
    +-- RCS/
    |   +-- org.ourproject.plugin.plugin1.Plugin1.jar,v
    |   +-- org.ourproject.plugin.plugin2.Plugin2.jar,v
    |   +-- ...
    +-- org.ourproject.plugin.plugin1.Plugin1.jar
    +-- org.ourproject.plugin.plugin2.Plugin2.jar
    +-- ...

An RCS plugin registry layout specification looks like this:

type: rcs
file-naming-convention: identifier  # optional

The object is defined as follows:

type

Type:

string

Required:

yes

The constant rcs, indicating an RCS plugin registry layout.

file-naming-convention

Type:

string

Required:

no

Default:

identifier

A file naming convention for the JAR files. Optional (identifier by default). The three available file naming conventions and their effect on the plugin identifier org.ourproject.plugin.plugin1.Plugin1 are:

file-naming-convention	Effect
abbreviated	Plugin1.jar
identifier (default)	org.ourproject.plugin.plugin1.Plugin1.jar
underscore	org_ourproject_plugin_plugin1_Plugin1.jar

5.3.2. Plugin Registry Layer Specification

A plugin registry layer specification looks like the following:

id: <<identifier>>
name: <<display name>>
path: <<directory path>>

The object is defined as follows:

id

Type:

string

Required:

yes

An identifier for the layer [1]. Examples: production, testing.

name

Type:

string

Required:

yes

A display name for the layer. Example: Our Project Plugin Registry (Production).

path

Type:

string

Required:

yes

The layer's directory path. A relative path is understood to be relative to the plugin registry definition file. Example: /var/www/props/props.ourproject.org/plugins/production (absolute), production (relative).

5.4. Plugin Registry Catalog Definition Reference

A plugin registry catalog definition looks like the following:

---
kind: PluginRegistryCatalog
plugin-registry-files:
  - <<plugin registry definition file path 1>>
  - <<plugin registry definition file path 2>>
  - ...

The object is defined as follows:

kind

Type:

string

Required:

yes

The constant PluginRegistryCatalog, indicating a plugin registry catalog.

plugin-registry-files

Type:

list of strings

Required:

yes

A non-empty list of plugin registry definition file paths. Paths that are relative are understood to be relative to the plugin registry catalog definition file.

5.5. Plugin Signing Credentials Definition Reference

A plugin signing credentials definition looks like the following:

---
kind: PluginSigningCredentials
plugin-signing-keystore: <<plugin signing keystore path>>
plugin-signing-alias: <<plugin signing keystore alias>>

The object is defined as follows:

kind

Type:

string

Required:

yes

The constant PluginSigningCredentials, indicating plugin signing credentials.

plugin-signing-keystore

Type:

string

Required:

yes

File path for a plugin signing keystore. A relative path is understood to be relative to the plugin signing credentials definition file. Example: /home/user123/secrets/user123.keystore (absolute), secrets/user123.keystore (relative).

plugin-signing-alias

Type:

string

Required:

yes

User alias within the plugin signing keystore. Example: user123.

---

Footnotes

[1]

Although Turtles does not enforce a particular syntax, the intended shape of these identifiers is that they are made of lowercase letters and digits, optionally separated by hyphens or underscores, excluding spaces and other characters/punctuation. Turtles may specify the exact syntax of identifiers in a future version.