Gld Extension Development
Internal
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:
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:
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):
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".