portlet-05-creating-multi-module-portlet-project.asciidoc

title	order	layout
Creating Multi-Module Portlet Project	5	page

Creating Multi-Module Portlet Project

It is possible to set up your Vaadin Portlet project up as a multi-module maven project. This allows each portlet to be placed into its own module, allowing for greater separation between the portlets. The separation makes it easier to separate concerns and allow multiple people or teams to work on the portlets simultaneously.

The multi-module Vaadin Portlet project can naturally contain non-Vaadin Portlets in their own modules (and vice-versa). A module may of course contain multiple portlets, if it makes sense for the project.

Multi-Module project is the recommended setup for Vaadin Portlet projects. In this chapter we look into what a multi-module project looks like for Vaadin Portlets, how and it can be set up.

Vaadin Portlet Multi-Module Project Structure

The project consists of 1+N modules, where N in the number of portlets in the project - the 1 stands for Vaadin frontend asset module. All frontend assets used by the Vaadin Portlets are packaged into a single war by the frontend asset module. The asset war can be deployed onto the same web server as the portlet wars, or onto some other file provider. Below is a sketch of a possible project structure.

Potential project structure

project-base
+-- frontend-bundle
+-- vaadin-portlet-1
+-- vaadin-portlet-2
:
+-- vaadin-portlet-n

For an example of a multi-module Vaadin Portlet project, take a look at the addressbook-portlet and the associated tutorial Address Book Demonstration. The tutorial covers the project structure and how the different portlet components interact.

Setting up the above configuration requires some configuration in pom.xml files of each module directly related to portlets. After the configuration is done, and everything has been built and deployed once, further portlet deployments require deploying only the war file for the module being edited, if there are no frontend changes. In the next section we show how to configure a multi-module Vaadin Portlet project.

Configuring a Vaadin Portlet Multi-Module Project

Configuring the Vaadin Portlet multi-module project has two requirements:

1. Portlet modules build wars without frontend resources

2. Static asset module packages frontend resources from all portlet wars

The first requirement can be achieved by not using vaadin-maven-plugin in the pom.xml. Normally, Vaadin 14+ projects would have vaadin-maven-plugin in the pom.xml to enable packaging frontend files into the war. We will simply leave the plugin out, and the first step is achieved.

The second step requires a bit more configuring. The static asset module needs to depend on each of the portlet modules. This means, that each portlet module builds two assets, a war and a jar. In addition, for the frontend resources to be available, the portlet modules need to be set up similarly to Vaadin add-on projects. Finally, the portlet modules need to be configured to fetch frontend resources from the deployed static frontend resource provider.

Building Two Assets

Building both war and jar can be achieved by configuring the maven-war-plugin as follows:

pom.xml in a portlet module

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <attachClasses>true</attachClasses>
    </configuration>
</plugin>

Adding the attachClasses flag instructs maven to build a jar file with -classes classifier. We use this jar as a dependency in our static assets module:

Add module as dependency to static assets pom.xml

<dependency>
    <groupId>your.group</groupId>
    <artifactId>module-name</artifactId>
    <classifier>classes</classifier>
</dependency>

Replace the groupId and artifactId with the correct values. The portlet module is now used as a dependency for the static asset module.

Structuring Module as a Vaadin Add-on

The significant part of the project structure, when considering add-ons, is the frontend resource folder. The folder is normally located on to root of the module for Vaadin 14+ projects. In order for the frontend resources to packaged into the jar file, place the files under the frontend folder to /src/main/resources/META-INF/frontend/.

Retrieving frontend Resources from the Static Asset Artifact

The Vaadin Portlet applications need to be instructed to retrieve the static frontend assets from the war build from the "static-vaadin-assets" module. This is done by adding the file ./src/main/resources/META-INF/VAADIN/config/flow-build-info.json.

After creating the file, put the following contents into the json file:

flow-build-info.json

{
  "externalStatsUrl": "/vaadin-portlet-static/VAADIN/config/stats.json"
}

The /vaadin-portlet-static/ is the assumed name of the war build from the static module. If you rename the war, change the json file to match. If you need to place the static asset war to some other web location, use the full URL to do so (keeping the /VAADIN/…​ portion intact).

Note	The relative URL is mapped to port 8080, so the above partial URL would map as http://127.0.0.1:8080/vaadin-portlet-static/VAADIN/config/stats.json. If your web server is mapped to a different port, provide the full URL instead of a relative URL.

Deploying Multi-Module Portlet Project

The deployment of a multi-module Vaadin Portlet project is very similar to that of the single module project: deploy all the portlet war files and static assets war file to your web server.

When editing a single portlet module, there are two different deployment patterns:

• If you only edit the Java code of the portlet and do not add frontend resources, you can simply re-build the portlet war and only re-deploy that war file.

• If you add frontend resources to your portlet module, you will need to re-build and re-deploy the static assets war as well as the portlet war itself.