用于生成.java 源文件的 Java API .zip

JavaPoet ======== `JavaPoet` is a Java API for generating `.java` source files. Source file generation can be useful when doing things such as annotation processing or interacting with metadata files (e.g., database schemas, protocol formats). By generating code, you eliminate the need to write boilerplate while also keeping a single source of truth for the metadata. Deprecated ---------- As of 2020-10-10, Square's JavaPoet project is deprecated. We're proud of our work but we haven't kept up on maintaining it. If you'd like an alternative that supports the latest Java language features, one option is [Palantir's JavaPoet](https://github.com/palantir/javapoet). To switch to that project, you'll need new Maven coordinates: ```diff - javapoet = { module = "com.squareup:javapoet", version = "1.13.0" } + javapoet = { module = "com.palantir.javapoet:javapoet", version = "0.5.0" } ``` And new imports: ``` sed -i "" \ 's/com.squareup.javapoet.\([A-Za-z]*\)/com.palantir.javapoet.\1/g' \ `find . -name "*.kt" -or -name "*.java"` ``` And you might need to track some API changes where fields became functions: ```diff - javaFile.packageName + javaFile.packageName() ``` ### Example Here's a (boring) `HelloWorld` class: ```java package com.example.helloworld; public final class HelloWorld { public static void main(String[] args) { System.out.println("Hello, JavaPoet!"); } } ``` And this is the (exciting) code to generate it with JavaPoet: ```java 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, JavaPoet!") .build(); TypeSpec helloWorld = TypeSpec.classBuilder("HelloWorld") .addModifiers(Modifier.PUBLIC, Modifier.FINAL) .addMethod(main) .build(); JavaFile javaFile = JavaFile.builder("com.example.helloworld", helloWorld) .build(); javaFile.writeTo(System.out); ``` To declare the main method, we've created a `MethodSpec` "main" configured with modifiers, return type, parameters and code statements. We add the 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()`). The [Javadoc][javadoc] catalogs the complete JavaPoet API, which we explore below. ### Code & Control Flow Most of JavaPoet's API uses plain old immutable Java objects. There's also builders, method chaining and varargs to make the API friendly. JavaPoet offers models for classes & interfaces (`TypeSpec`), fields (`FieldSpec`), methods & constructors (`MethodSpec`), parameters (`ParameterSpec`) and annotations (`AnnotationSpec`). But the _body_ of methods and constructors is not modeled. There's no expression class, no statement class or syntax tree nodes. Instead, JavaPoet uses strings for code blocks: ```java MethodSpec main = MethodSpec.methodBuilder("main") .addCode("" + "int total = 0;\n" + "for (int i = 0; i < 10; i++) {\n" + " total += i;\n" + "}\n") .build(); ``` Which generates this: ```java 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 JavaPoet offers APIs to make it easier. There's `addStatement()` which takes care of semicolons and newline, and `beginControlFlow()` + `endControlFlow()` which are used together for braces, newlines, and indentation: ```java 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: ```java private MethodSpec computeRange(String name, int from, int to, String op) { return 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(); } ``` And here's what we get when we call `computeRange("multiply10to20", 10, 20, "*")`: ```java int multiply10to20() { int result = 1; for (int i = 10; i < 20; i++) { result = result * i; } return result; } ``` Methods generating methods! And since JavaPoet generates source instead of bytecode, you can read through it to make sure it's right. Some control flow statements, such as `if/else`, can have unlimited control flow possibilities. You can handle those options using `nextControlFlow()`: ```java MethodSpec main = MethodSpec.methodBuilder("main") .addStatement("long now = $T.currentTimeMillis()", System.class) .beginControlFlow("if ($T.currentTimeMillis() < now)", System.class) .addStatement("$T.out.println($S)", System.class, "Time travelling, woo hoo!") .nextControlFlow("else if ($T.currentTimeMillis() == now)", System.class) .addStatement("$T.out.println($S)", System.class, "Time stood still!") .nextControlFlow("else") .addStatement("$T.out.println($S)", System.class, "Ok, time still moving forward") .endControlFlow() .build(); ``` Which generates: ```java void main() { long now = System.currentTimeMillis(); if (System.currentTimeMillis() < now) { System.out.println("Time travelling, woo hoo!"); } else if (System.currentTimeMillis() == now) { System.out.println("Time stood still!"); } else { System.out.println("Ok, time still moving forward"); } } ``` Catching exceptions using `try/catch` is also a use case for `nextControlFlow()`: ```java MethodSpec main = MethodSpec.methodBuilder("main") .beginControlFlow("try") .addStatement("throw new Exception($S)", "Failed") .nextControlFlow("catch ($T e)", Exception.class) .addStatement("throw new $T(e)", RuntimeException.class) .endControlFlow() .build(); ``` Which produces: ```java void main() { try { throw new Exception("Failed"); } catch (Exception e) { throw new RuntimeException(e); } } ``` ### $L for Literals The string-concatenation in calls to `beginControlFlow()` and `addStatement` is distracting. Too many operators. To address this, JavaPoet offers a syntax inspired-by but incompatible-with [`String.format()`][formatter]. It accepts **`$L`** to emit a **literal** value in the output. This works just like `Formatter`'s `%s`: ```java private MethodSpec computeRange(String name, int from, int to, String op) { return 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(); } ``` Literals are emitted directly to the output code with no escaping. Arguments for literals may be strings, primitives, and a few JavaPoet 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 3 methods, each of which returns its own name: ```java 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)