Arez

Edit

Project Setup

An Arez project can be setup using any build system that supports configuration of annotation processors. The authors prefer Apache Buildr but this is a relatively fringe build system so the project setup will be detailed using Apache Maven as that tool is relatively well known within the Java ecosystem.

Configure Maven

To configure Maven to support Arez you need to add a dependency on the library as well as configure the compiler to use the Arez annotation processor.

The core elements of Arez as well as the annotations and infrastructure for the annotation driven component model are included in the arez-core artifact. To add this library to your Maven project, simply add the following to your pom.xml:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.realityforge.arez</groupId>
      <artifactId>arez-core</artifactId>
      <version>0.249</version>
    </dependency>
    ...
  </dependencies>
</project>

To enable the annotation processor used by the component framework, you need add the following snippet to configure the maven compiler plugin from within the pom.xml:

<project>
  ...
  <plugins>
    ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.5.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
          <useIncrementalCompilation>false</useIncrementalCompilation>
          <annotationProcessorPaths>
            <path>
              <groupId>org.realityforge.arez</groupId>
              <artifactId>arez-processor</artifactId>
              <version>0.249</version>
            </path>
          </annotationProcessorPaths>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
</project>

Optional Generated Source Formatting

By default, the Arez processor writes the standard JavaPoet generated source. To format generated Arez component source, pass the literal annotation processor option -Aarez.format_generated_source=true. Any other value, or omitting the option, leaves generated source unformatted.

The persist processor supports the same behavior via -Aarez.persist.format_generated_source=true.

The formatter support is supplied by Proton and shaded inside the arez-processor artifact, but the formatter uses JDK compiler internals. On JDK 16 and later, the JVM running javac and annotation processing must receive these exports when formatting is enabled:

--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

For Maven, put the --add-exports flags in .mvn/jvm.config or MAVEN_OPTS so they reach the Maven JVM that runs annotation processing. If the compiler plugin forks javac, pass the same exports with -J, for example -J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED, so they reach the forked compiler JVM.

Configure your IDE

It is expected that most Arez applications are developed from within an IDE. The configuration of the IDE can be done by importing the pom.xml into the IDE but further customizations will often need to be done by the user. In particular, there is some additional steps required when using IntelliJ IDEA.

Configure a GWT Application

If you are using Arez within a GWT application you will also need to inherit the appropriate GWT module in your .gwt.xml file. For Arez applications that depend on the component model it is sufficient to add:

<module>
  ...
  <inherits name='arez.component.Component'/>
  ...
</module>

If you are not using the component model you can instead inherit the base module:

<module>
  ...
  <inherits name='arez.Arez'/>
  ...
</module>

In addition you can also add the Dev module if you want the framework to perform validation and limited invariant checking. The Dev module is very useful during development as it adds a level of safety and error checking but it should not be used in production environments as it adds some overhead. The Dev module decreases the execution speeds and significantly increases the code size. In small and medium sized applications, the extra safety afforded by developing with the Dev module always enabled and disabling the Dev module for production builds is usually worth the decreased performance of development builds. The Dev module can be added via:

<module>
  ...
  <inherits name='arez.ArezDev'/>
  ...
</module>

Rather than adding the Dev module you can instead add the Debug module and force the Arez framework to do significantly more invariant checking. This adds a significant performance impact and should never be present in production builds and may be too much overhead, even in development builds. The Debug module can be added via:

<module>
  ...
  <inherits name='arez.ArezDebug'/>
  ...
</module>
← MotivationGetting Started →