View source for Creating gCube Maven components: How-To

= 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 <code>groupId</code> must be of the following form:

<pre>org.gcube.<class></pre>

: 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 [http://maven.apache.org/guides/mini/guide-naming-conventions.html guidelines]. By agreement, for example, components in gCube class <code>DataAccess</code> declare a <code>groupId</code> of <code>org.gcube.data.access</code> and those in gCube class <code>DataTransfer</code> declare a <code>groupId</code> of <code>org.gcube.data.transfer</code>. On the other hand, also by agreement, components in gCube class <code>InformationSystem</code> declare a <code>groupId</code> of <code>org.gcube.informationsystem</code>.

* their <code>groupId</code> must follow Maven conventions (e.g. avoid capital letters or punctuation other than hyphens).

* 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 <code>tar.gz</code> artefact with classifier <code>servicearchive</code>. 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 <code>streams</code> library is a Maven component in gCube class <code>DataAccess</code>. The Maven coordinates of one of its development versions are:

<source lang="xml">
	<groupId>org.gcube.data.access</groupId>
	<artifactId>streams</artifactId>
	<version>1.0.0-SNAPSHOT</version>
</source>

Its POM specifies the following Maven parent:

<source lang="xml">
<parent>
 <artifactId>maven-parent</artifactId>
 <groupId>org.gcube.tools</groupId>
 <version>1.0.0</version>
 <relativePath />
</parent>
</source>

=== Profile ===

The gCube Software profile of the library is as follows:

<source lang="xml" highlight="14-18">
<?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>
</source>

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 <code>artifactId</code> of the component;
* the package version is aligned with the Maven <code>version</code> of the component;
* the package includes <code>MavenCoordinates</code> that can be directly copied and pasted from the POM;
* the package does '''not''' specify dependencies;
* 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, <code>streams</code> uses POM variables top define its profile:

<source lang="xml">
<?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>
</source>

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.

=== Service Archive ===

<code>streams</code> 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;

<code>streams</code> uses the [http://maven.apache.org/plugins/maven-assembly-plugin Maven Assembly Plugin] to generate its own SA, with an approach that makes optimal use of Maven variable interpolation in static files such as <code>README</code>, <code>svnpath.txt</code>, <code>MAINTAINERS</code>, <code>changelog.xml</code>, etc. In particular, the <code>Assembly</code> plugin takes care of variable interpolation in the profile and other static files. The approach is best illustrated with a reference to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/data-access/streams sources]] of the <code>streams</code> library.


As we discuss [[#Creating the ETICS Configurations|below]], <code>streams</code> has the final requirement to produce an interpolated profile during ETICS builds, outside the context of the SA.
<code>streams</code> meets this requirement with the [http://maven.apache.org/plugins/maven-resources-plugin/ Maven Resources Plugin]. Again, consult the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/data-access/streams sources]] of the <code>streams</code> library to reuse this approach.

== Services ==

The <code>tree-manager</code> service is a Maven component in gCube class <code>DataAccess</code>. 

=== Project Structure ===

Differently from a library, the service is associated with a number of distinguished build artefacts:

* the service implementation (a Jar);
* the stubs automatically generated from the WSDL interfaces (a Jar);
* the archive required for deployment in gCore (a Gar);
* the archive required for registration in the system (a SA);

Producing these artefacts requires sharing a number of static and dynamic files (from profiles to WSDLs to pre-processed WSDLs). The usual Maven approach of mapping the artefacts onto different Maven projects is then genuinely difficult. It is instead more practical to use a single multi-module Maven project. The <code>tree-manager</code> uses this module structure:

<pre>
  tree-manager  (parent module)------- (produces) --- (POM only)
         |
         |----- tree-manager-service   (service impl module)------- (produces) --- jar, gar, SA
         |                       |
         |                       | (depends on)
         |                       |
         |                      \/
         |----- tree-manager-stubs     (service stubs module)------- (produces) --- jar
</pre>

As customary, the parent does not produce any artefact (is a POM-only project). It  declares these coordinates in its POM:

<source lang="xml">
<groupId>org.gcube.data.access</groupId>
<artifactId>tree-manager</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
</source>

The parent physically includes the sub-modules;

<source lang="xml">
<modules>
  <module>tree-manager-stubs</module>
  <module>tree-manager-service</module>
</modules>
</source> 

Finally, the parent inherits from '''maven-parent''':

<source lang="xml">
<parent>
 <artifactId>maven-parent</artifactId>
 <groupId>org.gcube.tools</groupId>
 <version>1.0.0</version>
 <relativePath />
</parent>
</source>

The submodules inherit from the parent:

<source lang="xml">
<parent>
  <artifactId>tree-manager</artifactId>
  <groupId>org.gcube.data.access</groupId>
  <version>1.0.0-SNAPSHOT</version>
  <relativePath>..</relativePath>
</parent>
</source>

and share its <code>version</code> and <code>groupId</code>. Their coordinates are then minimal:

<source lang="xml">
<artifactId>tree-manager-service</artifactId>
</source>

<source lang="xml">
<artifactId>tree-manager-stubs</artifactId>
</source>

The <code>tree-manager-service</code> module produces a Jar of its own implementation, as well the GAR and the SA of the whole services as secondary artefacts with classifiers of, respectively, <code>gar</code> and <code>service archive</code>.

The <code>tree-manager-stubs</code> module produces a Jar of its own implementation.

Finally, the parent module coordinates the build of its sub-modules and centralises the declaration of common dependencies and configuration. Refer to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/data-access/tree-manager project sources]] to reuse this approach.

=== Generating Stubs and Gars ===

The <code>tree-manager-stubs</code> uses the '''gCube Service Plugin''' to generate its classes from WSDL interfaces. 

Similarly, the <code>tree-manager-service</code> uses the plugin to generate its secondary GAR artefact. 

The configuration of the plugin is conveniently shared in the parent module.

Refer to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/data-access/tree-manager project sources]] of the <code>streams</code> for details.

=== Profile ===

The gCube Software profile (<code>profile.xml</code>) of a development version of the service is as follows:

<source lang="xml" highlight="13-17,32-36">
<?xml version="1.0" encoding="UTF-8"?>
<Resource>
	<ID></ID>
	<Type>Service</Type>
	<Profile>
		<Class>DataAccess</Class>
		<Name>tree-manager-service</Name>
		<Version>1.0.0</Version>
		<Packages>
			<Main>
				<Name>tree-manager-service</Name>
				<Version>1.0.0</Version>
				<MavenCoordinates>
					<groupId>org.gcube.data.access</groupId>
					<artifactId>tree-manager-service</artifactId>
					<version>1.0.0-SNAPSHOT</version>
				</MavenCoordinates>
				<GARArchive>tree-manager-service-1.0.0-SNAPSHOT.gar</GARArchive>
				<PortType>
					<Name>gcube/data/tm/binder</Name>
				</PortType>
				<PortType>
					<Name>gcube/data/tm/reader</Name>
				</PortType>
				<PortType>
					<Name>gcube/data/tm/writer</Name>
				</PortType>
			</Main>
			<Software>
				<Name>tree-manager-stubs</Name>
				<Version>1.0.0</Version>
				<MavenCoordinates>
					<groupId>org.gcube.data.access</groupId>
					<artifactId>tree-manager-stubs</artifactId>
					<version>1.0.0-SNAPSHOT</version>
				</MavenCoordinates>
				<Type>library</Type>
				<Files>
					<File>tree-manager-stubs-1.0.0-SNAPSHOT.jar</File>
				</Files>
			</Software>
		</Packages>
	</Profile>
</Resource>
</source>

Notice that:

* the profile includes two packages and this package corresponds to the main build artefacts of the submodules; 
* the whole profile and the packages have usual gCube coordinates;
* package names are aligned with the Maven <code>artifactId</code>s of the submodules;
* package versions are aligned with the Maven <code>version</code>s of the submodules;
* package include <code>MavenCoordinates</code>s that can be directly copied and pasted from the POM of the submodules;
* packages do '''not''' specify dependencies;
* packages points to the main artefact of the Maven build of the submodules;

Notice that, unlike libraries, services cannot easily use Maven variables in their profiles (as these artefacts are used for different purposes by different modules). Accordingly, developers needs to maintain versions used in profiles across releases. In particular, they need to:

* replace SNAPSHOT versions with release versions in release branches;
* advance SNAPSHOT versions in HEAD;

=== Service Archive ===

<code>tree-manager-service</code> generates the service SA as part of its Maven build. This requires dedicated logic in the POM of the module and its parent.

As shown for [[#Libraries|libraries]], the service uses the [http://maven.apache.org/plugins/maven-assembly-plugin Maven Assembly Plugin] to generate its own SA, with an approach that makes optimal use of Maven variable interpolation in static files such as <code>README</code>, <code>svnpath.txt</code>, <code>MAINTAINERS</code>, <code>changelog.xml</code>, etc. In particular, the <code>Assembly</code> plugin takes care of variable interpolation for these files. Refer to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/data-access/tree-manager project sources]] for details.


== Portlets ==

The <code>sample-portlet</code> portlet is a Maven based sample portlet based on GWT. Refer to the [http://svn.d4science.research-infrastructures.eu/gcube/trunk/portal/maven-sample-portlet project sources] for details.

=== Project Structure ===

As for a library project, the portlet  is associated with 2  distinguished build artefacts:

* the archive required for deployment in a Liferay Container (a WAR);
* the archive required for registration in the system (a SA);

In order to generate automatically the project structure and the base pom, we start by customizing the maven archetype liferay-portlet-archetype v. 6.0.6.

The generation of the project structure and the pom can be performed either from Eclipse ( by using  the m2eclipse plugin) or by command line using the Maven SDK.

On Eclipse the following steps must be followed:

* FIle -> New -> Project
* From the wizard select Maven->Maven Project
* From the Select Archetype step, Select 'All Catalogs' from the Catalogs combobox and type 'portlet' on the Filter field.
* Select the '''liferay-portlet-archetype''' version 6.0.6 archetype ( if does not appear on the list just unselect 'show the last version of the Archetype only")
* In the next step you have to provide Maven coordinates for your project
* groupid : <your group id> e.g org.gcube.portlets.admin
* artifactId : <your artifactId> e.g. sample-admin-portlet
* version : <your project version> e.g. 1.0.0-SNAPSHOT ( use always SNAPSHOT versions for development versions of a project)
* package: <your portlet code package> e.g. org.gcube.portlets.admin.sample

while from shell the following mvn command should be issued :

<pre>
mvn archetype:generate \
    -DarchetypeArtifactId=liferay-theme-archetype \
    -DarchetypeGroupId=com.liferay.maven.archetypes \
    -DarchetypeVersion=6.0.6 \
    -DartifactId=<your artifactId> \
    -DgroupId=<your group id> \
    -Dversion=1.0.0-SNAPSHOT
</pre>

Both approaches generate a project structure similar to the picture below:

[[image:sample-portlet-project.png|Sample portlet project structure]]

In order to customize the build procedure to the gCube needs  we should open the pom.xml and apply the following changes:

Configure the inheritance  from '''maven-parent''' :

<source lang="xml">
<parent>
 <artifactId>maven-parent</artifactId>
 <groupId>org.gcube.tools</groupId>
 <version>1.0.0</version>
 <relativePath />
</parent>
</source>

Configure some project properties:

<source lang="xml">
<properties>
	<liferay.version>6.0.6</liferay.version>
	<liferay.auto.deploy.dir>${system.CATALINA_HOME}/../deploy</liferay.auto.deploy.dir>
	<distroDirectory>${project.basedir}/distro</distroDirectory>
	<configDirectory>${project.basedir}/config</configDirectory>
</properties>
</source>

Add the plugin for the generation of the SA, which has to be included under the build plugins section:

<source lang="xml">
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-assembly-plugin</artifactId>
	<version>2.2</version>
	<configuration>
            <descriptors>
	        <descriptor>${distroDirectory}/descriptor.xml</descriptor>
	   </descriptors>
	</configuration>
	<executions>
		<execution>
			<id>servicearchive</id>
			<phase>install</phase>
			<goals>
		          <goal>single</goal>
		       </goals>
		</execution>
	</executions>
</plugin>
</source>

In the case of a GWT portlet the [http://mojo.codehaus.org/gwt-maven-plugin gwt-maven-plugin] should also be configured ( within build plugins section as well), by also selecting the proper gwt version ( in our example 2.4)

<source lang="xml">
<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>gwt-maven-plugin</artifactId>
   <version>${gwt.version}</version>
   <executions>
	<execution>
         <goals>
	    <goal>compile</goal>
        </goals>
      </execution>
  </executions>
</plugin>
</source>


The proper GWT version should be added to the pom properties :

<source lang="xml">
<gwt.version>2.4.0</gwt.version>
</source>

and GWT dependencies should be also configured:

<source lang="xml">
<dependency>
            <groupId>com.google.gwt</groupId>
            <artifactId>gwt-user</artifactId>
            <version>${gwt.version}</version>
</dependency>
 <dependency>
            <groupId>com.google.gwt</groupId>
            <artifactId>gwt-dev</artifactId>
            <version>${gwt.version}</version>
</dependency>
<dependency>
            <groupId>com.google.gwt</groupId>
            <artifactId>gwt-servlet</artifactId>
            <version>${gwt.version}</version>
            <scope>provided</scope>
</dependency>
</source>




Please note as well that for GWT portlets the gwt.xml configuration files should be included under the ''src/main/resources''' folder. 

Refer to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/portal/maven-sample-portlet/ project sources]]  for further details on the project configuration.

=== Generating Artifacts ===

The <code>sample-portlet</code> uses the '''maven-compiler-plugin''' to compile the portlet code and the  '''gwt-maven-plugin''' as well for GWT compilation.

The generation of a war package can be triggered by typing :

<pre>
mvn package 
</pre>

on your shell or running this build task within Eclipse.

In both cases the war package will be generated under the ''target''  folder, e.g.:

<pre>
target/sample-admin-portlet-1.0.0-SNAPSHOT.war
</pre>

The generation of  all project artifacts ( war, source jar, javadoc, SA) can be triggered by the build task :

<pre>
mvn install 
</pre>

this will install as well all artifacts in your local repository, while the deployment of the artifacts to the remote gCube Maven repos can triggered by the build task:

<pre>
mvn deploy 
</pre>

=== Portlet dependencies ===

Specific portlet dependencies ( e.g. GWT, service stubs ) should be packaged within the portlet war. All dependencies specified within the pom file without the ''provided'' scope will be copied inside the WEB-INF/lib folder at packaging time.

For this reason all portlet specific dependencies should not specified that scope e.g:

<source lang="xml">
<dependency>
	<groupId>org.gcube.externals</groupId>
	<artifactId>gwt-ext-patched</artifactId>
	<version>2.0.5</version>
</dependency>
</source>

On the other hand the system dependencies ( the one contained within the [[GCube_Portal_Installation#Portal_Bundle_Libraries|Portal bundle]] ) should not be included inside the portlet war. As said in this case the ''provided'' scope should be specified, e.g.

<source lang="xml">
<dependency>
	<groupId>org.gcube.portal</groupId>
	<artifactId>custom-portal-handler</artifactId>
	<version>1.1.0-SNAPSHOT</version>
	<scope>provided</scope>
</dependency>
<dependency>
	<groupId>org.gcube.core</groupId>
	<artifactId>gcf</artifactId>
	<version>[1.4.0,1.5.0]</version>
	<scope>provided</scope>
</dependency>
</source>

=== Profile ===

The gCube Software profile (<code>profile.xml</code>) of a development version of the portlet is as follows:

<source lang="xml" highlight="13-17,32-36">
<?xml version="1.0" encoding="UTF-8"?>
<Resource>
	<ID></ID>
	<Type>Service</Type>
	<Profile>
		<Class>PortletAdmin</Class>
		<Name>sample-admin-portlet</Name>
		<Version>1.0.0</Version>
		<Packages>
			<Software>
				<Name>sample-admin-portlet</Name>
				<Version>1.0.0</Version>
				<MavenCoordinates>
					<groupId>org.gcube.portles.admin</groupId>
					<artifactId>sample-admin-portlet</artifactId>
					<version>1.0.0-SNAPSHOT</version>
				</MavenCoordinates>
                                <InstallScripts>
					<File>installPortlet.sh</File>
				</InstallScripts>
				<Files>
					<File>target/sample-admin-portlet-1.0.0-SNAPSHOT.war</File>
				</Files>
			</Software>
		</Packages>
	</Profile>
</Resource>
</source>

Notice that:

* the whole profile and the packages have usual gCube coordinates;
* package names are aligned with the Maven <code>artifactId</code> of the project;
* package versions are aligned with the Maven <code>version</code> of the project;
* package include <code>MavenCoordinates</code> that can be directly copied and pasted from the POM of the project;
* packages do '''not''' specify dependencies;

The alignment between profile and POM can be exploited to simplify the management of the profile across different component versions.
In particular, <code>sample-portlet</code> uses POM variables top define its profile:

<source lang="xml">
<?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>PortletAdmin</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>
         <InstallScripts>
	     <File>installPortlet.sh</File>
	</InstallScripts>
	 <Files>
            <File>target/${build.finalName}.war</File>
         </Files>
       </Software>
     </Packages>
</Profile>
</Resource>
</source>

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.

=== Service Archive ===

<code>sample-portlet</code> generates the service SA as part of its Maven build. This requires dedicated logic in the POM of the project.

As shown for [[#Libraries|libraries]], the portlet uses the [http://maven.apache.org/plugins/maven-assembly-plugin Maven Assembly Plugin] to generate its own SA, with an approach that makes optimal use of Maven variable interpolation in static files such as <code>README</code>, <code>svnpath.txt</code>, <code>MAINTAINERS</code>, <code>changelog.xml</code>, etc. In particular, the <code>Assembly</code> plugin takes care of variable interpolation for these files. Refer to the [[http://svn.d4science.research-infrastructures.eu/gcube/trunk/portal/maven-sample-portlet project sources]] for details.

== Dependencies ==

Service and libraries that depend on other gCube components (Maven-based or Ant-based) can find them in the gCube Maven Repositories: <code>gcube-snapshots</code> and <code>gcube-releases</code>. 

=== Repositories ===

As a one-off task, developers must configure these repositories in the <code>~/.m2/settings.xml</code> file of their local Maven installation, as follows:

<source lang="xml">
<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

	<servers>
		<server>
			<id>gcube-snapshots</id>
			<username>gcube-user</username>
			<password>maven</password>
		</server>
	</servers>
	

	<profiles>
		<profile>
			<id>gcube</id>
			<repositories>
				<repository>
					<id>gcube-snapshots</id>
					<name>gCube Snapshots</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-snapshots</url>
					<releases>
						<enabled>false</enabled>
					</releases>
					<snapshots>
						<enabled>true</enabled>
					</snapshots>
				</repository>
				<repository>
					<id>gcube-releases</id>
					<name>gCube Releases</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-releases</url>
					<snapshots>
						<enabled>false</enabled>
					</snapshots>
					<releases>
						<enabled>true</enabled>
					</releases>
				</repository>
				<repository>
					<id>gcube-externals</id>
					<name>gCube Externals</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-externals</url>
					<snapshots>
						<enabled>false</enabled>
					</snapshots>
					<releases>
						<enabled>true</enabled>
					</releases>
				</repository>
			</repositories>

			<pluginRepositories>
				<pluginRepository>
					<id>gcube-snapshots</id>
					<name>gCube Snapshots</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-snapshots</url>
					<releases>
						<enabled>false</enabled>
					</releases>
					<snapshots>
						<enabled>true</enabled>
					</snapshots>
				</pluginRepository>
				<pluginRepository>
					<id>gcube-releases</id>
					<name>gCube Releases</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-releases</url>
					<snapshots>
						<enabled>false</enabled>
					</snapshots>
					<releases>
						<enabled>true</enabled>
					</releases>
				</pluginRepository>
				<pluginRepository>
					<id>gcube-externals</id>
					<name>gCube Externals</name>
					<url>http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-externals</url>
					<snapshots>
						<enabled>false</enabled>
					</snapshots>
					<releases>
						<enabled>true</enabled>
					</releases>
				</pluginRepository>
			</pluginRepositories>
			
		</profile>
	</profiles>

	<activeProfiles>
		<activeProfile>gcube</activeProfile>
	</activeProfiles>
</settings>
</source>


'''Note:Developers must not configure these repositories in their POMs''', only in <code>settings.xml</code>. 

This is to:
* keep their projects independent from future changes in repository locations; 
* avoid interference with ETICS builds, where access to these repositories may comprise correct system integration;

=== Third Party external Repositories ===

Using the the <code>settings.xml</code> aforementioned, any dependency declared in pom.xml that can be found in one of gCube repositories or in Maven Central will be resolved at build time and deployment time without any further configuration. Frequently it may happens that a gCube component needs software stored on a public Maven repository not in on of those repositories. In this case, Maven provides an easy solution for declaring additional repositories for dependency resolution by adding a <repositories> section in the pom.xml of the project. E.g.:

<source lang="xml" highlight="3,4">
<repositories>
    <repository>
    	<id>[repository-id]</id>
    	<url>[repository URL]</url>
    </repository>
</repositories>
</source>

Though technically possible to add any Maven repository in this way, in order to preserve the quality of gCube software it is required to check trustworthiness of its dependencies disallowing usage of certain external software. To enforce such a control over public Maven repositories, '''gCube components are allowed to use external repository not directly but only through a proxy repository''' (a.k.a. shadow repository) created on CNR's Nexus Repository Portal (http://maven.research-infrastructures.eu/nexus/).

List of all repositories in Nexus Portal is available at http://maven.research-infrastructures.eu/nexus/index.html#view-repositories

'''Note''': if a component uses a public Maven repository directly, it will work for building but would fail in deployment phase. In fact, Software Gateway is only able to download software accessible from Nexus.

==== How to request creation of a new proxy repository in Nexus ====
Proxy Repositories on Nexus are created by the Release Manager. To request a new proxy a new ticket must be created.

Details of ticket are:
#  open a ticket of type "Task" in iMarine TRAC (at https://issue.imarine.research-infrastructures.eu/)
# ticket's '''description''' must report:
#* URL of repository to add
#* organization which hosts the repository
#* which artifacts are needed from that repository
# '''Type''' is ''Task''
# '''Milestone''' field should be set to the gCube release in which the component is expected to be released 
# '''Component''' field must report the gCube component that needs the external repository
# '''Blocking''' should list (if any) other tickets blocked by the addition of this Maven repository 
# '''Task Category''' is ''software''
# assign the ticket to the Release Manager

An example of ticket for requesting a new repository mirror is reported in the figure below.
[[Image:New_maven_mirror_repo.png|600px|center|Ticket for requesting a new Mirror Repository]]

Release Manager will process the ticket checking that no issues are foreseen from the usage of software stored in the repository. If request is accepted, a new proxy repository is created and the repository's URL will be communicated publicly on gCube's developers mailinglist (a.k.a. TCOM mailinglist).

Knowing the mirror repository URL, developer can use it adding following lines in pom.xml. E.g.

<source lang="xml" highlight="3,4">
<repositories>
    <repository>
    	<id>gcube-ext-osgeo</id>
    	<url>http://maven.research-infrastructures.eu/nexus/content/repositories/osgeo/</url>
    </repository>
</repositories>
</source>

'''Note''': it is possible that software stored on proxy repositories is not included in search results on Nexus. This happens for those repositories that does not have indexes (or have indexes in a format that Nexus is not able to download). Anyway, once Nexus has downloaded artifacts from the original repository for the first time (e.g. because a compilation of a pom that uses the proxy repository), creates its own indexes and those artifacts will become available also for local search.

=== Dependency Versions ===

ETICS builds ensure correct integration of gCube components, regardless of the versions their dependencies. It also ensures that components are released with fixed versions for their dependencies, i.e. ensures build reproducibility.

Accordingly, developers can be liberal in the choice of dependency versions.  i.e. rely on version ranges to:

* minimise the requirements for version management;
* be readily informed of any mis-alignment with their dependencies;

As we start adopting Maven, the lower-bound of version ranges will be a SNAPSHOT version. For example, a dependency on the <code>streams</code> library can be specified as follows:

<source lang="xml">
<dependency>
    <groupId>org.gcube.data.access</groupId>
    <artifactId>streams</artifactId>
    <version>[1.0.0-SNAPSHOT,2.0.0)</version>
</dependency>
</source>

With this dependency, a component will be soon notified of  a non-retro compatible change that, contrary to conventions, <code>streams</code> may have introduced in, say, version <code>1.3.0</code> (typically the day after at the latest). The notification will be delivered in the IDE, assuming the availability of Maven integration (e.g. <code>m2e</code> in Eclipse).   
The component is in fact free to open the range further if it wants to be aligned with its dependencies across major versions.

=== Common Dependencies ===

Many gCube components depend on <code>gcf</code>, which is now available as a Maven component since version <code>1.4</code>. At the time of writing, the component has not been released yet. A dependency on it is then specified as follows:

<source lang="xml">
<dependency>
    <groupId>org.gcube.core</groupId>
    <artifactId>gcf</artifactId>
    <version>[1.4.0-SNAPSHOT,2.0.0)</version>
    <scope>provided</scope>
</dependency>
</source>

The scope <code>provided</code> indicates that these dependency will be satisfied in the development environment (the gHN) and should not be included in GAR and SA archives.

Some components depend on the libraries available in all gHNs, though they do not depend on <code>gcf</code> itself. The subset of these libraries that are required for compilation and integration testing have been coalesced in a single Jar, distributed as a Maven component called <code>ghn-core-runtime</code>. A dependency on this Jar can be specified as follows:

<source lang="xml">
<dependency>
    <groupId>org.gcube.distribution</groupId>
    <artifactId>ghn-core-runtime</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>
</source>

Note: a component that depends on <code>gcf</code> indirectly depends on <code>gun-core-runtime</code>.

Another common dependency is on the gCube gRS2, an Ant component that the build infrastructure make available in Maven repositories. A dependency on this component can be specified as follows:

<source lang="xml">
<dependency>
    <groupId>org.gcube.execution</groupId>
    <artifactId>grs2library</artifactId>
    <version>[1.2.0-SNAPSHOT,2.0.0)</version>
</dependency>
</source>

= Creating the ETICS Configurations =

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. <code>mvn deploy</code>). 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 <code>${prefix}</code>''' 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 <code>${prefix}</code> 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:

[[Image:maven-component-configuration.png|600px|center|Example of maven-component's build commands]]

== 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:
[[Image:Maven-deps.png|700px|center|Example of maven-component's dependency set]]

== Environment ==
Unlike Ant-based components, Maven components do not use the <code>CLASSPATH</code> 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 to add to CLASSPATH the artifact produced. It is suggested to use following convention:
<pre>
CLASSPATH: ${moduleDir}/target/<artifactid>-${version}[-SNAPSHOT].jar
</pre>
where:
* <artifactId> must be replaced with the name of the artifact produced by Maven compilation. By default it is the same of <artifactId> value in the pom
* -SNAPSHOT must be added only if you are setting up a configuration for org.gcube.HEAD
* ${moduleDir} and ${version} are ETICS properties and will be resolved by ETICS itself

Valid examples of CLASSPATH:
<pre>
CLASSPATH: ${moduleDir}/target/home-library-${version}.jar
CLASSPATH: ${moduleDir}/target/home-library-${version}-SNAPSHOT.jar
CLASSPATH: ${moduleDir}/SoftwareGateway-stubs/target/softwaregateway-stubs-${version}.jar
CLASSPATH: ${moduleDir}/SoftwareGateway-stubs/target/softwaregateway-stubs-${version}-SNAPSHOT.jar		
...
</pre>

'''Tip''': you can easily find exactly which artifact is created during an ETICS build by searching in the build report of the component for the line "''Installing /home/gbuilder/catalogueoflife-spd-plugin/<span style="background-color:#E6E6FA">target/catalogue-of-life-spd-plugin-1.0.0.jar</span> to...''"