一、 检查合法性
接着上一篇文章,继续对process()方法进行分析。在parseBindView方法中,先做了一次检查,如下:
// Start by verifying common generated code restrictions.
boolean hasError = isInaccessibleViaGeneratedCode(BindView.class, "fields", element)
|| isBindingInWrongPackage(BindView.class, element);
那么就先来看看isInaccessibleViaGeneratedCode.
isInaccessibleViaGeneratedCode
private boolean isInaccessibleViaGeneratedCode(Class<? extends Annotation> annotationClass,
String targetThing, Element element) {
boolean hasError = false;
// 得到父节点
TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();
// 判断修饰符,如果为private 或者 static, 则会抛出异常
// Verify method modifiers.
Set<Modifier> modifiers = element.getModifiers();
if (modifiers.contains(PRIVATE) || modifiers.contains(STATIC)) {
error(element, "@%s %s must not be private or static. (%s.%s)",
annotationClass.getSimpleName(), targetThing, enclosingElement.getQualifiedName(),
element.getSimpleName());
hasError = true;
}
// 判断父节点的类型是否为 class, 如果不是,会抛出异常
// Verify containing type.
if (enclosingElement.getKind() != CLASS) {
error(enclosingElement, "@%s %s may only be contained in classes. (%s.%s)",
annotationClass.getSimpleName(), targetThing, enclosingElement.getQualifiedName(),
element.getSimpleName());
hasError = true;
}
// 判断父节点是否被private修饰,如果使用了private,会抛出异常
// Verify containing class visibility is not private.
if (enclosingElement.getModifiers().contains(PRIVATE)) {
error(enclosingElement, "@%s %s may not be contained in private classes. (%s.%s)",
annotationClass.getSimpleName(), targetThing, enclosingElement.getQualifiedName(),
element.getSimpleName());
hasError = true;
}
return hasError;
}
上面的代码已经注释清楚了,再此强调一下:在使用BindView注解时,被注解的元素不能用private 或者 static修饰。
然后来看isBindingInWrongPackage方法:
isBindingInWrongPackage
private boolean isBindingInWrongPackage(Class<? extends Annotation> annotationClass,
Element element) {
TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();
String qualifiedName = enclosingElement.getQualifiedName().toString();
if (qualifiedName.startsWith("android.")) {
error(element, "@%s-annotated class incorrectly in Android framework package. (%s)",
annotationClass.getSimpleName(), qualifiedName);
return true;
}
if (qualifiedName.startsWith("java.")) {
error(element, "@%s-annotated class incorrectly in Java framework package. (%s)",
annotationClass.getSimpleName(), qualifiedName);
return true;
}
return false;
}
这里也就是说不能在以android 或者 java 这种源码SDK中使用。
至此,用户合法性的检测到此就完了。接下来看创建BindingSet实例。
二、缓存
在获取id之后,有这么一段代码:
BindingSet.Builder builder = builderMap.get(enclosingElement);
if (builder != null) {
String existingBindingName = builder.findExistingBindingName(getId(id));
if (existingBindingName != null) {
error(element, "Attempt to use @%s for an already bound ID %d on '%s'. (%s.%s)",
BindView.class.getSimpleName(), id, existingBindingName,
enclosingElement.getQualifiedName(), element.getSimpleName());
return;
}
} else {
builder = getOrCreateBindingBuilder(builderMap, enclosingElement);
}
如果builder 不为空,直接通过id获取existingBindingName, 如果existingBindingName 不为空,则抛出异常,这里的意思是 同一个ID不能绑定多次。
如果builder 为空,则直接调用getOrCreateBindingBuilder 创建并返回,下面看看这个方法。
getOrCreateBindingBuilder
private BindingSet.Builder getOrCreateBindingBuilder(
Map<TypeElement, BindingSet.Builder> builderMap, TypeElement enclosingElement) {
BindingSet.Builder builder = builderMap.get(enclosingElement);
if (builder == null) {
builder = BindingSet.newBuilder(enclosingElement);
builderMap.put(enclosingElement, builder);
}
return builder;
}
static Builder newBuilder(TypeElement enclosingElement) {
TypeMirror typeMirror = enclosingElement.asType();
boolean isView = isSubtypeOfType(typeMirror, VIEW_TYPE);
boolean isActivity = isSubtypeOfType(typeMirror, ACTIVITY_TYPE);
boolean isDialog = isSubtypeOfType(typeMirror, DIALOG_TYPE);
TypeName targetType = TypeName.get(typeMirror);
if (targetType instanceof ParameterizedTypeName) {
targetType = ((ParameterizedTypeName) targetType).rawType;
}
// 获取父节点所在的包名
String packageName = getPackage(enclosingElement).getQualifiedName().toString();
// 获取类名
String className = enclosingElement.getQualifiedName().toString().substring(
packageName.length() + 1).replace('.', '$');
// 根据包名称和类名称 获取bindingClassName, 并加上“_ViewBinding”后缀
ClassName bindingClassName = ClassName.get(packageName, className + "_ViewBinding");
// 是否是 final 类
boolean isFinal = enclosingElement.getModifiers().contains(Modifier.FINAL);
// 创建BindingClass实例并加入集合中
return new Builder(targetType, bindingClassName, isFinal, isView, isActivity, isDialog);
}
注释已经写的很清楚了,继续看parseBindView方法;
String name = element.getSimpleName().toString();
TypeName type = TypeName.get(elementType);
boolean required = isFieldRequired(element);
builder.addField(getId(id), new FieldViewBinding(name, type, required));
举个例子;
@BindView(R.id.tv)
TextView tv;
name 就是这里的 tv ,type 也就是类型的名字 TextView. required 是否为空, 然后创建FieldViewBinding, 添加到bindingSet中的成员变量的实体的集合中,方便生成java源文件也就是xxxxx_ViewBinding文件的成员变量的初始化.
以上只是分析了BindView注解,其他注解和这类似。 至此,process方法的第一个功能--收集信息已经分析完了。
三、OnClick 注解分析
由于OnClick注解一般用于方法上,有别于BindView使用在成员变量上,所以还是对它做个分析吧。先看源码:
// Process each annotation that corresponds to a listener.
for (Class<? extends Annotation> listener : LISTENERS) {
findAndParseListener(env, listener, builderMap, erasedTargetNames);
}
可能你发现这里的LISTENERS是什么鬼!其实这是butterknife支持的注解集合。
private static final List<Class<? extends Annotation>> LISTENERS = Arrays.asList(//
OnCheckedChanged.class, //
OnClick.class, //
OnEditorAction.class, //
OnFocusChange.class, //
OnItemClick.class, //
OnItemLongClick.class, //
OnItemSelected.class, //
OnLongClick.class, //
OnPageChange.class, //
OnTextChanged.class, //
OnTouch.class //
);
我们在前面说到所有的注解都通过getSupportedAnnotationTypes获取,这里也不例外,看源码:
@Override public Set<String> getSupportedAnnotationTypes() {
Set<String> types = new LinkedHashSet<>();
for (Class<? extends Annotation> annotation : getSupportedAnnotations()) {
types.add(annotation.getCanonicalName());
}
return types;
}
private Set<Class<? extends Annotation>> getSupportedAnnotations() {
Set<Class<? extends Annotation>> annotations = new LinkedHashSet<>();
annotations.add(BindArray.class);
annotations.add(BindBitmap.class);
annotations.add(BindBool.class);
annotations.add(BindColor.class);
annotations.add(BindDimen.class);
annotations.add(BindDrawable.class);
annotations.add(BindFloat.class);
annotations.add(BindInt.class);
annotations.add(BindString.class);
annotations.add(BindView.class);
annotations.add(BindViews.class);
annotations.addAll(LISTENERS);
return annotations;
}
重点来看findAndParseListener这个方法。
private void findAndParseListener(RoundEnvironment env,
Class<? extends Annotation> annotationClass,
Map<TypeElement, BindingSet.Builder> builderMap, Set<TypeElement> erasedTargetNames) {
for (Element element : env.getElementsAnnotatedWith(annotationClass)) {
// 检查合法性
if (!SuperficialValidation.validateElement(element)) continue;
try {
// 解析注解
parseListenerAnnotation(annotationClass, element, builderMap, erasedTargetNames);
} catch (Exception e) {
StringWriter stackTrace = new StringWriter();
e.printStackTrace(new PrintWriter(stackTrace));
error(element, "Unable to generate view binder for @%s.\n\n%s",
annotationClass.getSimpleName(), stackTrace.toString());
}
}
}
看一下parseListenerAnnotation方法;这个方法比较长,看源码:
private void parseListenerAnnotation(Class<? extends Annotation> annotationClass, Element element,
Map<TypeElement, BindingSet.Builder> builderMap, Set<TypeElement> erasedTargetNames)
throws Exception {
// This should be guarded by the annotation's @Target but it's worth a check for safe casting.
// 由于事件注解一般用于方法上,所有这里必须是方法类型,就是ExecutableElement
if (!(element instanceof ExecutableElement) || element.getKind() != METHOD) {
throw new IllegalStateException(
String.format("@%s annotation must be on a method.", annotationClass.getSimpleName()));
}
ExecutableElement executableElement = (ExecutableElement) element;
// 获取父节点
TypeElement enclosingElement = (TypeElement) element.getEnclosingElement();
// Assemble information on the method.
// 获取注解信息
Annotation annotation = element.getAnnotation(annotationClass);
// 获取注解value方法,这里要求是数组,否则会抛异常
Method annotationValue = annotationClass.getDeclaredMethod("value");
if (annotationValue.getReturnType() != int[].class) {
throw new IllegalStateException(
String.format("@%s annotation value() type not int[].", annotationClass));
}
// 反射获取注解value的值
int[] ids = (int[]) annotationValue.invoke(annotation);
// 获取方法名
String name = executableElement.getSimpleName().toString();
boolean required = isListenerRequired(executableElement);
// Verify that the method and its containing class are accessible via generated code.
// 和分析BindView时一样,这里也会检查修饰符 以及 包名
boolean hasError = isInaccessibleViaGeneratedCode(annotationClass, "methods", element);
hasError |= isBindingInWrongPackage(annotationClass, element);
// 一个被注解的方法不能有相同的id 否则会抛出异常
Integer duplicateId = findDuplicate(ids);
if (duplicateId != null) {
error(element, "@%s annotation for method contains duplicate ID %d. (%s.%s)",
annotationClass.getSimpleName(), duplicateId, enclosingElement.getQualifiedName(),
element.getSimpleName());
hasError = true;
}
//获取该注解的ListenerClass.class注解, 这里后面再做解释。
ListenerClass listener = annotationClass.getAnnotation(ListenerClass.class);
if (listener == null) {
throw new IllegalStateException(String.format("No @%s defined on @%s.", ListenerClass.class.getSimpleName(), annotationClass.getSimpleName()));
}
// 检查ID 的合法性
for (int id : ids) {
if (id == NO_ID.value) {
if (ids.length == 1) {
if (!required) {
error(element, "ID-free binding must not be annotated with @Optional. (%s.%s)", enclosingElement.getQualifiedName(), element.getSimpleName());
hasError = true;
}
} else {
error(element, "@%s annotation contains invalid ID %d. (%s.%s)", annotationClass.getSimpleName(), id, enclosingElement.getQualifiedName(), element.getSimpleName());
hasError = true;
}
}
}
ListenerMethod method;
// 获取实现的方法
ListenerMethod[] methods = listener.method();
if (methods.length > 1) {
throw new IllegalStateException(String.format("Multiple listener methods specified on @%s.", annotationClass.getSimpleName()));
} else if (methods.length == 1) {
// 如果有method属性值即这种onItemClick,则callbacks必须为空,也就是2者不能同时使用
if (listener.callbacks() != ListenerClass.NONE.class) {
throw new IllegalStateException(String.format("Both method() and callback() defined on @%s.", annotationClass.getSimpleName()));
}
method = methods[0];
} else {
// 否则使用callback
//反射ListenerClass注解中的callback方法
Method annotationCallback = annotationClass.getDeclaredMethod("callback");
Enum<?> callback = (Enum<?>) annotationCallback.invoke(annotation);
Field callbackField = callback.getDeclaringClass().getField(callback.name());
method = callbackField.getAnnotation(ListenerMethod.class);
//如果没有ListenerMethod.class注解 抛出异常,也就是说你使用了callback,则必须提供ListenerMethod.class注解
if (method == null) {
throw new IllegalStateException(String.format("No @%s defined on @%s's %s.%s.", ListenerMethod.class.getSimpleName(), annotationClass.getSimpleName(), callback.getDeclaringClass().getSimpleName(), callback.name()));
}
}
// Verify that the method has equal to or less than the number of parameters as the listener.
//检查方法的合法性,就是你使用的注解的方法的参数超过不能butterknife的参数的个数
List<? extends VariableElement> methodParameters = executableElement.getParameters();
if (methodParameters.size() > method.parameters().length) {
error(element, "@%s methods can have at most %s parameter(s). (%s.%s)", annotationClass.getSimpleName(), method.parameters().length, enclosingElement.getQualifiedName(), element.getSimpleName());
hasError = true;
}
// Verify method return type matches the listener.
//检查返回值,就是你使用的注解的方法的参数不能超过butterknife的参数的个数
TypeMirror returnType = executableElement.getReturnType();
if (returnType instanceof TypeVariable) {
TypeVariable typeVariable = (TypeVariable) returnType;
returnType = typeVariable.getUpperBound();
}
if (!returnType.toString().equals(method.returnType())) {
error(element, "@%s methods must have a '%s' return type. (%s.%s)", annotationClass.getSimpleName(), method.returnType(), enclosingElement.getQualifiedName(), element.getSimpleName());
hasError = true;
}
if (hasError) {
return;
}
// 下面都是方法参数的检查
Parameter[] parameters = Parameter.NONE;
if (!methodParameters.isEmpty()) {
parameters = new Parameter[methodParameters.size()];
BitSet methodParameterUsed = new BitSet(methodParameters.size());
String[] parameterTypes = method.parameters();
for (int i = 0; i < methodParameters.size(); i++) {
VariableElement methodParameter = methodParameters.get(i);
TypeMirror methodParameterType = methodParameter.asType();
if (methodParameterType instanceof TypeVariable) {
TypeVariable typeVariable = (TypeVariable) methodParameterType;
methodParameterType = typeVariable.getUpperBound();
}
for (int j = 0; j < parameterTypes.length; j++) {
if (methodParameterUsed.get(j)) {
continue;
}
if ((isSubtypeOfType(methodParameterType, parameterTypes[j]) && isSubtypeOfType(methodParameterType, VIEW_TYPE)) || isTypeEqual(methodParameterType, parameterTypes[j]) || isInterface(methodParameterType)) {
parameters[i] = new Parameter(j, TypeName.get(methodParameterType));
methodParameterUsed.set(j);
break;
}
}
if (parameters[i] == null) {
StringBuilder builder = new StringBuilder();
builder.append("Unable to match @")
.append(annotationClass.getSimpleName())
.append(" method arguments. (").append(enclosingElement.getQualifiedName()).append('.').append(element.getSimpleName()).append(')');
for (int j = 0; j < parameters.length; j++) {
Parameter parameter = parameters[j];
builder.append("\n\n Parameter #").append(j + 1).append(": ").append(methodParameters.get(j).asType().toString()).append("\n ");
if (parameter == null) {
builder.append("did not match any listener parameters");
} else {
builder.append("matched listener parameter #").append(parameter.getListenerPosition() + 1).append(": ").append(parameter.getType());
}
}
builder.append("\n\nMethods may have up to ").append(method.parameters().length).append(" parameter(s):\n");
for (String parameterType : method.parameters()) {
builder.append("\n ").append(parameterType);
}
builder.append("\n\nThese may be listed in any order but will be searched for from top to bottom.");
error(executableElement, builder.toString());
return;
}
}
}
// 最后构建MethodViewBinding 实体
MethodViewBinding binding = new MethodViewBinding(name, Arrays.asList(parameters), required);
BindingSet.Builder builder = getOrCreateBindingBuilder(builderMap, enclosingElement);
for (int id : ids) {
if (!builder.addMethod(getId(id), listener, method, binding)) {
// 将生成的实体加入到builder中
error(element, "Multiple listener methods with return value specified for ID %d. (%s.%s)", id, enclosingElement.getQualifiedName(), element.getSimpleName());
return;
}
}
// Add the type-erased version to the valid binding targets set.
erasedTargetNames.add(enclosingElement);
}
这个方法执行的步骤以上都注释说明了。来看看ListenerClass 和 ListenerMethod.
ListenerClass 和 ListenerMethod
/**
* Bind a method to an {@link OnClickListener OnClickListener} on the view for each ID specified.
* <pre><code>
* {@literal @}OnClick(R.id.example) void onClick() {
* Toast.makeText(this, "Clicked!", Toast.LENGTH_SHORT).show();
* }
* </code></pre>
* Any number of parameters from
* {@link OnClickListener#onClick(android.view.View) onClick} may be used on the
* method.
*
* @see OnClickListener
*/
@Target(METHOD)
@Retention(CLASS)
@ListenerClass(
targetType = "android.view.View",
setter = "setOnClickListener",
type = "butterknife.internal.DebouncingOnClickListener",
method = @ListenerMethod(
name = "doClick",
parameters = "android.view.View"
)
)
public @interface OnClick {
/** View IDs to which the method will be bound. */
@IdRes int[] value() default { View.NO_ID };
}
@Retention(RUNTIME) @Target(ANNOTATION_TYPE)
public @interface ListenerClass {
String targetType();
/** Name of the setter method on the {@linkplain #targetType() target type} for the listener. */
String setter();
/**
* Name of the method on the {@linkplain #targetType() target type} to remove the listener. If
* empty {@link #setter()} will be used by default.
*/
String remover() default "";
/** Fully-qualified class name of the listener type. */
String type();
/** Enum which declares the listener callback methods. Mutually exclusive to {@link #method()}. */
Class<? extends Enum<?>> callbacks() default NONE.class;
/**
* Method data for single-method listener callbacks. Mutually exclusive with {@link #callbacks()}
* and an error to specify more than one value.
*/
ListenerMethod[] method() default { };
/** Default value for {@link #callbacks()}. */
enum NONE { }
}
@Retention(RUNTIME) @Target(FIELD)
public @interface ListenerMethod {
/** Name of the listener method for which this annotation applies. */
String name();
/** List of method parameters. If the type is not a primitive it must be fully-qualified. */
String[] parameters() default { };
/** Primitive or fully-qualified return type of the listener method. May also be {@code void}. */
String returnType() default "void";
/** If {@link #returnType()} is not {@code void} this value is returned when no binding exists. */
String defaultReturn() default "null";
}
ListenerMethod 这个注解包含了方法的返回值,名字,参数; ListenerClass是set的那些方法属性,包含setter等。可以看到OnClick上设置的值就是为一个控件添加Click方法时使用的值。
至此,findAndParseTargets方法基本上也就算分析完了,至于其他注解,原理都是相似的,在此就不多做解释了,想详细了解其实现的还是自己研究源码吧。
好了,process方法的第一步收集信息到此走完了,既然收集到那么多信息,接下来就该用这些信息生成Java代码了。下篇文章就针对生成代码做分析。