The Fabric3 Gradle assembly plugin is used to create a runtime image as part of an automated, reproducible Maven build process. The plugin downloads the Fabric3 standalone runtime as well as required profiles and , extensions and application contributions. In addition, it can apply custom configuration to the runtime image. The Fabric3 assembly plugin will use these artifacts to create a runtime distribution complete with installed application contributions. During a Maven the release process, the runtime image can be uploaded to a Maven repository where it can be accessed by IT automation software during the system packaging and deployment process.
Plugin Setup
When executed, the Fabric3 assembly plugin will place the resulting runtime image in the project.build.directory/image
directory. The Fabric3 assembly plugin is typically used in conjunction with the Maven assembly plugin to produce a compressed archive. This can be done as follows The following demonstrates how to configure the assembly plugin:
Code Block | ||
---|---|---|
| ||
<plugins>apply <plugin> <groupId>org.fabric3</groupId> <artifactId>fabric3-assembly-plugin</artifactId> plugin: 'fabric3-assembly' buildscript { dependencies <version>${fabric3.version}</version> <executions>classpath group: 'org.fabric3.gradle', name: 'fabric3-assembly', version: fabric3Version } } <execution> fabric3Assembly { <id>fabric3-assembly</id> // Configure the runtime with profiles profile group: 'org.fabric3', <goals> <goal>fabric3-assembly</goal> </goals> </execution> </executions> <configuration> <runtimeVersion>${fabric3.version}</runtimeVersion> <contributions> <dependency> <groupId>org.fabric3.samples</groupId> <artifactId>gateway</artifactId> <version>${app.version}</version> </dependency> <contributions> </configuration> </plugin> <plugin> <artifactId>maven-assembly-plugin</artifactId> <version>${assembly.version}</version>name: 'profile-timer', version: fabric3Version // include project contributions contribution project('...') contribution project('...') // Overlay the standard runtime configuration with a the selected one for the current profile configFile source: 'src/main/config/' + activeProfile + '/systemConfig.xml' if (activeProfile == 'production') { <executions>configFile <execution> <id>make-assembly</id> <phase>package</phase> <goals> <goal>single</goal> </goals>source: 'src/main/datasource/ojdbc6.jar', target: 'extensions/datasource' } else { </execution> configFile </executions> </plugin> </plugins> |
The Maven assembly.xml
will then compress the runtime image into a ZIP file:
Code Block | ||
---|---|---|
| ||
<assembly ....> <id>bin</id>source: 'src/main/datasource/h2-1.3.175.jar', target: 'extensions/datasource' <baseDirectory>${project.build.directory}</baseDirectory> <formats>contribution project(':modules:setup:setup-test') <format>zip</format> </formats> <fileSets>} <fileSet> <outputDirectory>/</outputDirectory> Remove standard runtime configurations other than the default VM <directory>${project.build.directory}/image</directory> configuration (i.e. controller, participant, node) clean </fileSet> </fileSets> </assembly> |
Adding Contributions
Contributions are added using the contributions
element of the plugin configuration
as shown in the previous example. Note that the order of the contributions is not important: at startup, Fabric3 will introspect and order the contributions based on declared dependencies such as Java package imports (for details of dependency ordering, see Contribution Modularity).
By default, contributions are installed in the VM runtime image (i.e. under runtimes/vm/deploy
). If they should be deployed to the controller or another runtime configuration, use the contributionTarget
element:
...
<plugins>
<plugin>
<groupId>org.fabric3</groupId>
<artifactId>fabric3-assembly-plugin</artifactId>
...
<configuration>
<runtimeVersion>${fabric3.version}</runtimeVersion>
<contributionTarget>controller</contributionTarget>
<contributions>
<dependency>
<groupId>org.fabric3.samples</groupId>
<artifactId>gateway</artifactId>
<version>${app.version}</version>
</dependency>
<contributions>
</configuration>
</plugin>
...
</plugins>
Adding Configuration
Typically you will need to add runtime configuration to the produced image. This can be done by creating a systemConfig.xml file in the Maven module source
directory and including it in the plugin configuration under configurationFiles
:
...
<plugins>
<plugin>
<groupId>org.fabric3</groupId>
<artifactId>fabric3-assembly-plugin</artifactId>
<version>${fabric3.version}</version>
.....
<configuration>
<runtimeVersion>${fabric3.version}</runtimeVersion>
<configurationFiles>
<copy>
<source>../../../config/security.xml</source>
<destination>runtimes/vm/config</destination>
</copy>
</configurationFiles>
</configuration>
</plugin>
</plugins>
When creating a production system remember to disable the contribution directory scanner in systemConfig.xml by declaring a production runtime:
Code Block |
---|
<config>
...
<scanner production="true"/>
</config> |
Profiles and Extensions
Specifying profiles and extensions to include in the runtime image is done using the profiles
and extensions
elements respectively:
...
<plugins>
<plugin>
<groupId>org.fabric3</groupId>
<artifactId>fabric3-assembly-plugin</artifactId>
<version>${fabric3.version}</version>
<executions>
<execution>
<id>fabric3-assembly</id>
<goals>
<goal>fabric3-assembly</goal>
</goals>
</execution>
</executions>
<configuration>
<runtimeVersion>${fabric3.version}</runtimeVersion>
<profiles>
<!-- JMS support -->
<profile>
<groupId>org.fabric3</groupId>
<artifactId>profile-jms</artifactId>
<version>${fabric3.version}</version>
</profile>
<!-- JAX-RS support -->
<profile>
<groupId>org.fabric3</groupId>
<artifactId>profile-rs</artifactId>
<version>${fabric3.version}</version>
</profile>
</profiles>
<!-- add contributions -->
<contributions>
<dependency>
<groupId>org.fabric3.samples</groupId>
<artifactId>gateway</artifactId>
<version>${app.version}</version>
</dependency>
<dependency>
<groupId>org.fabric3.samples</groupId>
<artifactId>backend</artifactId>
<version>${app.version}</version>
</dependency>
</contributions>
<!-- overlay configuration -->
<configurationFiles>
<copy>
<source>../../../config/security.xml</source>
<destination>runtimes/vm/config</destination>
</copy>
</configurationFiles>
</configuration>
</plugin>
</plugins>
Excluding Extensions
Runtime extensions included as part of the standard standalone runtime distribution can be removed using the removeExtensions
element:
Code Block | ||
---|---|---|
xml | xml | <plugins> <plugin> <groupId>org.fabric3</groupId> <artifactId>fabric3-assembly-plugin</artifactId> ... <configuration> <runtimeVersion>${fabric3.version}</runtimeVersion> <!-- add contributions --> <contributions> <dependency> <groupId>org.fabric3.samples</groupId> <artifactId>gateway</artifactId> <version>${app.version}</version> </dependency> <dependency> <groupId>org.fabric3.samples</groupId> <artifactId>backend</artifactId> <version>${app.version}</version> </dependency> </contributions> <!-- overlay configuration --> <removeExtensions> <dependency> <groupId>org.fabric3</groupId> <artifactId>fabric3-management-jmx</artifactId> <version>${app.version}</version> </dependency> </removeExtensions> </configuration> </plugin> </plugins> true } |
The above configuration installs the Fabric3 timer profile as part of the runtime image. In addition, it copies the runtime configuration (systemConfig.xml) based on the active profile, for example, if a test or production is image is being built. Further, it demonstrates installing datasources (and JDBC drivers) and an additional setup module ('setup-test') based on the active build profile.
Configuration Elements
The following configuration elements are supported by the plugin:
contribution
- points to a Project in the current build or external dependency using the Gradle dependency formatconfigFile source: <>, target:<>
- a file that is copied from the source to target location relative to the runtime image root directoryprofile
- points to a Fabric3 profile specified using the Gradle dependency formatextension
- points to a Fabric3 extension specified using the Gradle dependency formatexclude
- excludes an extension module that is either a dependency of a profile or extensiondatasources
- Points to a JDBC module (e.g. JAR) resolved as a dependency. Specified using the Gradle dependency format.- shared - Adds a module to the runtime shared classpath. Specified using the Gradle dependency format.
contributionTarget <name>
- The runtime name. All configuration will be targeted to<runtime image>/runtimes/<runtime name>
.clean true|false - If true, removes runtime configuration other than the contributionTarget.