Maven Integration · ActiveUI

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

In order to streamline the integration of ActiveUI with this build process, we publish the SDK as a jar file.

Jar Structure

The jar groupId is com.activeviam.activeui and its artifactId is activeui-sdk. It has the following content:

└── META-INF/resources/activeviam/activeui-sdk
    ├── cjs <!-- Folder containing the bundled modules used in the "ActiveUI Project" -->
    ├── index.js
    ├── locales <!-- Folder containing the translation files used by the SDK -->
    ├── package.json <!-- Entry point when using the SDK as an npm dependency -->
    └── umd
        ├── activeui-sdk.development.js <!-- Entry point when using the "Script-based Integration" while developing -->
        └── activeui-sdk.production.min.js <!-- Entry point when using the "Script-based Integration" in production -->

Using the Jar as an npm Dependency

Suppose we have a project with the following structure:

├── activeui/ <!-- your ActiveUI Project -->
|   ├── src/
|   └──  package.json
├── server/
|   ├── src/
|   └── pom.xml
└── pom.xml <!-- parent POM -->

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

build the ActiveUI Application in production mode
copy the generated assets in the server war under /activeui

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

<!-- pom.xml -->
<project>
  <!-- ... -->
  <modules>
    <module>activeui</module>
    <module>server</module>
  </modules>
  <!-- ... -->
  <properties>
    <!-- ... -->
    <ActiveUIVersion>{{ActiveUIVersion}}</ActiveUIVersion>
    <!-- ... -->
  </properties>
  <!-- ... -->
  <dependencyManagement>
    <dependencies>
      <!-- ... -->
      <dependency>
        <groupId>com.activeviam.activeui</groupId>
        <artifactId>activeui-sdk</artifactId>
        <version>${ActiveUIVersion}</version>
      </dependency>
      <!-- ... -->
    </dependencies>
  </dependencyManagement>
  <!-- ... -->
</project>

In our activeui folder, we will create a new POM file:

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

  <artifactId>activeui-application</artifactId>
  <name>ActiveUI Application</name>

  <build>
    <resources>
      <resource>
        <directory>${basedir}/build</directory>
      </resource>
    </resources>

    <plugins>
      <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>com.activeviam.activeui</groupId>
                  <artifactId>activeui-sdk</artifactId>
                  <overWrite>true</overWrite>
                </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</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</argument>
                </arguments>
                <!--
                  Don't run the JavaScript test suite
                  when installing with -DskipTests.
                -->
                <skip>${skipTests}</skip>
                <environmentVariables>
                   <!--
                     When CI (continuous integration) is false,
                     Create React App launches the tests in watch mode
                   -->
                  <CI>true</CI>
                </environmentVariables>
              </configuration>
            </execution>
          </executions>
      </plugin>
    </plugins>
  </build>
</project>

The unpack task declared in the maven-dependency-plugin section will extract our jar to the target/dependency directory. Thus we need the package.json to point to this path:

{
  "...": "...",
  "dependencies": {
    "...": "...",
    "@activeviam/activeui-sdk": "file:./target/dependency/META-INF/resources/activeviam/activeui-sdk"
  }
}

The last step is to edit the server POM:

<!-- server/pom.xml -->
<project>
  <!-- ... -->
  <dependencies>
    <dependency>
      <groupId><!-- put your project groupId --></groupId>
      <artifactId>activeui-application</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-activeui</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeArtifactIds>activeui-application</includeArtifactIds>
              <outputDirectory>
                ${project.build.directory}/${project.build.finalName}/activeui
              </outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <!-- ... -->
</project>

Using the Jar for Script-based Integration

If your project does not require complex client-side customization and is just serving a single widget such as a dashboard, you can opt for the Script-based Integration of ActiveUI SDK.

In this situation your project could have the following structure:

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

If your server's root URL is https://localhost/server, then the HTML file should be accessible at https://localhost/server/activeui/index.html.

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

<project>
  <!-- ... -->
  <dependencies>
    <!-- ... -->
    <dependency>
      <groupId>com.activeviam.activeui</groupId>
      <artifactId>activeui-sdk</artifactId>
    </dependency>
    <!-- ... -->
  </dependencies>
  <!-- ... -->
</project>

With this change, the ActiveUI SDK jar will now reside in the war under WEB-INF/lib/.

In our jar, the static assets are in the META-INF/resources/activeui-sdk/activeviam directory. This structure should automatically make our production bundle accessible at http://localhost/server/activeviam/activeui-sdk/umd/activeui-sdk.production.min.js. The same applies to the locales files.

The structure of our jar is similar to the WebJars ones except that we don't put our version in the path so that you don't have to duplicate it in several places. We recommend you take a look at their documentation to get more details about exposing client-side libraries from a Java server.

The index.html content could then be very similar to the one in the Script-based Integration page but the path to the ActiveUI library would be ./activeviam/activeui-sdk/umd/activeui-sdk.production.min.js.

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 ActiveUIResourceServerConfig#getResourceLocations method should return a Set containing:

/activeui/ for your index.html, favicon.ico, etc.

classpath:META-INF/resources/activeviam/activeui-sdk/ for ActiveUI SDK UMD scripts and supporting assets

classpath:META-INF/resources/webjars/react/16.3.1/umd/

classpath:META-INF/resources/webjars/react-dom/16.3.1/umd/