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:
- [[Nova Ordis Utilities Version Metadata Handling|]]
The difference is that the resource file has an extension-specific name (example: "jboss-datagrid-7-extension-version") and call VersionUtilities.getVersion(<extension-specific-resource-file-name>) instead.
New Extension
- Create the project root directory under $GLD_PROJECT_HOME/extensions.
- The directory name should follow the guidelines exposed here.
- Start from the following pom.xml.
- Update the following:
- The <name>.
- groupId/artifactId/version.
- The "extension.name" property, It should follow the guidelines exposed here and ideally 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.
- Repositories, if specific repositories are necessary.
- Create the 'main' and 'release' directories.
- Initialize the 'main' module.
- Use this pom.xml sample as template.
- Create the source root (src/main/java/io/novaordis/gld/extensions/jboss/datagrid). It is important that "io.novaordis.gld.extensions." prefixes the package name.
- Create the test root (src/test/java/io/novaordis/gld/extensions/jboss/datagrid)
- Initialize the 'release' module.
- Use this pom.xml sample as template.
- 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 Name: "GLD Extension for JBoss Data Grid 7"
- 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.
Code:
- io.novaordis.gld.extensions.jboss.datagrid.JBossDatagrid7Service extends JBossDatagridServiceBase.
- 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();
log.info(version);
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 template.
Configuration:
- A reference configuration should be available as main/src/test/resources/data/reference-gld-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".