註解與APT、JavaPoet

Android APT

註解處理工具(APT) +註解處理（AbstractProcess）+代碼處理（JavaPoet）+處理器註冊（AutoService）

 

javapoet官方

原文：https://github.com/square/javapoet

譯文：https://blog.csdn.net/crazy1235/article/details/51876192

 

JavaPoet

JavaPoet 是一個用來生成 .java源文件的Java API。

當作如註解或者數據庫模式、協議格式等事情時，生成源文件就比較有用處。

Example

以 HelloWorld 類爲例:

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

上面的代碼就是使用javapoet用下面的代碼進行生成的：

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);

經過MethodSpec類來建立一個」main」方法，並配置了修飾符、返回值類型、參數以及代碼語句。而後把這個main方法添加到 HelloWorld 類中，最後添加到 HelloWorld.java文件中。 
這個例子中，咱們將文件經過Sytem.out 進行輸出，可是一樣也可使用(JavaFile.toString()) 獲得string字符串，或者經過 (JavaPoet.writeTo()) 方法寫入到文件系統中。

Javadoc 中包括了完整的JavaPoet API, 咱們接着往下看。

Code & Control Flow

大多數JavaPoet的API使用的是簡單的不可變的Java對象。經過建造者模式，鏈式方法，可變參數是的API比較友好。JavaPoet提供了(TypeSpec)用於建立類或者接口，(FieldSpec)用來建立字段，(MethodSpec)用來建立方法和構造函數，(ParameterSpec)用來建立參數，(AnnotationSpec)用於建立註解。

可是若是沒有語句類，沒有語法結點數，能夠經過字符串來構建代碼塊：

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

生成的代碼以下:

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

人爲的輸入分號、換行和縮進是比較乏味的。因此JavaPoet提供了相關API使它變的容易。 
addStatement() 負責分號和換行，beginControlFlow() + endControlFlow() 須要一塊兒使用，提供換行符和縮進。

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

這個例子稍微有點差勁。生成的代碼以下：

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 = " + from + "; i < " + to + "; i++)") .addStatement("result = result " + op + " i") .endControlFlow() .addStatement("return result") .build(); }

調用computeRange("multiply10to20", 10, 20, "*")就生成以下代碼:

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

方法生成方法！JavaPoet生成的是源代碼而不是字節碼，因此能夠經過閱讀源碼確保正確。

$L for Literals

字符串鏈接的方法beginControlFlow() 和 addStatement是分散開的，操做較多。 
針對這個問題, JavaPoet 提供了一個語法可是有違String.format()語法. 經過 $L 來接受一個 literal 值。 這有點像 Formatter’s %s:

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 直接寫在輸出代碼中，沒有轉義。 它的類型能夠是字符串、primitives和一些接下來要說的JavaPoet類型。

$S for Strings

當輸出的代碼包含字符串的時候, 可使用 $S 表示一個 string。 下面的代碼包含三個方法，每一個方法返回本身的名字:

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) .build(); javaFile.writeTo(System.out); } private static MethodSpec whatsMyName(String name) { return MethodSpec.methodBuilder(name) .returns(String.class) .addStatement("return $S", name) .build(); }

輸出結果以下:

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

$T for Types

使用Java內置的類型會使代碼比較容易理解。JavaPoet極大的支持這些類型，經過 $T 進行映射，會自動import聲明。

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) .build(); javaFile.writeTo(System.out);

自動完成import聲明，生成代碼以下:

package com.example.helloworld; import java.util.Date; public final class HelloWorld { Date today() { return new Date(); } }

再舉一個類似的例子，可是應用了一個不存在的類：

ClassName hoverboard = ClassName.get("com.mattel", "Hoverboard"); MethodSpec today = MethodSpec.methodBuilder("tomorrow") .returns(hoverboard) .addStatement("return new $T()", hoverboard) .build();

類不存在，可是代碼是完整的:

package com.example.helloworld; import com.mattel.Hoverboard; public final class HelloWorld { Hoverboard tomorrow() { return new Hoverboard(); } }

ClassName 這個類很是重要, 當你使用JavaPoet的時候會頻繁的使用它。 
它能夠識別任何聲明類。具體看下面的例子:

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();

JavaPoet將每一種類型進行分解，並儘量的導入其聲明.

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

JavaPoet支持import static。它顯示的收集類型成員的名稱。例子以下:

...
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) .addStaticImport(hoverboard, "createNimbus") .addStaticImport(namedBoards, "*") .addStaticImport(Collections.class, "*") .build();

JavaPoet將會首先添加 import static 代碼塊進行配置，固然也須要導入其餘所需的類型引用。

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

使用 $N 能夠引用另一個經過名字生成的聲明。

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'); }

生成的代碼以下，在byteToHex()方法中經過$N來引用 hexDigit()方法做爲一個參數：

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();

Methods

上面的例子中的方法都有方法體。 使用 Modifiers.ABSTRACT 建立的方法是沒有方法體的。一般用來建立一個抽象類或接口。

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

生成以下代碼：

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

當執行修飾符的時。JavaPoet用的是 
javax.lang.model.element.Modifier類，這個類在android平臺上不可用. 這隻限制與生成代碼階段；輸出的代碼可運行在任何平臺上: JVMs, Android, 
and GWT。

方法可能會有參數，異常，可變參數，註釋，註解，類型變量和一個返回類型。這些均可以經過 MethodSpec.Builder 來進行配置。

Constructors

MethodSpec 也能夠用來建立構造函數:

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();

生成以下代碼:

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

多數狀況下，構造方法同普通方法同樣。當生成代碼時，構造函數會先於其餘方法生成。

Parameters

經過 ParameterSpec.builder() 能夠建立參數，或者直接調用 MethodSpec類的 addParameter() 方法添加參數：

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

雖然上面的代碼生成android 和 robot這兩個參數是不一樣的方式，可是輸出是同樣的：

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

當參數有註解(好比 @Nullable)的時候，經過擴展的 Builder 方式建立參數是比較方便的。

Fields

字段通參數同樣經過 build 方式建立:

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();

生成以下代碼:

public class HelloWorld { private final String android; private final String robot; }

通關 Builder 方式很容易生成帶註釋、註解或者初始化的字段。 
Field的初始化代碼以下：

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

生成代碼：

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

Interfaces

JavaPoet一樣能夠生成接口。注意接口的方法必須是 PUBLIC 
ABSTRACT 類型，接口的變量必須是 PUBLIC STATIC FINAL 類型。 
建立接口的時候必需要添加上這些修飾符。

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();

可是這些修飾符在生成的java文件中是找不到的。這些都是缺省值。

public interface HelloWorld { String ONLY_THING_THAT_IS_CONSTANT = "change"; void beep(); }

Enums

經過 enumBuilder 能夠建立枚舉類型, 調用 addEnumConstant() 可添加枚舉變量：

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

生成以下代碼:

public enum Roshambo { ROCK, SCISSORS, PAPER }

Fancy enums 也是支持的。

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

生成代碼:

public enum Roshambo { ROCK("fist") { @Override public void toString() { return "avalanche!"; } }, SCISSORS("peace"), PAPER("flat"); private final String handsign; Roshambo(String handsign) { this.handsign = handsign; } }

Anonymous Inner Classes

在上面的枚舉代碼彙總，使用了 Types.anonymousInnerClass()。匿名內部類也能夠在代碼塊中使用。 經過 $L 引用匿名內部類：

TypeSpec comparator = TypeSpec.anonymousClassBuilder("") .addSuperinterface(ParameterizedTypeName.get(Comparator.class, String.class)) .addMethod(MethodSpec.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(MethodSpec.methodBuilder("sortByLength") .addParameter(ParameterizedTypeName.get(List.class, String.class), "strings") .addStatement("$T.sort($N, $L)", Collections.class, "strings", comparator) .build()) .build();

生成的代碼包含一個類和一個方法：

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

定義匿名內部類的一個特別棘手的問題是參數的構造。在上面的代碼中咱們傳遞了不帶參數的空字符串。TypeSpec.anonymousClassBuilder("")。

Annotations

對方法添加註解很是簡單：

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

生成以下代碼：

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

經過 AnnotationSpec.builder() 能夠對註解設置屬性：

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

生成以下代碼：

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

註解一樣能夠註解其它的註解。經過 $L 進行引用：

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

生成以下代碼：

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

addMember() 能夠調用屢次。

Javadoc

變量方法和類均可以添加註釋:

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

生成以下：

/** * 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);

使用 $T 能夠自動導入類型的引用。

Download

下載最新的 the latest .jar

或者添加Maven依賴：

<dependency> <groupId>com.squareup</groupId> <artifactId>javapoet</artifactId> <version>1.7.0</version> </dependency>

或者Gradle依賴：

compile 'com.squareup:javapoet:1.7.0'

Snapshots of the development version are available in Sonatype’s snapshots repository.