Using Maven

Introduction

The development under Lutece, including the construction and assembly of components, is based on the Apache Maven tool. The very large modularity of Lutece necessarily generates a complexity related to the assembly of components and the management of dependencies. This complexity is managed by the model proposed by Maven through the Project Object Model (POM). In order to make the most of this tool, a specific plugin for Lutece has been created to handle complex construction and assembly tasks.

The Lutece plugin for Maven

The Lutece Maven plugin is used to frame the development and distribution tasks of Lutèce and its plugins. It also allows to prepare websites by "assembling" a version of the Lutèce Core and a number of plugins.

The goals

The Lutece plugin for Maven introduces the following goals :

Creation of a test webapp

Mono-project webapp

To manually test the developed plugin in a Lutece webapp, use the goal lutece:exploded :

$ mvn lutece:exploded

This will :

• recover the lutece-core artifact from the Maven repository.
• install and prepare the version of the core in target/lutece folder.
• copy plugin-specific components to this prepared folder.
• copy all the specified configuration files (see this page).

Following this process, the target/lutece folder contains an instance of Lutece with your plugin installed.

Multi-project webapp

When the current developments concern several components, building a test webapp requires recovering these components locally. This can be done in two ways :

• By placing the components in the local Maven depot.
• By using a multi-module parent project with these components as modules.

Using the local maven repository

A component can be pushed into the local Maven repository by invoking the maven install phase :

$ mvn install

Once the command executed the new version of the component will be available for the construction of webapp with the goals of the plugin Lutèce Maven (lutece:exploded or lutece:site-assembly).

Using a multi-module project

See How lutece-maven-plugin works part Using the Maven Reactor (multi module) for how to use a multi-module project with the Lutèce Maven plugin.

Creation of distribution

Generating a plugin distribution

$ mvn lutece:assembly

This command will generate two archives :

• a ZIP containing the sources of the plugin
• a ZIP containing a binary version of the plugin that can be pasted on an existing webapp (the plugin must be activated in the administration interface)

Generation of a distribution of the Core

$ mvn lutece:assembly

This command will generate two archives :

• a ZIP containing the sources of the core
• a ZIP containing :
  • a WAR file, a webapp core, minimal, ready to be deployed and can be used as a basis for the deployment of plugins (which must be activated in the administration interface).
  • the initialization files of the database

Note In the case of a webapp intended to exploit several plugins, it is advisable to create a Lutece site.

Other uses of Maven

Get information

The Maven Help plugin provides information about the project or the system.

The following command allows for example to see the POM built by Maven from the POMs taken into account by the project (effective POM) :

$ mvn help:effective-pom

Initialize database

On Lutece projects built with "lutece:exploded" goal, the antrun:run goal allows the initialization of the database. If the database exists then it is reset.

$ mvn antrun:run

The connection with it is configured in the file WEB-INF/conf/db.properties (see Access to data).

It is possible to overload the db.properties file of the project by passing one of the following arguments in the command to indicate which database system to use :

• -Dlutece-test-mysql
• -Dlutece-test-postgresql
• -Dlutece-test-hsql

Depending on the database system chosen, db.properties will be overloaded by the db.properties model for this system. Optional arguments can be added to configure the connection to the database (for MySQL or PostGreSQL only) :

• -Dlutece-antrun-db-host=XXX
• -Dlutece-antrun-db-name=XXX
• -Dlutece-antrun-db-user=XXX
• -Dlutece-antrun-db-password=XXX

The default values for these last arguments are the following :

• lutece-antrun-db-host : localhost,
• lutece-antrun-db-name : lutece,
• lutece-antrun-db-user : lutece,
• lutece-antrun-db-password : motdepasse.

Examples :

# creates an hsql file database in target/ folder
$ mvn lutece:exploded antrun:run \
    -Dlutece-test-hsql

# PostGreSQ
$ mvn clean lutece:exploded antrun:run \
    -Dlutece-test-postgresql \
    -Dlutece-antrun-db-user=postgres \
    -Dlutece-antrun-db-password=postgres

# remote MySQL
$ mvn clean lutece:exploded antrun:run \
    -Dlutece-test-mysql \
    -Dlutece-antrun-db-host=vm18:3307 \
    -Dlutece-antrun-db-user=user19 \
    -Dlutece-antrun-db-password=$3cr3t \
    -Dlutece-antrun-db-name=test29

Run unit tests

To automatically test the plugin (unit test), you can use the following command :

$ mvn lutece:exploded antrun:run test

This will :

• start with the operations described in the previous step (manual test).
• erase and reset a database.
• run unit tests with maven.

Manage dependencies

The Maven Dependency plugin provides goals for managing project dependencies. Among these we can cite :

• The goal dependency:purge-local-repository which allows to delete the dependencies of the project in the local repository and possibly to resolve them again.

$ mvn dependency:purge-local-repository

• The goal dependency:tree shows the different package dependencies :

$ mvn dependency:tree -Dverbose
# see only the Lutece dependencies
$ mvn dependency:tree -Dverbose -Dincludes=fr.paris.lutece

• The goal dependency:resolve lists the site dependencies :

# list only the Lutece dependencies
$ mvn dependency:resolve -Dsort -DincludeGroupIds=fr.paris.lutece

Generate the documentation and the code reports

The site phase is used to build a maven site containing documentation on the current project and code reports :

$ mvn site

We can generate the documentation without the reports so that the operation is faster :

$ mvn site -DgenerateReports=false -Dmaven.test.skip=true

See also the documentation of Maven Site plugin for more information.

Note more memory needs to be allocated to Maven to generate reports via the env variable MAVEN_OPTS = -Xmx1024m

Markdown Documentation

A Lutece-specific Maven plugin converts the documentation home page in xDoc format (see Documentation conventions) into a README.md file in Markdown format used by GitHub :

$ mvn xdoc2md:readme

Format the code

The Maven Formatter plugin allows you to format the source code according to the rules of the Lutèce project :

$ mvn formatter:format

Insert Lutece licence in source code

The global POM refers to the License Maven plugin which allows you to add or update licenses in the headers of source files.

As of version 5.0.0 of the global POM, the License Maven plugin uses the goal license:update-file-header to add or update the Lutèce license in the source files :

$ mvn license:update-file-header

Before version 5.0.0 of the global POM, the License Maven plugin uses the goal license:format to add or update the Lutèce license in the source files :

$ mvn license:format