Gld Extension Development

Internal

• gld Development

Overview

Extensions are developed independently of the core, which includes the GLD API, shipped as gld-api-*.jar and the load driver, shipped as gld-load-driver-*.jar. Once a new core version has been released, the extensions that wish to use it should update their

<gld.api.version>...</gld.api.version> 

in the topmost POM of the extension.

To get to the work area of an extension:

cd projects/gld/extensions/<extension-name>
release snapshot

The above will build the extension and install it in $RUNTIME_DIR/gld/extensions. For more details about the release process, see The Release Process below.

Maven Coordinates

Group ID:

io.novaordis.gld.extensions.simplified-extension-name

Example:

io.novaordis.gld.extensions.jboss-datagrid

There is no target product version information in the Group ID, the version information goes into the artifact ID, if necessary.

Artifact IDs examples:

JBoss Data Grid:

• jboss-datagrid-common
• jboss-datagrid-6
• jboss-datagrid-7

JBoss JMS Providers (the common JMS library's place is taken by the JMS API):

• jboss-eap-7-jms

Extension Name

The extension name should follow guidelines described in:

gld Concepts - Extension Name

Once established, the extension name must be specified as the "extension.name" property in the extension project topmost POM:

<project ...>
    ...
    <properties>

        <!--
            The official extension name
        -->
        <extension.name>jboss-datagrid-7</extension.name>

        ...
    </properties>
   ...
</project>

The POM "extension.name" property is the authoritative source of information for extension name. The system property will be used everywhere the extension name is required.

Extension Project Home Directory

For consistency, it is recommended that the extension home directory - the top-level directory of the extension project - has the same name as "extension.name" system property value.

Extension Version

Use a variant of the procedure described here:

Nova Ordis Utilities Version Metadata Handling

The difference is that the resource file has an extension-specific name (example: "jboss-datagrid-7-extension-version").

To get the version information, call

VersionUtilities.getVersion(<extension-specific-resource-file-name>)

instead.

New Extension Procedure

New Extension Infrastructure

• Create the project root directory under $GLD_PROJECT_HOME/extensions.
• The directory name should follow the guidelines provided in the "Extension Project Home Directory" section, above.
• Start from the following pom.xml or from the closest working extension POM and update the following:
  • <name>
  • groupId/artifactId/version according to the details presented in section "Maven Coordinates".
  • The "extension.name" property, It should follow the guidelines exposed in the "Extension Name" section. Ideally, it should be identical with the name of the project root directory.
  • Various dependency versions, including the "common" module, shared by the extensions corresponding to different versions of the target service. jboss-datagrid-* use a common module. For the extensions that do not need a "common" module and rely directly on the GLD API, declared a direct dependency on GLD API. jboss-eap-*-jms do not use a common module.
• Create the 'main' and 'release' directories.
• Initialize the 'main' module.
  • Use this pom.xml sample as template, or the closest working extension main module POM.
  • Create the source and the test root. It is important that "io.novaordis.gld.extensions." prefixes the package name:

cd main
mkdir -p src/main/java/io/novaordis/gld/extensions/jboss/eap/jms
mkdir -p src/test/java/io/novaordis/gld/extensions/jboss/eap/jms

• Initialize the 'release' module.
  • Use this pom.xml sample as template, or the closest working extension release module POM.
  • Initialize src/assembly/release.xml using the sample available here: release.xml.
• Convenience aliases (cdgldjdg7)
• Create the IntelliJ IDEA project:
  • The root of the project should be the project directory name. There will be an independent IntelliJ IDEA project per extension.
  • Project Names:
    • "GLD Extension for JBoss Data Grid 7"
    • "GLD Extension for JBoss EAP 7 JMS"
    • "GLD Extension for JBoss EAP 6 JMS"

• Release infrastructure:
  • version metadata file: main/src/main/resources/jboss-datagrid-7-extension-version, with the following content: version=${project.version}
  • release/src/main/bash/.install. Template available here: .install
  • .nort/project.yml

New Extension Code

Service code examples:

• io.novaordis.gld.extensions.jboss.datagrid.JBossDatagrid7Service extends JBossDatagridServiceBase.
• io.novaordis.gld.extensions.jboss.eap.jms. JBossEap7JmsService extends JmsServiceBase.

Extension version reporting: the Service implementation must override getVesion() as follows:

@Override
public String getVersion() {
       return VersionUtilities.getVersion(EXTENSION_VERSION_METADATA_FILE_NAME);
}

where EXTENSION_VERSION_METADATA_FILE_NAME contains the name of the version metadata file mentioned above.

Also the service test class should contain the following:

@Test
public void version() throws Exception {

    JBossDatagrid7Service s = new JBossDatagrid7Service();

    String version = s.getVersion();

    assertNotNull(version);

    String mavenInjectedProjectVersion = System.getProperty("maven.injected.project.version");
    assertNotNull(mavenInjectedProjectVersion);
    assertEquals(mavenInjectedProjectVersion, version);
}

"maven.injected.project.version" should be injected by Maven, if we used the correct pom.xml top-level project template. The system property is set by the maven-surefire-plugin task.

Configuration

A reference configuration should be available as main/src/test/resources/data/reference-jboss-datagrid-7.yml

Service Implementation Class Naming Conventions

As per gld 1.0, the Service implementation class must adhere to naming convention described below. In the future, we plan to relax this requirement.

The extension name dictates the Service implementation class name.

If the extension name is "alpha-beta-gamma", where any of the components, except the first one, can be entirely numeric, then the service implementation class name must be: "io.novaordis.gld.extensions.alpha.beta.gamma.AlphaBetaGammaService". The components that are entirely numeric are dropped from the package name. The logic is implemented here (extensionNameToExtensionServiceFullyQualifiedClassName() method):

https://github.com/NovaOrdis/gld/blob/master/core/api/src/main/java/io/novaordis/gld/api/service/ServiceFactory.java

The Release Process

An extension source tree is completely independent of core. The only relationship is the API version specified in the extension's POM file.

The release process should be as simple as:

release snapshot|minor|...

nort will install the extension into the local gld deployment. The location of the installation directory can be configured in <extension-name>/.nort/project.yml, as "install/installation.directory".

Smoke Tests

• JBoss Data Grid 6 Extension Smoke Test
• JBoss Data Grid 7 Extension Smoke Test
• EAP 7 JMS Extension Smoke Test
• EAP 6 JMS Extension Smoke Test