1 /* 2 * Copyright (C) 2017 The Dagger Authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package dagger.spi; 18 19 import dagger.model.BindingGraph; 20 import java.util.Collections; 21 import java.util.Map; 22 import java.util.Set; 23 import javax.annotation.processing.Filer; 24 import javax.annotation.processing.Messager; 25 import javax.lang.model.util.Elements; 26 import javax.lang.model.util.Types; 27 28 /** 29 * A pluggable visitor for {@link BindingGraph}. 30 * 31 * <p>Note: This is still experimental and will change. 32 */ 33 public interface BindingGraphPlugin { 34 /** 35 * Called once for each valid root binding graph encountered by the Dagger processor. May report 36 * diagnostics using {@code diagnosticReporter}. 37 */ visitGraph(BindingGraph bindingGraph, DiagnosticReporter diagnosticReporter)38 void visitGraph(BindingGraph bindingGraph, DiagnosticReporter diagnosticReporter); 39 40 /** 41 * Initializes this plugin with a {@link Filer} that it can use to write Java or other files based 42 * on the binding graph. This will be called once per instance of this plugin, before any graph is 43 * {@linkplain #visitGraph(BindingGraph, DiagnosticReporter) visited}. 44 * 45 * @see javax.annotation.processing.ProcessingEnvironment#getFiler() 46 */ initFiler(Filer filer)47 default void initFiler(Filer filer) {} 48 49 /** 50 * Initializes this plugin with a {@link Types} instance. This will be called once per instance of 51 * this plugin, before any graph is {@linkplain #visitGraph(BindingGraph, DiagnosticReporter) 52 * visited}. 53 * 54 * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils() 55 */ initTypes(Types types)56 default void initTypes(Types types) {} 57 58 /** 59 * Initializes this plugin with a {@link Elements} instance. This will be called once per instance 60 * of this plugin, before any graph is {@linkplain #visitGraph(BindingGraph, DiagnosticReporter) 61 * visited}. 62 * 63 * @see javax.annotation.processing.ProcessingEnvironment#getElementUtils() 64 */ initElements(Elements elements)65 default void initElements(Elements elements) {} 66 67 /** 68 * Initializes this plugin with a filtered view of the options passed on the {@code javac} 69 * command-line for all keys from {@link #supportedOptions()}. This will be called once per 70 * instance of this plugin, before any graph is {@linkplain #visitGraph(BindingGraph, 71 * DiagnosticReporter) visited}. 72 * 73 * @see javax.annotation.processing.ProcessingEnvironment#getOptions() 74 */ initOptions(Map<String, String> options)75 default void initOptions(Map<String, String> options) {} 76 77 /** 78 * Returns the annotation-processing options that this plugin uses to configure behavior. 79 * 80 * @see javax.annotation.processing.Processor#getSupportedOptions() 81 */ supportedOptions()82 default Set<String> supportedOptions() { 83 return Collections.emptySet(); 84 } 85 86 /** 87 * A distinguishing name of the plugin that will be used in diagnostics printed to the {@link 88 * Messager}. By default, the {@linkplain Class#getCanonicalName() fully qualified name} of the 89 * plugin is used. 90 */ pluginName()91 default String pluginName() { 92 return getClass().getCanonicalName(); 93 } 94 95 /** 96 * Perform any extra work after the plugin finished all its visiting. This will be called once per 97 * instance of this plugin, after all graphs were {@linkplain #visitGraph(BindingGraph, 98 * DiagnosticReporter) visited} 99 */ onPluginEnd()100 default void onPluginEnd() {} 101 } 102