Usage

Hocon Includes (the good stuff)

Hocon has an additional syntax of particular interest to Unbound’s use cases. Hocon can include other hocon files. This means you can abstract arbitrary parts of a multi-module build system into any Hocon file. Then these build components can be included in sub-modules. For instance in a file called scalaCompile.conf could be

dependencies +=
  {
    groupId = "org.scala-lang", artifactId = "scala-library"
    version = "${versionScalaRelease}", scope = "compile"
  }
build {
  plugins +=
    {
      groupId = "org.apache.maven.plugins", artifactId = "maven-compiler-plugin"
      version = "3.7.0"
      configuration { skip = true, skipMain = true }
    }
  plugins +=
    {
      groupId = "net.alchim31.maven", artifactId = "scala-maven-plugin"
      version = "4.0.2"
      configuration { scalaVersion = "${versionScalaRelease}" }
      executions = [ { goals = [ "compile", "testCompile" ] } ]
    }
}

and then in your pom.conf file you have

{
  project {
    artifactId = "my-sub-module"
    properties { versionScalaRelease = "2.12.8" }
    include "scalaCompile.conf"
  }
}

This allows for arbitary abstraction of any part of the maven POM without breaking how reporting aggregration works. This allows for a nice addition to Maven’s existing abstraction functionality without requiring existing code to change.

Lists

Lists are handled differently in pom.xml files. A parent element is labeled with a pluralized form of a noun and the child elements are all labeled with the same singular form of the noun. In Hocon this gets compressed to

dependencies = [
  { groupId = "foo", artifactId = "bar" }
  { groupId = "foo2", artifactId = "bar2" }
]

So this Hocon becomes the following XML

<dependencies>
  <dependency>
    <groupId>foo</groupId>
    <artifactId>bar</artifactId>
  </dependency>
  <dependency>
    <groupId>foo2</groupId>
    <artifactId>bar2</artifactId>
  </dependency>
</dependencies>

Notice that the word dependency disappears from the Hocon (and Json) form(s).

Properties

Another difference is how Properties objects are handled in configuration elements. In Plugins and some other POM model components, there are often a configuration element whose values are bound to fields of the Plugin’s Mojo. When the Mojo binds a Properties object, its XML is expressed in this rather verbose way:

<configuration>
  <myProperties>
    <property>
      <name>propertyName1</name>
      <value>propertyValue1</value>
    <property>
    <property>
      <name>propertyName2</name>
      <value>propertyValue2</value>
    <property>
  </myProperties>
</configuration>

In Hocon becomes:

configuration {
  myProperties {
    properties = true
    propertyName1 = "propertyValue1"
    propertyName2 = "propertyValue2"
  }
}

Note the properties = true entry that is added. This way when this Hocon is converted back to XML, it can be converted into the correct XML for the Plugin. Otherwise, this block of Hocon would be converted to

<configuration>
  <myProperties>
    <propertyName1>propertyValue1</propertyName1>
    <propertyName2>propertyValue2</propertyName2>
  </myProperties>
</configuration>

by following the general rules of translating XML Elements to Map of String to Any. See Configuring Plugins for more information.

XML Attributes

Even though most Maven POM XML files don’t have configuration elements with attributes it does happen. To handle this case, you must add a special key called attributeKeys to your Hocon or Json object to tell Unbound which children to create XML elements for and which ones to create XML attributes for. So this Hocon

"target" {
  "chmod" { "attributeKeys" = [ "perm" ]
    "perm" = "755"
    "fileset" { "attributeKeys" = [ "dir" ]
      "dir" = "${basedir}/target/deb"
      "include" = { "attributeKeys" = [ "name" ]
        "name" = "usr/bin/mvnu"
      }
    }
  }
}

becomes this XML

<target>
  <chmod perm="755">
    <fileset dir="${basedir}/target/deb">
      <include name="usr/bin/mvnu"/>
    </fileset>
  </chmod>
</target>

which is messy but its such a rare case that it hardly matters.

Shared Plugin Configuration

There are three other special cases that appear because of shared infrastructure supplied by Maven and used by Plugins. Transformer and Archiver functionality can be used by Plugin authors to provide compression, dependency resolution or other common functionality provided by Maven itself. These features are configured in commons but special ways.

<transformers>
  <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
    <mainClass>org.apache.maven.unbound.Cli</mainClass>
  </transformer>
</transformers>

transformers = [ { implementation = "org.apache.maven.plugins.shade.resource.ManifestResourceTransformer", mainClass = "org.apache.maven.unbound.Cli" } ]

<archive>
  <manifest>
    <addClasspath>true</addClasspath>
    <mainClass>com.footballradar.jpademo.App</mainClass>
  </manifest>
  <manifestFile>src/main/resources/Manifest.txt</manifestFile>
</archive>

archive {
  manifestFile = "src/main/resources/Manifest.txt"
  manifest { addClasspath = true, mainClass = "com.footballradar.jpademo.App" }
}

<fileset>
  <directory>src/main/java</directory>
  <outputDirectory>target/classes</outputDirectory>
  <includes><include>*.java</include><includes>
</fileset>

fileset { directory = "src/main/java", outputDirectory = "target/classes", includes = [ "*.java" ] }

defineBridge = [ { groupId = "org.scala-sbt", artifactId = "compiler-bridge_${version.scala.epoch}", version = "${version.scala.zinc}" } ]
defineCompiler = [ { groupId = "org.scala-lang", artifactId = "scala-compiler", version = "${version.scala.release}" } ]

<defineBridge>
  <dependency>
    <groupId>org.scala-sbt</groupId>
    <artifactId>compiler-bridge_${version.scala.epoch}</artifactId>
    <version>${version.scala.zinc}</version>
  </dependency>
</defineBridge>
<defineCompiler>
  <dependency>
    <groupId>org.scala-lang</groupId>
    <artifactId>scala-compiler</artifactId>
    <version>${version.scala.release}</version>
  </dependency>
</defineCompiler>