ALFA Maven Plugin (OSS)

ALFA Tools include an Apache Maven plugin that support compiling ALFA projects and executing ALFA model importers and exporters.

The plugin releases are published in the central Maven repository -

https://mvnrepository.com/artifact/com.schemarise.alfa.utils/alfa-maven-plugin

Plugin Usage

An example usage of the plugin is shown below:

<plugin>
   <groupId>com.schemarise.alfa.utils</groupId>
   <artifactId>alfa-maven-plugin</artifactId>
   <version>3.4.7</version>
   <executions>
      <execution>
         <id>alfa-exec</id>
         <goals>
            <goal>compile</goal>
            <goal>package</goal>
         </goals>
         <configuration>
             <exportSettings>
                 <exportSetting>
                     <exportType>java</exportType>
                 </exportSetting>
             </exportSettings>
         </configuration>
      </execution>
   </executions>
</plugin>

The plugin support 2 Maven goals, compile and package.

1. compile - compiles and executes exporters defined under configuration.
2. package - packages the alfa files into a zip artifact, that can be uploaded to a repository and be used as dependency to other ALFA projects.

The plugin locates ALFA source files in 3 possible ways.

1. Top level Maven source directory

   <sourceDirectory>${basedir}/src/main/alfa</sourceDirectory>
   

2. Use build-helper-maven-plugin and add source directory

   <source>${basedir}/src/main/alfa</source>
   

3. Specify srcPath parameter to the ALFA plugin as shown in the complete example below. ..

   <srcPath>${basedir}/src/main/alfa</srcPath>
   

Plugin Parameters

All parameters are optional.

Name	Description
srcPath	Custom path to ALFA source files.
srcDependency	Specified as < group >:< artifact >:< version >; Use the dependency as source for code generation. Plugin should depend on the required artifact.
exportSetting[]	Array of ExportSetting objects
exportSetting.exportType	Exporter to run - e.g. java
exportSetting.outputDir	Custom output dir. By default target/generated-sources/${exportType}
exportSetting.config	Map of key value pairs for configuring exporter.

Plugin Compile-time Dependencies

ALFA files being compiled by the Plugin can reference other Maven-based artifacts at compile time. This allows teams to share their definitions via formal release processes. Downstream teams can express dependencies on ALFA artifacts to reference definitions from other ALFA artifacts.

Other ALFA generated projects can be used a dependencies by specifying a dependency when using the ALFA plugin. Note the classifier and type fields need to be specified as a alfa and zip respectively.

<dependencies>
    <dependency>
        <groupId>other.project.group</groupId>
        <artifactId>other-project-name</artifactId>
        <version>1.0</version>
        <classifier>alfa</classifier>
        <type>zip</type>
    </dependency>
</dependencies>

Dependencies can used as source for code generation. See srcDependency plugin parameter.

Complete Example

To quickly setup a test Maven project with ALFA files, you can follow the 3 steps below.

• Create a new directory alfademo. In alfademo, create new file pom.xml file and paste the contents below.

<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>alfa-demo-project</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
      <encoding>UTF-8</encoding>
  </properties>

  <!-- The generated Java code depends on the the alfa-rt-java-core library /-->
  <dependencies>
      <dependency>
          <groupId>com.schemarise.alfa.runtime</groupId>
          <artifactId>alfa-runtime-java</artifactId>
          <version>3.4.7</version>
      </dependency>
  </dependencies>

  <build>
     <plugins>
        <plugin>
           <groupId>com.schemarise.alfa.utils</groupId>
           <artifactId>alfa-maven-plugin</artifactId>
           <version>3.4.7</version>
           <executions>
              <execution>
                 <id>alfa-exec</id>
                 <goals>
                    <goal>compile</goal>
                    <goal>package</goal>
                 </goals>
                 <configuration>
                     <!-- source path /-->
                     <srcPath>${basedir}/src/main/alfa</srcPath>
                     <!-- generate java /-->
                     <exportSettings>
                         <exportSetting>
                             <exportType>java</exportType>
                         </exportSetting>
                     </exportSettings>
                 </configuration>
              </execution>
           </executions>
        </plugin>

        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>1.7</version>
            <executions>
                <execution>
                    <id>add-java-gen-source</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>${project.build.directory}/generated-sources/java</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>

     </plugins>
  </build>
</project>

• In alfademo, create a file in a subdirectory as src/main/alfa/demo.alfa, and paste the contents below.

namespace sample

trait Person {
   FirstName : string
   LastName : string
   DateOfBirth : date
   email : string
}

enum ServiceLevelType {
   Standard Gold Platinum
}

entity Customer key ( Id : uuid ) includes Person {
   Accounts : set< string >
   DeclaredIncomes : list< double >
   ServiceLevel : ServiceLevelType
}

service CustomerSvc() {
   getCustomerByEmailAddress( email : string) : Customer?
}

• Run mvn install in the alfademo directory. When run the 1st time, it will download the ALFA plugin and runtime arifacts.

If successful, you should have jar created - target/alfa-demo-project-1.0-SNAPSHOT.jar. The generated Java code can be seen in target/generated-sources/java/.

Congratulations! You have generated and built your 1st ALFA type library!