Build Plugins

Automate VLINGO XOOM platform related build tasks.

The XOOM build plugin provides build-time tools for automating steps that would be tedious if performed manually.

To use xoom-build-plugins in your builds, simply add it as build plugin in your pom.xml. The build tasks section below describes the supported goals and their configuration.

<project ...>
  <build>
    <plugins>
      <plugin>
        <groupId>io.vlingo.xoom</groupId>
        <artifactId>xoom-build-plugins</artifactId>
        <version>1.7.0</version>
        <executions>
        ...
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
  </project>

Build Tasks

There are currently two build tasks supported by the plugin. One is for using XOOM Schemata and one for generating proxies for XOOM ACTORS. These are both covered in this section.

Integration with XOOM Schemata

There are two uses of the plugin that integrates your build with VLINGO Schemata:

• Push schemas from your project to the schema registry: Makes your schemas available to dependent projects.

• Pulls from the schema registry to you project: Enabled your project to depend on the schemas of other projects, or to retrieve fresh definitions of your own schemas from the registry.

Various projects for services and applications (e.g. Bounded Contexts) must interact with others. To make interaction, such as collaboration and integration, more manageable, you use the VLINGO Schemata schema registry to publish and consume the exchanged type definitions. This implements the Published Language pattern using the registry to exchange type safe definitions and the corresponding source code. For a detailed description of schema specifications and registry usage, see VLINGO Schemata.

Specifications of Domain Events published by your services and applications should be kept along with its source code. Consumed types should not be committed with your sources but rather generated on demand. This makes updating to new event versions easy and will trigger build warnings or errors if you're depending on a version that is unsafe to use, e.g. if it becomes deprecated.

The push-schema and pull-schema goals of xoom-build-plugins enable you to perform the vital build tasks.

Both goals need to be configured with the URL of the VLINGO Schemata instance to push to and the client organization and unit of the current project, e.g.

<configuration>
  <schemataService>
    <url>http://localhost:9019</url>
    <clientOrganization>VLINGO</clientOrganization>
    <clientUnit>examples</clientUnit>
  </schemataService>
</configuration>

Goal: push-schema

The push-schema goal publishes schema specifications from your sources to the schema registry.

By default the path to your specification files defaults to src/main/vlingo/schemata and can be overridden by specifying configuration.srcDirectory

The push-schema goal doesn't bind to any lifecycle phase by default.

For each schema, you'll need to define:

• Its reference consisting of the organization, unit, context namespace, schema name, and version, e.g. VLINGO:examples:io.vlingo.xoom.examples.schemata:SchemaDefined:1.0.1

• The corresponding source file (optional, defaults to <schema-name-reference>.vss)

• The previous version of the schema in case you're updating an existing schema.

The following example configuration will push the schemas SchemaDefined v2.1.0 as an update to v2.0.4 and SchemaPublished v0.0.1 stored in src/main/vlingo to the registry running on localhost:9019 :

<build>
<plugins>
  <plugin>
    <groupId>io.vlingo.xoom</groupId>
    <artifactId>xoom-build-plugins</artifactId>
    <version>1.7.7</version>
    <executions>
      <execution>
        <id>push</id>
        <goals>
          <goal>push-schema</goal>
        </goals>
        <configuration>
          <srcDirectory>${basedir}/src/main/vlingo</srcDirectory>
          <schemataService>
            <url>http://localhost:9019</url>
            <clientOrganization>VLINGO</clientOrganization>
            <clientUnit>examples</clientUnit>
          </schemataService>
          <schemata>
            <schema>
              <ref>VLINGO:examples:io.vlingo.xoom.examples.schemata:SchemaDefined:2.1.0</ref>
              <src>SchemaDefinedButWithACustomFileName.vss</src>
              <previousVersion>2.0.4</previousVersion>
            </schema>
            <schema>
              <ref>VLINGO:examples:io.vlingo.xoom.examples.schemata:SchemaPublished:0.0.1</ref>
            </schema>
          </schemata>
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>
</build>

The schema will be pushed when the push-schema goal is run:

$ mvn io.vlingo.xoom:xoom-build-plugins:push-schemata@push

@push in the example above indicates the ID of the plugin execution (see the previous snippet with plugin configuration).

It's also possible to automatically push the schema during a chosen Maven phase. With the following example, Maven will push the schema when mvn install is run:

<build>
<plugins>
  <plugin>
    <groupId>io.vlingo.xoom</groupId>
    <artifactId>xoom-build-plugins</artifactId>
    <version>1.7.7</version>
    <executions>
      <execution>
        <id>push</id>
        <phase>install</phase>
        <goals>
          <goal>push-schema</goal>
        </goals>
        <configuration>
          <!-- schema configuration -->
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>
</build>

Goal: pull-schema

The pull-schema goal retrieves code generated by the schema registry and puts it into thetarget/generated-sources/vlingo output folder in the generate-sources lifecycle phase by default. You can override this default by specifying configuration.outputDirectory. The output folder is added to maven's compile path automatically. The specifications to pull are listed using their reference.

The following example will pull java code generated from the schemas defined in the previous section when running mvn generate-sources.

<build>
  <plugins>
    <plugin>
      <groupId>io.vlingo.xoom</groupId>
      <artifactId>xoom-build-plugins</artifactId>
      <version>1.1.0</version>
      <executions>
        <execution>
          <id>pull</id>
          <goals>
            <goal>pull-schema</goal>
          </goals>
          <configuration>
            <schemataService>
              <url>http://localhost:9019</url>
              <clientOrganization>VLINGO</clientOrganization>
              <clientUnit>examples</clientUnit>
            </schemataService>
            <schemata>
              <schema>
                <ref>VLINGO:examples:io.vlingo.xoom.examples.schemata:SchemaDefined:2.1.0</ref>
              </schema>
              <schema>
                <ref>VLINGO:examples:io.vlingo.xoom.examples.schemata:SchemaPublished:0.0.1</ref>
              </schema>
            </schemata>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

This example shows working integrations between services by using the plugin.

As with push-schema, it's also possible to trigger pull-schema on demand:

$ mvn io.vlingo.xoom:xoom-build-plugins:pull-schemata@pull

@pull in the example above indicates the ID of the plugin execution (see the previous snippet with plugin configuration).

Generating proxies for XOOM Actors

An important part of the XOOM architecture is the use of proxies to enable type-safe asynchronous message sending. The proxies are not implemented manually by XOOM SDK users. The platform SDK takes care of that for you by auto-generating and compiling them. Having actual classes generated is essential because it avoids the overhead of runtime dynamic proxies that use reflection. There are two ways that XOOM Actors supports proxy generation:

• Runtime generation: Requires no thought, planning, or effort. The sources are seamlessly generated once, compiled, generally during service or application startup. Any protocol interfaces and actor types that are not created until after startup will be generated and compiled at that time. The overhead is quite minimal, going unnoticed.

• Build-time generation: Requires including this build plugin and listing the names of service/application protocol interfaces in the build script. The proxies will be generated during regular builds.

For both of these options, the proxies are not generated into main source, but rather the area that your build tool designates as the generated sources area. In the case of both proxy generation options, you can cache the proxies by copying the source files from the generated sources area to the main source. This will provide a slight performance optimization over runtime generation, but will offer no advantages if using build-time generation.

If you decide to cache proxies, you must not edit the source code.

The one downside to caching proxies is that any changes to the protocol interface will not be immediately supported in the cached generated proxies. You will see build errors instead. The best way to avoid this is to delete the proxy source, run one or more tests that require the proxy, which causes the regeneration according to the current proxy interface. Then copy the newly generated source into your main source.

It is assumed that you would delete an obsolete proxy source, regenerate, and copy so as to recache the source, all before committing source to revision control. Doing so will retain the history of the changes rather than appearing that the source was deleted and then newly added later.

The following is and example of using the plugin with configuration for Maven builds:

...
  <build>
    <plugins>
      <plugin>
        <groupId>io.vlingo.xoom</groupId>
        <artifactId>xoom-build-plugins</artifactId>
        <version>${xoom.build.plugins.version}</version>
        <executions>
          <execution>
            <id>generateProxies</id>
            <phase>compile</phase>
            <goals>
              <goal>actorProxyGen</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <actorProtocols>
            <param>io.vlingo.xoom.maven.actortest.Test1Protocol</param>
            <param>io.vlingo.xoom.maven.actortest.Test2Protocol</param>
          </actorProtocols>
        </configuration>
      </plugin>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.3.2</version>
        <executions>
          <execution>
            <id>default-compile</id>
            <phase>generate-sources</phase>
          </execution>
          <execution>
            <id>build-generated-code</id>
            <phase>compile</phase>
            <goals>
              <goal>compile</goal>
            </goals>
            <configuration>
              <generatedSourcesDirectory>${project.build.directory}/generated-sources</generatedSourcesDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>3.0.0</version>
        <executions>
          <execution>
            <phase>generate-sources</phase>
            <goals>
              <goal>add-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>${project.build.directory}/generated-sources</source>
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
...

Note that the use of the Java-based xoom-build-plugins requires the use of two other plugins, namely:

• maven-compiler-plugin with the (default) groupId of org.apache.maven.plugins

• build-helper-maven-plugin with groupId of org.codehaus.mojo

If you prefer to use build-time generated proxies, see this example.