Revision as of 12:01, 3 May 2012

Developing a gCube Maven Component

We assume familiarity with Maven concepts and terminology and notice that Maven components for gCube must satisfy the following requirements:

• their groupId must be of the following form:

org.gcube.<class>

where class identifies a functionally correlated set of components and helps a range of users (developers, administrator) to discover components in various UIs/reports used within the system and in tools. Logically, the class corresponds to the gCube class of the component's, as specified in its gCube Software Profile. However, more specific, or else cross-class groups may be agreed upon among developers. In all cases, the group should align with official Maven guidelines. By agreement, for example, components in gCube class DataAccess declare a groupId of org.gcube.data.access and those in gCube class DataTransfer declare a groupId of org.gcube.data.transfer. On the other hand, also by agreement, components in gCube class InformationSystem declare a groupId of org.gcube.informationsystem.

• they must inherit from maven-parent. This ensure and promotes compliance with project-wide requirements, from the enforcement of minimal Java and Maven versions to generation and packaging of Javadoc documentation and component sources;

• for each deployable artefact they produce (primary or secondary), they must include the Maven coordinates of the arteact in the corresponding package section of the gCube Software Profile. Specifying package dependencies in the Software Profile, on the other hand, is no longer required;

• whenever they are associated with a gCube Software Archive (SA), they must produce it as a secondary tar.gz artefact with classifier servicearchive. Note that the SA of Maven components does not need to include Javadoc documentation (as this documentation is produced and published directly as a Maven artefact);

We illustrate how these requirements can be satisfied by example, distinguishing the case of library components and service components:

Libraries

The streams library is a Maven component in gCube class DataAccess. The Maven coordinates of one of its development versions are:

	<groupId>org.gcube.data.access</groupId>
	<artifactId>streams</artifactId>
	<version>1.0.0-SNAPSHOT</version>

Its POM specifies the following Maven parent:

<parent>
 <artifactId>maven-parent</artifactId>
 <groupId>org.gcube.tools</groupId>
 <version>1.0.0</version>
 <relativePath />
</parent>

Its gCube Software profile (profile.xml) is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ID />
  <Type>Service</Type>
  <Profile>
    <Description>Embedded Domain-Specific Language for Stream Transformations</Description>
    <Class>DataAccess</Class>
    <Name>streams</Name>
     <Version>1.0.0</Version>
     <Packages>
       <Software>
         <Name>streams</Name>
         <Version>1.0.0-SNAPSHOT</Version>
         <MavenCoordinates>           <groupId>org.gcube.data.access</groupId>           <artifactId>streams</artifactId>           <version>1.0.0-SNAPSHOT</version>         </MavenCoordinates>         <Files>
           <File>streams-1.0.0-SNAPSHOT.jar</File>
         </Files>
       </Software>
     </Packages>
  </Profile>
</Resource>

Notice that:

• the profile includes a single package and this package corresponds to the main build artefact of the component;
• the whole profile and the package have usual gCube coordinates;
• the package name is aligned with the Maven artifactId of the component;
• the package version is aligned with the Maven version of the component;
• the package include MavenCoordinates that can be directly copied and pasted from the POM;
• the package points to the main artefact of the Maven build;

The alignment between profile and POM can be exploited to simplify the management of the profile across different component versions. In particular, streams uses POM variables top define its profile:

<?xml version="1.0" encoding="UTF-8"?>
<Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ID />
  <Type>Service</Type>
  <Profile>
    <Description>${description}</Description>
     <Class>DataAccess</Class>
     <Name>${artifactId}</Name>
     <Version>1.0.0</Version>
     <Packages>
       <Software>
         <Name>${artifactId}</Name>
         <Version>${version}</Version>
         <MavenCoordinates>
            <groupId>${groupId}</groupId>
            <artifactId>${artifactId}</artifactId>
             <version>${version}</version>
         </MavenCoordinates>
	 <Files>
            <File>${build.finalName}.jar</File>
         </Files>
       </Software>
     </Packages>
</Profile>
</Resource>

Note that the variables must be resolved (i.e. the profile is interpolated) before the profile can be used within the system. In particular, the main destination of the profile is the gCube Software Archive (SA) which packages the component for registration within the system.

streams is responsible for generating its own SA as part of its Maven build. This requires dedicated logic in the POM but has the advantage that:

• SA validity can be verified locally;
• no SA configurations are required in ETICS;
• the required build logic can be easily reused across components;

streams uses the Maven Assembly Plugin to generate its own SA, with an approach that makes optimal use of Maven variable interpolation in static files such as README, svnpath.txt, MAINTAINERS, changelog.xml, etc. In particular, the Assembly plugin takes care of variable interpolation in the profile and other static files. The approach is best illustrated with a reference to the [sources] of the streams library.

As we discuss below, streams has the final requirement to produce an interpolated profile during ETICS builds, outside the context of the SA. streams meets this requirement with the Maven Resources Plugin. Again, consult the [sources] of the streams library to reuse this approach.

Creating the ETICS Configurations

Maven Coordinates for most common gCube dependencies (to move in a))

gcf

<dependency>
    <groupId>org.gcube.core</groupId>
    <artifactId>gcf</artifactId>
    <version>[1.4.0-SNAPSHOT,1.5.0)</version>
    <scope>provided</scope>
</dependency>

ghn-core-runtime

<dependency>
    <groupId>org.gcube.distribution</groupId>
    <artifactId>ghn-core-runtime</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

grs2library

<dependency>
    <groupId>org.gcube.execution</groupId>
    <artifactId>grs2library</artifactId>
    <version>[1.2.0-SNAPSHOT,1.3.0)</version>
</dependency>

This sections is meant to provide operative instructions about most relevant aspects of creation of ETICS configurations for Maven-based components.

Versioning

Version field of the ETICS configuration must match the version specified for the Maven project in the pom.xml, excepting for the "-SNAPSHOT" postfix. The match will be checked during the invocation of mvn to guarantee that ETICS versions are always in sync with Maven versions.

Build Commands

• the compile target of their Build Commands must invoke Maven to build the components up to the deploy phase (e.g. mvn deploy). This allows the deployment of components into Maven repositories directly from ETICS builds

• the install target of their Build Commands must copy the gCube profile of the component in the ${prefix} directory. This allows the registration of the profile with the Software Gateway when the component is released. It remains a good practice to copy also the outcome of the compilation (usually jar files) in ${prefix} in order to include them in packages generated by ETICS

Sample build commands for a maven-based component should look like the one in the picture below:

Dependencies

The configuration must directly or indirectly depend on the ETICS configurations of all gCube components that are specified in the POM, including maven-parent. This guarantees that at build-time all dependencies requested by the pom.xml have been already compiled and installed on the Maven's local reposiotry.

Dependencies on third-party components available in Maven Central (or other Maven repository specified in the POM) do not need to be configured in ETICS (i.e. Maven repositories replace ETICS externals).

All dependencies must be declared of type dynamic and the actual version will be resolved at project level.

Example of dependencies for a Maven component:

Environment

Unlike Ant-based components, Maven components do not use the CLASSPATH variable for compile-time dependency resolution, but rely on the Maven local repository. This means that the Environment section of Maven component's configurations will be empty (unless other environment variables has to be set for other purposes).

There exist an exception, though. If the component's artifact is meant to be used as compile-time dependency by others Ant-based components, the artifact produced by the Maven build needs to be exported in the CLASSPATH to allows the Ant-based component to find it. Only in this case the Environment section will contain an entry like:

CLASSPATH: ${moduleDir}/target/artifactFilename.jar