Module org.tquadrat.foundation.javacomposer

Package org.tquadrat.foundation.javacomposer

package org.tquadrat.foundation.javacomposer

JavaComposer is a Java toolkit for the generation of Java source code. Basically, this is a fork of version 1.11.1 of JavaPoet that was originally developed by Square, Inc. (see below). Refer to https://github.com/square/javapoet for the original software.

The interfaces in this package are not meant to be implemented by the user; instead they provide several static methods that allow to obtain an instance of the respective implementation. According to this, the behaviour of the adapted version is not different from the original.

Unless otherwise stated, null argument values will cause methods and constructors of all classes in this package to throw an Exception, usually a NullArgumentException, but in some rare cases, it could be also a NullPointerException.

Source code generation can be useful when doing things such as annotation processing or interacting with metadata files (e.g., database schemas, protocol formats). By generating the code, you eliminate the need to write boilerplate while also keeping a single source of truth for the metadata.

Example

Here's a (boring) HelloWorld class:

  package com.example.helloworld;

  public final class HelloWorld {
      public static void main(String[] args) {
          System.out.println("Hello, JavaComposer!");
      }
  }

And this is the (exciting) code to generate it with JavaComposer:

  MethodSpec main = MethodSpec.methodBuilder( "main" )
      .addModifiers( Modifier.PUBLIC, Modifier.STATIC )
      .returns( void.class )
      .addParameter( String[].class, "args" )
      .addStatement( "$T.out.println($S)", System.class, "Hello, JavaComposer!" )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC, Modifier.FINAL )
      .addMethod( main )
      .build();

  JavaFile javaFile = JavaFile.builder( "com.example.helloworld", helloWorld )
      .layout( JavaFile.Layout.LAYOUT_JAVAPOET )
      .build();

  javaFile.writeTo( System.out );

To declare the main method, we've created a MethodSpec "main" and configured it with modifiers, return type, parameters and code statements. We add that main method to a HelloWorld class, and then add that to a HelloWorld.java file.

In this case we write the file to System.out, but we could also get it as a string (JavaFile.toString()) or write it to the file system (JavaFile.writeTo()). It can be used also directly as input to an instance of JavaCompiler (JavaFile.toJavaFileObject()). The JavaDoc lists the complete JavaComposer API, which we explore below.

Code & Control Flow

Most of JavaComposer's API uses plain old immutable Java objects. There are also builders, method chaining and varargs to make the API friendly to use. JavaComposer offers models for classes & interfaces (TypeSpec), fields (FieldSpec), methods & constructors (MethodSpec), parameters (ParameterSpec), annotations (AnnotationSpec) and lambdas (LambdaSpec).

But the body of methods and constructors is not modelled. There's no expression class, no statement class or syntax tree nodes. Instead, JavaComposer uses strings for code blocks:

  MethodSpec main = MethodSpec.methodBuilder( "main" )
      .addCode(
          """
          int total = 0;
          for (int i = 0; i < 10; i++) {
              total += i;
          }
          """ )
      .build();

Which generates this:

  void main() {
      int total = 0;
      for (int i = 0; i < 10; i++) {
          total += i;
      }
  }

The manual semicolons, line wrapping, and indentation are tedious and so JavaComposer offers APIs to make it easier. There's addStatement() which takes care of semicolons and newline, and beginControlFlow() and endControlFlow() which are used together for braces, newlines, and indentation. The output from the code below is the same as above:

  MethodSpec main = MethodSpec.methodBuilder( "main" )
      .addStatement( "int total = 0" )
      .beginControlFlow( "for (int i = 0; i < 10; i++)" )
      .addStatement( "total += i" )
      .endControlFlow()
      .build();

This example is lame because the generated code is constant! Suppose instead of just adding 0 to 10, we want to make the operation and range configurable. Here's a method that generates a method:

  private MethodSpec computeRange( String name, int from, int to, String op )
  {
      var retValue = MethodSpec.methodBuilder( name )
          .returns( int.class )
          .addStatement( "int result = 1" )
          .beginControlFlow( "for (int i = " + from + "; i < " + to + "; i++)" )
          .addStatement( "result = result " + op + " i" )
          .endControlFlow()
          .addStatement( "return result" )
          .build();

     //---* Done *----------------------------------------------------------
     return retValue;
  }   //  computeRange()

And here's what we get when we call computeRange( "multiply10to20", 10, 20, "*" ):

  int multiply10to20() {
      int result = 1;
      for (int i = 10; i < 20; i++) {
          result = result * i;
      }
      return result;
  }

Methods generating methods! And since JavaComposer generates source instead of byte code, you can read through it to make sure it's right.

$L for Literals

The string-concatenation in calls to beginControlFlow() and addStatement() is distracting. Too many operators. To address this, JavaComposer offers a syntax inspired-by but incompatible with String.format(String,Object[]). It accepts $L to emit a literal value in the output. This works just like Formatter's %s:

  private MethodSpec computeRange( String name, int from, int to, String op )
  {
      var retValue = MethodSpec.methodBuilder( name )
          .returns( int.class )
          .addStatement( "int result = 0" )
          .beginControlFlow( "for (int i = $L; i < $L; i++)", from, to )
          .addStatement( "result = result $L i", op )
          .endControlFlow()
          .addStatement( "return result" )
          .build();

      //---* Done *----------------------------------------------------------
      return retValue;
  }   //  computeRange()

Literals are emitted directly to the output code with no escaping. Arguments for literals may be Strings, primitives, and a few JavaComposer types described below.

$S for Strings

When emitting code that includes string literals, we can use $S to emit a string, complete with wrapping quotation marks and escaping. Here's a program that emits three methods, each of which returns its own name:

  public static void main( String[] args ) throws Exception
  {
      TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
          .addModifiers( Modifier.PUBLIC, Modifier.FINAL )
          .addMethod( whatsMyName( "slimShady" ) )
          .addMethod( whatsMyName( "eminem" ) )
          .addMethod( whatsMyName( "marshallMathers" ) )
          .build();

      JavaFile javaFile = JavaFile.builder( "com.example.helloworld", helloWorld )
          .layout( JavaFile.Layout.LAYOUT_JAVAPOET )
          .build();

      javaFile.writeTo(System.out);
  }   //  main()

  private static MethodSpec whatsMyName( String name )
  {
      var retValue MethodSpec.methodBuilder( name )
          .returns( String.class )
          .addStatement( "return $S", name )
          .build();

      //---* Done *----------------------------------------------------------
      return retValue;
  }   //  whatsMyName()

In this case, using $S gives us quotation marks:

  public final class HelloWorld {
      String slimShady() {
          return "slimShady";
      }

      String eminem() {
          return "eminem";
      }

      String marshallMathers() {
          return "marshallMathers";
      }
  }

$T for Types

We Java programmers love our types: they make our code easier to understand. And JavaComposer is on board. It has rich built-in support for types, including automatic generation of import statements. Just use $T to reference types:

  MethodSpec today = MethodSpec.methodBuilder( "today" )
      .returns( Date.class )
      .addStatement( "return new $T()", Date.class )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC, Modifier.FINAL )
      .addMethod( today )
      .build();

  JavaFile javaFile = JavaFile.builder( "com.example.helloworld", helloWorld )
      .layout( JavaFile.Layout.LAYOUT_JAVAPOET )
      .build();

  javaFile.writeTo( System.out );

That generates the following *.java file, complete with the necessary import:

  package com.example.helloworld;

  import java.util.Date;

  public final class HelloWorld {
      Date today() {
          return new Date();
      }
  }

We passed Date.class to reference a class that just-so-happens to be available when we're generating code. This doesn't need to be the case. Here's a similar example, but this one references a class that doesn't exist (yet):

  ClassName hoverboard = ClassName.get( "com.mattel", "Hoverboard" );

  MethodSpec today = MethodSpec.methodBuilder( "tomorrow" )
      .returns( hoverboard )
      .addStatement( "return new $T()", hoverboard )
      .build();

And that not-yet-existent class is imported as well:

  package com.example.helloworld;

  import com.mattel.Hoverboard;

  public final class HelloWorld {
      Hoverboard tomorrow() {
          return new Hoverboard();
      }
  }

The ClassName type is very important, and you'll need it frequently when you're using JavaComposer. It can identify any declared class. Declared types are just the beginning of Java's rich type system: we also have arrays, parameterised types, wildcard types, and type variables. JavaComposer has classes for building each of these:

  ClassName hoverboard = ClassName.get( "com.mattel", "Hoverboard" );
  ClassName list = ClassName.get( "java.util", "List" );
  ClassName arrayList = ClassName.get( "java.util", "ArrayList" );
  TypeName listOfHoverboards = ParameterizedTypeName.get( list, hoverboard );

  MethodSpec beyond = MethodSpec.methodBuilder( "beyond" )
      .returns( listOfHoverboards )
      .addStatement( "$T result = new $T<>()", listOfHoverboards, arrayList )
      .addStatement( "result.add(new $T())", hoverboard )
      .addStatement( "result.add(new $T())", hoverboard )
      .addStatement( "result.add(new $T())", hoverboard )
      .addStatement( "return result" )
      .build();

JavaComposer will decompose each type and import its components where possible:

  package com.example.helloworld;

  import com.mattel.Hoverboard;
  import java.util.ArrayList;
  import java.util.List;

  public final class HelloWorld {
      List<Hoverboard> beyond() {
          List<Hoverboard> result = new ArrayList <>();
          result.add(new Hoverboard());
          result.add(new Hoverboard());
          result.add(new Hoverboard());
          return result;
      }
  }

Import static

JavaComposer also supports import static. It does it via explicitly collecting type member names. Let's enhance the previous example with some static sugar:

  …

  ClassName namedBoards = ClassName.get( "com.mattel", "Hoverboard", "Boards" );

  MethodSpec beyond = MethodSpec.methodBuilder( "beyond" )
      .returns( listOfHoverboards )
      .addStatement( "$T result = new $T<>()", listOfHoverboards, arrayList )
      .addStatement( "result.add($T.createNimbus(2000))", hoverboard )
      .addStatement( "result.add($T.createNimbus(\"2001\"))", hoverboard )
      .addStatement( "result.add($T.createNimbus($T.THUNDERBOLT))", hoverboard, namedBoards )
      .addStatement( "$T.sort(result)", Collections.class )
      .addStatement( "return result.isEmpty() ? $T.emptyList() : result", Collections.class )
      .build();

  TypeSpec hello = TypeSpec.classBuilder( "HelloWorld" )
      .addMethod( beyond )
      .build();

  JavaFile.builder( "com.example.helloworld", hello )
      .layout( JavaFile.Layout.LAYOUT_JAVAPOET )
      .addStaticImport( hoverboard, "createNimbus" )
      .addStaticImport( namedBoards, "*" )
      .addStaticImport( Collections.class, "*" )
      .build();

JavaComposer will first add your import static block to the file as configured, match and mangle all calls accordingly and also import all other types as needed:

  package com.example.helloworld;

  import static com.mattel.Hoverboard.Boards.*;
  import static com.mattel.Hoverboard.createNimbus;
  import static java.util.Collections.*;

  import com.mattel.Hoverboard;
  import java.util.ArrayList;
  import java.util.List;

  class HelloWorld {
      List<Hoverboard> beyond() {
          List<Hoverboard> result = new ArrayList<>();
          result.add(createNimbus(2000));
          result.add(createNimbus("2001"));
          result.add(createNimbus(THUNDERBOLT));
          sort(result);
          return result.isEmpty() ? emptyList() : result;
      }
  }

$N for Names

Generated code is often self-referential. Use $N to refer to another generated declaration by its name. Here's a method that calls another:

  public String byteToHex(int b) {
  char[] result = new char[2];
  result[0] = hexDigit((b >>> 4) & 0xf);
  result[1] = hexDigit(b & 0xf);
  return new String(result);
  }

  public char hexDigit(int i) {
  return (char) (i < 10 ? i + '0' : i - 10 + 'a');
  }

When generating the code above, we pass the hexDigit() method as an argument to the byteToHex() method using $N:

  MethodSpec hexDigit = MethodSpec.methodBuilder( "hexDigit" )
      .addParameter( int.class, "i" )
      .returns( char.class )
      .addStatement( "return (char) (i < 10 ? i + '0' : i - 10 + 'a')" )
      .build();

  MethodSpec byteToHex = MethodSpec.methodBuilder( "byteToHex" )
      .addParameter( int.class, "b" )
      .returns( String.class )
      .addStatement( "char[] result = new char[2]" )
      .addStatement( "result[0] = $N((b >>> 4) & 0xf)", hexDigit )
      .addStatement( "result[1] = $N(b & 0xf)", hexDigit )
      .addStatement( "return new String(result)" )
      .build();

Code block format strings

Code blocks may specify the values for their placeholders in a few ways. Only one style may be used for each operation on a code block.

In each example, we generate code to say "I ate 3 tacos".

Relative Arguments

Pass an argument value for each placeholder in the format string to CodeBlock.add().

  CodeBlock.builder().add( "I ate $L $L", 3, "tacos" );

Positional Arguments

Place an integer index (1-based) before the placeholder in the format string to specify which argument to use.

  CodeBlock.builder().add( "I ate $2L $1L", "tacos", 3 );

Named Arguments

Use the syntax

$<argumentName>:<X>

where X is the format character, and call CodeBlock.addNamed() with a map containing all argument keys in the format string. Argument names use characters in a-z, A-Z, 0-9, and _, and must start with a lowercase character.

  Map<String,Object> map = Map.of( "food", "tacos", "count", 3 );
  CodeBlock.builder().addNamed( "I ate $count:L $food:L", map );

Methods

All of the above methods have a code body. Use Modifier.ABSTRACT to get a method without any body. This is only legal if the enclosing class is either abstract or an interface. 

  MethodSpec flux = MethodSpec.methodBuilder( "flux" )
      .addModifiers( Modifier.ABSTRACT, Modifier.PROTECTED )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC, Modifier.ABSTRACT )
      .addMethod( flux )
      .build();

Which generates this:

public abstract class HelloWorld {
      protected abstract void flux();
  }

The other modifiers work where permitted. Note that when specifying modifiers, JavaComposer uses Modifier, a class that is not available on Android. This limitation applies to code-generating-code only; the output code runs everywhere: JVMs, Android, and GWT.

Methods also have parameters, exceptions, varargs, Javadoc comments, annotations, type variables, and a return type. All of these are configured with MethodSpec.Builder.

Constructors

MethodSpec is a slight misnomer; it can also be used for constructors:

  MethodSpec flux = MethodSpec.constructorBuilder()
      .addModifiers( Modifier.PUBLIC )
      .addParameter( String.class, "greeting" )
      .addStatement( "this.$N = $N", "greeting", "greeting" )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC )
      .addField( String.class, "greeting", Modifier.PRIVATE, Modifier.FINAL )
      .addMethod( flux )
      .build();

Which generates this:

  public class HelloWorld {
      private final String greeting;

      public HelloWorld(String greeting) {
          this.greeting = greeting;
      }
  }

For the most part, constructors work just like methods. When emitting code, JavaComposer will place constructors before methods in the output file.

Parameters

Declare parameters on methods and constructors with either JavaComposer.parameterBuilder(org.tquadrat.foundation.javacomposer.TypeName,CharSequence,javax.lang.model.element.Modifier...) or MethodSpec's convenience addParameter() API:

  ParameterSpec android = composer.parameterBuilder( String.class, "android" )
      .addModifiers( Modifier.FINAL )
      .build();

  MethodSpec welcomeOverlords = composer.methodBuilder( "welcomeOverlords" )
      .addParameter( android )
      .addParameter( String.class, "robot", Modifier.FINAL )
      .build();

Though the code above to generate android and robot parameters is different, the output is the same:

  void welcomeOverlords(final String android, final String robot) {
  }

The extended Builder form is mandatory when the parameter has annotations (such as @Nullable).

Fields

Like parameters, fields can be created either with builders or by using convenient helper methods:

  FieldSpec android = FieldSpec.builder( String.class, "android" )
      .addModifiers( Modifier.PRIVATE, Modifier.FINAL )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC )
      .addField( android )
      .addField( String.class, "robot", Modifier.PRIVATE, Modifier.FINAL )
      .build();

Which generates:

  public class HelloWorld {
      private final String android;

      private final String robot;
  }

The extended Builder form is necessary when a field has Javadoc comments, annotations, or a field initializer. Field initializers use the same String.format()-like syntax as the code blocks above:

  FieldSpec android = FieldSpec.builder( String.class, "android" )
      .addModifiers( Modifier.PRIVATE, Modifier.FINAL )
      .initializer( "$S + $L", "Lollipop v.", 5.0d )
      .build();

Which generates:

  private final String android = "Lollipop v." + 5.0;

The method TypeSpec.addProperty() can be used to add getter and setter together with the field:

 FieldSpec android = FieldSpec.builder( String.class, "android" )
      .addModifiers( Modifier.PRIVATE )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC )
      .addProperty( android, false )
      .build();

Which generates:

  public class HelloWorld {
      private String android;

      public final String getAndroid() {
          return android;
      }

      public final void setAndroid(String value) {
          android = value;
      }
  }

Interfaces

JavaComposer has no trouble with interfaces. Note that interface methods must always be public abstract and interface fields must always be public static final. These modifiers are necessary when defining the interface:

  TypeSpec helloWorld = TypeSpec.interfaceBuilder( "HelloWorld" )
      .addModifiers( Modifier.PUBLIC )
      .addField( FieldSpec.builder( String.class, "ONLY_THING_THAT_IS_CONSTANT" )
          .addModifiers( Modifier.PUBLIC, Modifier.STATIC, Modifier.FINAL )
          .initializer( "$S", "change" )
          .build() )
      .addMethod( MethodSpec.methodBuilder( "beep" )
          .addModifiers( Modifier.PUBLIC, Modifier.ABSTRACT )
          .build() )
       .build();

But these modifiers are omitted when the code is generated. These are the defaults so we don't need to include them for javac's benefit!

  public interface HelloWorld {
      String ONLY_THING_THAT_IS_CONSTANT = "change";

      void beep();
  }

Enums

Use enumBuilder to create the enum type, and addEnumConstant() for each value:

  TypeSpec helloWorld = composer.enumBuilder( "Roshambo" )
      .addModifiers( Modifier.PUBLIC )
      .addEnumConstant( "ROCK" )
      .addEnumConstant( "SCISSORS" )
      .addEnumConstant( "PAPER" )
      .build();

To generate this:

  public enum Roshambo {
      ROCK,

      SCISSORS,

      PAPER
  }

Fancy enums are supported, where the enum values override methods or call a superclass constructor. Here's a comprehensive example:

  TypeSpec helloWorld = composer.enumBuilder( "Roshambo" )
      .addModifiers( Modifier.PUBLIC )
      .addEnumConstant( "ROCK", composer.anonymousClassBuilder( "$S", "fist" )
          .addMethod( composer.methodBuilder( "toString" )
              .addAnnotation( Override.class )
              .addModifiers( Modifier.PUBLIC )
              .addStatement( "return $S", "avalanche!" )
              .returns( String.class )
              .build() )
          .build() )
      .addEnumConstant( "SCISSORS", composer.anonymousClassBuilder( "$S", "peace" )
          .build() )
      .addEnumConstant( "PAPER", composer.anonymousClassBuilder( "$S", "flat" )
          .build() )
      .addField( String.class, "handsign", Modifier.PRIVATE, Modifier.FINAL )
      .addMethod( composer.constructorBuilder()
          .addParameter( String.class, "handsign" )
          .addStatement( "this.$N = $N", "handsign", "handsign" )
          .build() )
      .build();

Which generates this:

  public enum Roshambo {
      ROCK("fist") {
          @Override
          public String toString() {
              return "avalanche!";
          }
      },

      SCISSORS("peace"),

      PAPER("flat");

      private final String handsign;

      Roshambo(String handsign) {
          this.handsign = handsign;
      }
  }

Anonymous Inner Classes

In the enum code above, we used TypeSpec.anonymousClassBuilder() to create an anonymous inner class. This can also be used in code blocks. They are values that can be referenced with $L:

  TypeSpec comparator = composer.anonymousClassBuilder( "" )
      .addSuperinterface( ParameterizedTypeName.get( Comparator.class, String.class ) )
      .addMethod( composer.methodBuilder( "compare" )
          .addAnnotation( Override.class )#
          .addModifiers( Modifier.PUBLIC )#
          .addParameter( String.class, "a" )
          .addParameter( String.class, "b" )
          .returns( int.class )
          .addStatement( "return $N.length() - $N.length()", "a", "b" )
          .build() )
      .build();

  TypeSpec helloWorld = TypeSpec.classBuilder( "HelloWorld" )
      .addMethod( composer.methodBuilder( "sortByLength" )
          .addParameter( ParameterizedTypeName.get( List.class, String.class ), "strings" )
          .addStatement( "$T.sort($N, $L)", Collections.class, "strings", comparator )
          .build() )
      .build();

This generates a method that contains a class that contains a method:

  void sortByLength(List<String> strings) {
      Collections.sort(strings, new Comparator<String>() {
          @Override
          public int compare(String a, String b) {
              return a.length() - b.length();
          }
      });
  }

One particularly tricky part of defining anonymous inner classes is the arguments to the superclass constructor. In the above code we're passing the empty string for no arguments: composer.anonymousClassBuilder( "" ). To pass different parameters use JavaComposer's code block syntax with commas to separate arguments.

Annotations

Simple annotations are easy:

  MethodSpec toString = composer.methodBuilder( "toString" )
      .addAnnotation( Override.class )
      .returns( String.class )
      .addModifiers( Modifier.PUBLIC )
      .addStatement( "return $S", "Hoverboard" )
      .build();

Which generates this method with an @Override annotation:

  @Override
  public String toString() {
      return "Hoverboard";
  }

Use JavaComposer.annotationBuilder() to set properties on annotations:

  MethodSpec logRecord = composer.methodBuilder( "recordEvent" )
      .addModifiers( Modifier.PUBLIC, Modifier.ABSTRACT )
      .addAnnotation( composer.annotationBuilder( Headers.class )
          .addMember( "accept", "$S", "application/json; charset=utf-8" )
          .addMember( "userAgent", "$S", "Square Cash" )
          .build() )
      .addParameter( LogRecord.class, "logRecord" )
      .returns( LogReceipt.class )
      .build();

Which generates this annotation with accept and userAgent properties:

  @Headers(
      accept = "application/json; charset=utf-8",
      userAgent = "Square Cash"
  )
  LogReceipt recordEvent(LogRecord logRecord);

When you get fancy, annotation values can be annotations themselves. Use $L for embedded annotations:

MethodSpec logRecord = composer.methodBuilder( "recordEvent" )
      .addModifiers( Modifier.PUBLIC, Modifier.ABSTRACT )
      .addAnnotation( composer.annotationBuilder( HeaderList.class )
          .addMember( "value", "$L", composer.annotationBuilder( Header.class )
              .addMember( "name", "$S", "Accept" )
              .addMember( "value", "$S", "application/json; charset=utf-8" )
              .build() )
          .addMember( "value", "$L", composer.annotationBuilder( Header.class )
              .addMember( "name", "$S", "User-Agent" )
              .addMember( "value", "$S", "Square Cash" )
              .build() )
          .build() )
      .addParameter( LogRecord.class, "logRecord" )
      .returns( LogReceipt.class )
      .build();

Which generates this:

 @HeaderList({
      @Header(name = "Accept", value = "application/json; charset=utf-8"),
      @Header(name = "User-Agent", value = "Square Cash")
  })
  LogReceipt recordEvent(LogRecord logRecord);

Note that you can call addMember() multiple times with the same property name to populate a list of values for that property.

Javadoc

Fields, methods and types can be documented with Javadoc (in fact, they should be documented, even for generated code):

  MethodSpec dismiss = composer.methodBuilder( "dismiss" )
      .addJavadoc( """
                   Hides {@code message} from the caller's history. Other
                   participants in the conversation will continue to see the
                   message in their own history unless they also delete it.
                   """ )
      .addJavadoc( "\n" )
      .addJavadoc( """
                   <p>Use {@link #delete($T)} to delete the entire
                   conversation for all participants.
                   """, Conversation.class )
      .addModifiers( Modifier.PUBLIC, Modifier.ABSTRACT )
      .addParameter( Message.class, "message" )
      .build();

Which generates this:

  /**
   * Hides {@code message} from the caller's history. Other
   * participants in the conversation will continue to see the
   * message in their own history unless they also delete it.
   *
   * <p>Use {@link #delete(Conversation)} to delete the entire
   * conversation for all participants. */
   void dismiss(Message message);

Use $T when referencing types in JavaDoc to get automatic imports.

Lambda

LambdaSpec provides a basic API for the generation of lambda expressions.

The code

  ParameterSpec parameter = ParameterSpec.of( VOID, "s" );
   LambdaSpec lambda = LambdaSpec.builder()
      .addParameter( parameter )
      .addCode( "upperCase( $N )" , parameter )
      .build();

      CodeBlock codeBlock = CodeBlock.of( "$T<$T> function = $L;", UnaryOperator.class, String.class, candidate );

generates

  java.util.function.UnaryOperator<java.lang.String> function = s -> upperCase( s );
.

Layout

You may have noticed that the layout for the samples of generating code looks different from that of generated code: the first was formatted like the code for the Foundation Library, while the layout for the second was that used by the original JavaPoet code.

When creating a new JavaComposer you can specify a Layout with the constructor that determines the look of the output, generated by JavaFile.

Currently, this implementation supports the following layouts:

LAYOUT_JAVAPOET
The format as used by the original JavaPoet software from Square,Inc.
LAYOUT_FOUNDATION
The format as used by the Foundation Library

Debug Output

In particular when generating complex code, it is not immediately obvious which statement of the generator was responsible for which part of the output.

To help with the debugging of generated code, it is possible to prepend each component of the generated code with the name of the class and the line number where the method creating that component was called.

This feature is activated when the JavaComposer is created.

License

The original code is Copyright © 2015 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied. See the License for the specific language governing permissions and limitations under the License.

The modification for the Foundation version and the amendments are Copyright © 2018 by Thomas Thrien, tquadrat.org.

Open Issues (The ToDo List):
  • 2021-01-05 – An implementation for the new record type is needed. At 2021-02-14, the implementation is mostly done, only the parameterless constructor is missing.
  • 2021-01-05 – The modifiers sealed and non-sealed needs to be implemented, together with the permits keyword.
  • 2021-01-05 – How do we generate a package-info.java file?
  • 2021-01-05 – How do we generate a module-info.java file?
  • 2021-01-05 – Can we use the new switch statement for generated code?
  • 2021-01-09 – Add the suppressable warnings from IntelliJ IDEA to the enum class SuppressableWarnings.
  • 2021-01-09 – Add the missing suppressable warnings from the IntelliJ IDEA list.
  • 2021-01-18 – Enhance the layouts that it will allow the generation of code that is fully Foundation compliant.
  • 2021-01-18 – Remove the deprecated methods and classes once the implementation of JavaComposer is done. This also requires the adjustment of the existing tests.
  • 2021-01-20 – Remove the use of the deprecated AnnotationSpec APIs.
  • 2021-02-02 – Consolidate the exceptions thrown by the JavaComposer code; currently, that is a mixture of ValidationException, IllegalArgumentException, NullArgumentException and IllegalStateException. At least IllegalStateException might be obsolete.
  • 2021-04-02 – Validate the generated Javadocs
  • 2023-03-02 – Add the capability to generate Compact Constructors for records. Refer to https://blogs.oracle.com/javamagazine/post/java-records-constructor-methods-inheritance
  • 2023-03-06 – Fix the broken @Option for Collections