Maven Integration

Plug ActivePivot Live to Your Maven Build

Most of the projects relying on ActivePivot Live also use some Java code server-side. In these projects, a Maven build process is thus almost always already in place.

In order to streamline the integration of ActivePivot Live with this build process, we publish ActivePivot Live as a jar file to http://support.quartetfs.com/share/Live_stable/.

The jar artifact can be consumed by projects based on the sandbox or by projects that only import the ActivePivot Live library in HTML pages.

Jar Structure #

The jar groupId is quartetfs.biz.live and its artifactId is just live. It has the following content:

├── META-INF/resources/live/ <!-- for script integration -->
|   ├── fonts/
|   ├── locales/
|   └── app.min.js
└── livejs.tgz <!-- for sandbox integration -->

Script-based Integration #

If your project does not require complex client-side customization and just serving something such as the Dashboard widget would be enough, you can opt for the script-based integration of ActivePivot Live.

In this situation your project could have the following structure:

├── src/main/
|   ├── java/
|   ├── webapp/live/
|   |   └── index.html  
└── pom.xml
Tip

If your server’s root URL is http://localhost/server, then the HTML file should be accessible at http://localhost/server/live/index.html.

To plug ActivePivot Live into your Maven build, first edit the POM to add the new dependency:

<project>
  <!-- ... -->
  <dependencies>
    <!-- ... -->
    <dependency>
      <groupId>quartetfs.biz.live</groupId>
      <artifactId>live</artifactId>
    </dependency>
    <!-- ... -->
  </dependencies>
  <!-- ... -->
</project>

With this change, the ActivePivot Live jar will end up in the war under WEB-INF/lib/.

Tip

In our jar, the static assets are in the META-INF/resources/live/ directory. This structure should automatically make our JavaScript bundle accessible at http://localhost/server/live/app.min.js. Same thing for the locales and the fonts files.

The index.html content could then be pretty similar to the one in the script integration page but the path to the ActivePivot Live library would be ./app.min.js.

Warning

If you have a security layer set-up to prevent direct access to your server resources, you may need to tweak your configuration. In the server sandbox for instance, the LiveResourceServerConfig#getResourceLocations method should return a Set containing:

  • /live/ for your index.html
  • classpath:META-INF/resources/live/ for the jar assets

Sandbox Integration #

Let’s say that we have a project with the following structure:

├── live/ <!-- based on ActivePivot Live sandbox -->
|   ├── src/
|   └──  package.json
├── server/
|   ├── src/
|   └── pom.xml
└── pom.xml <!-- parent POM -->

By simply running mvn clean install -DskipTests (or mvn clean install to also launch the test suite) we want to:

  1. build the ActivePivot Live sandbox in production mode
  2. copy the generated assets in the server war under /live.

To achieve this goal, the first thing to do is declaring a new dependency in the parent POM:

<!-- pom.xml -->
<project>
  <!-- ... -->
  <modules>
    <module>live</module>
    <module>server</module>
  </modules>
  <!-- ... -->
  <properties>
    <!-- ... -->
    <apLiveVersion>4.0.12-SNAPSHOT</apLiveVersion>
    <!-- ... -->
  </properties>
  <!-- ... -->
  <dependencyManagement>
    <dependencies>
      <!-- ... -->
      <dependency>
        <groupId>quartetfs.biz.live</groupId>
        <artifactId>live</artifactId>
        <version>${apLiveVersion}</version>
      </dependency>
      <!-- ... -->
    </dependencies>
  </dependencyManagement>
  <!-- ... -->
</project>

In our live directory, we will create a new POM file:

<!-- live/pom.xml -->
<project>
  <parent>
    <!-- point to your parent POM -->
  </parent>

  <artifactId>project-live</artifactId>
  <name>Project Live</name>

  <build>
    <resources>
      <resource>
        <directory>${basedir}/dist</directory>
      </resource>
    </resources>
          
    <plugins>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <filesets>
            <fileset>
              <!--
                Deleting the livejs directory to force reinstall.
                It makes it easier to upgrade the live version in the parent POM.
              -->
              <directory>${basedir}/node_modules/livejs</directory>
            </fileset>
          </filesets>
        </configuration>
      </plugin>
      
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.10</version>
        <executions>
          <execution>
            <id>unpack</id>
            <phase>initialize</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>quartetfs.biz.live</groupId>
                  <artifactId>live</artifactId>
                  <overWrite>true</overWrite>
                  <!-- Only unpack the .tgz file needed by npm -->
                  <includes>*.tgz</includes>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>
      
      <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>exec-maven-plugin</artifactId>
          <version>1.4.0</version>
          <executions>
            <execution>
              <id>npm install</id>
              <phase>initialize</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>install</argument>
                </arguments>
              </configuration>
            </execution>
            
            <execution>
              <id>npm build</id>
              <phase>generate-resources</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>run</argument>
                  <argument>build:once:prod</argument>
                </arguments>
              </configuration>
            </execution>
            
            <execution>
              <id>npm test</id>
              <phase>test</phase>
              <goals>
                <goal>exec</goal>
              </goals>
              <configuration>
                <executable>npm</executable>
                <arguments>
                  <argument>run</argument>
                  <argument>test:once</argument>
                </arguments>
                <!--
                  Don't run the JavaScript test suite
                  when installing with -DskipTests.
                -->
                <skip>${skipTests}</skip>
              </configuration>
            </execution>
          </executions>
      </plugin>
    </plugins>
  </build>
</project>

The unpack task declared in the maven-dependency-plugin section will partially extract the ActivePivot Live jar and create the file live/target/dependency/livejs.tgz. Thus we need the package.json to point to this new path:

{
  "...": "...",
  "devDependencies": {
    "...": "...",
    "livejs": "file:./target/dependency/livejs.tgz"
  }
}

The last step is to edit the server POM:

<!-- server/pom.xml -->
<project>
  <!-- ... -->
  <dependencies>
    <dependency>
      <groupId><!-- put your project groupId --></groupId>
      <artifactId>project-live</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack-live</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeArtifactIds>project-live</includeArtifactIds>
              <outputDirectory>
                ${project.build.directory}/${project.build.finalName}/live
              </outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <!-- ... -->
</project>