KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > inject > Binder


1 /*
2  * Copyright (C) 2007 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;
18
19 import com.google.inject.binder.AnnotatedBindingBuilder;
20 import com.google.inject.binder.ConstantBindingBuilder;
21 import com.google.inject.binder.LinkedBindingBuilder;
22 import com.google.inject.binder.AnnotatedConstantBindingBuilder;
23 import com.google.inject.matcher.Matcher;
24 import java.lang.annotation.Annotation JavaDoc;
25 import java.lang.reflect.Method JavaDoc;
26 import org.aopalliance.intercept.MethodInterceptor;
27
28 /**
29  * Collects configuration information (primarily <i>bindings</i>) which will be
30  * used to create an {@link Injector}. Guice provides this object to your
31  * application's {@link Module}s so they may each contribute
32  * their own bindings.
33  *
34  * <p>The bindings contributed by {@code Module}s define how the {@code
35  * Injector} resolves dependencies. A {@link Key} consisting of a type
36  * and optional annotation uniquely identifies a binding within an {@code
37  * Injector}.
38  *
39  * <p>You may bind from a key to:
40  *
41  * <ul>
42  * <li>Another binding, which this binding's key is now "aliased to"
43  * <li>Another binding, which references a {@link Provider} for this key
44  * <li>A preconstructed instance
45  * <li>A preconstructed instance which should be used as the {@link Provider}
46  * for this binding
47  * </ul>
48  *
49  * <p>In addition, a binding may have an associated scope, such as
50  * {@link Scopes#SINGLETON}, and singleton bindings may specify eager or lazy
51  * initialization.
52  *
53  * <p>See the users' guide appendix, "How the Injector resolves injection
54  * requests," to better understand binding resolution.
55  *
56  * <p>After an {@code Injector} has been created, its bindings may be
57  * examined using methods like {@link Injector#getBinding(Key)}, but this
58  * read-only {@link Binding} type is not used when <i>creating</i> the
59  * bindings.
60  */

61 public interface Binder {
62
63   /**
64    * Binds a method interceptor to methods matched by class and method
65    * matchers.
66    *
67    * @param classMatcher matches classes the interceptor should apply to. For
68    * example: {@code only(Runnable.class)}.
69    * @param methodMatcher matches methods the interceptor should apply to. For
70    * example: {@code annotatedWith(Transactional.class)}.
71    * @param interceptors to bind
72    */

73   void bindInterceptor(Matcher<? super Class JavaDoc<?>> classMatcher,
74       Matcher<? super Method JavaDoc> methodMatcher, MethodInterceptor... interceptors);
75
76   /**
77    * Binds a scope to an annotation.
78    */

79   void bindScope(Class JavaDoc<? extends Annotation JavaDoc> annotationType, Scope scope);
80
81   /**
82    * Creates a binding to a key.
83    */

84   <T> LinkedBindingBuilder<T> bind(Key<T> key);
85
86   /**
87    * Creates a binding to a type.
88    */

89   <T> AnnotatedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);
90
91   /**
92    * Creates a binding to a type.
93    */

94   <T> AnnotatedBindingBuilder<T> bind(Class JavaDoc<T> type);
95
96   /**
97    * Binds a constant value to an annotation.
98    */

99   AnnotatedConstantBindingBuilder bindConstant();
100
101   /**
102    * Upon successful creation, the {@link Injector} will inject static fields
103    * and methods in the given classes.
104    *
105    * @param types for which static members will be injected
106    */

107   void requestStaticInjection(Class JavaDoc<?>... types);
108
109   /**
110    * Uses the given module to configure more bindings.
111    */

112   void install(Module module);
113
114   /**
115    * Gets the current stage.
116    */

117   Stage currentStage();
118
119   /**
120    * Records an error message which will be presented to the user at a later
121    * time. Unlike throwing an exception, this enable us to continue
122    * configuring the Injector and discover more errors. Uses {@link
123    * String#format(String, Object[])} to insert the arguments into the
124    * message.
125    */

126   void addError(String JavaDoc message, Object JavaDoc... arguments);
127
128   /**
129    * Records an exception, the full details of which will be logged, and the
130    * message of which will be presented to the user at a later
131    * time. If your Module calls something that you worry may fail, you should
132    * catch the exception and pass it into this.
133    */

134   void addError(Throwable JavaDoc t);
135 }
136
Popular Tags