1 /**
2  * Copyright (C) 2008 Google Inc.
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 com.google.inject.spi;
18 
19 import com.google.inject.Binder;
20 
21 /**
22  * A core component of a module or injector.
23  *
24  * <p>The elements of a module can be inspected, validated and rewritten. Use {@link
25  * Elements#getElements(com.google.inject.Module[]) Elements.getElements()} to read the elements
26  * from a module, and {@link Elements#getModule(Iterable) Elements.getModule()} to rewrite them.
27  * This can be used for static analysis and generation of Guice modules.
28  *
29  * <p>The elements of an injector can be inspected and exercised. Use {@link
30  * com.google.inject.Injector#getBindings Injector.getBindings()} to reflect on Guice injectors.
31  *
32  * @author jessewilson@google.com (Jesse Wilson)
33  * @author crazybob@google.com (Bob Lee)
34  * @since 2.0
35  */
36 public interface Element {
37 
38   /**
39    * Returns an arbitrary object containing information about the "place" where this element was
40    * configured. Used by Guice in the production of descriptive error messages.
41    *
42    * <p>Tools might specially handle types they know about; {@code StackTraceElement} is a good
43    * example. Tools should simply call {@code toString()} on the source object if the type is
44    * unfamiliar.
45    */
getSource()46   Object getSource();
47 
48   /**
49    * Accepts an element visitor. Invokes the visitor method specific to this element's type.
50    *
51    * @param visitor to call back on
52    */
acceptVisitor(ElementVisitor<T> visitor)53   <T> T acceptVisitor(ElementVisitor<T> visitor);
54 
55   /**
56    * Writes this module element to the given binder (optional operation).
57    *
58    * @param binder to apply configuration element to
59    * @throws UnsupportedOperationException if the {@code applyTo} method is not supported by this
60    *     element.
61    */
applyTo(Binder binder)62   void applyTo(Binder binder);
63 
64 }
65