Author: limpbizkit
Date: Mon Mar 2 21:06:38 2009
New Revision: 894
Modified:
wiki/CreatingBindings.wiki
Log:
Edited wiki page through web user interface.
Modified: wiki/CreatingBindings.wiki
==============================================================================
--- wiki/CreatingBindings.wiki (original)
+++ wiki/CreatingBindings.wiki Mon Mar 2 21:06:38 2009
@@ -2,176 +2,4 @@
=Creating Bindings=
The injector's job is to assemble graphs of objects. You request an
instance of a given type, and it figures out what to build, resolves
dependencies, and wires everything together. To specify how dependencies
are resolved, configure your injector with bindings.
-To create bindings, extend `AbstractModule` and override its `configure`
method. In the method body, call `bind()` to specify each binding. These
methods are type checked so the compiler can report errors if you use the
wrong types. Once you've created your modules, pass them as arguments to
`Guice.createInjector()` to build an injector.
-
-
-==Linked Bindings==
-Linked bindings map a type to its implementation. This example maps the
interface `TransactionLog` to the implementation `DatabaseTransationLog`:
-{{{
-public class BillingModule extends AbstractModule {
- @Override
- protected void configure() {
- bind(TransactionLog.class).to(DatabaseTransactionLog.class);
- }
-}
-}}}
-Now, when you call `injector.getInstance(TransactionLog.class)`, or when
the injector encounters a dependency on `TransactionLog`, it will use a
`DatabaseTransactionLog`. Link from a type to any of its subtypes, such as
an implementing class or an extending class. You can even link the concrete
`DatabaseTransactionLog` class to a subclass:
-{{{
-
bind(DatabaseTransactionLog.class).to(MySqlDatabaseTransactionLog.class);
-}}}
-Linked bindings can also be chained:
-{{{
-public class BillingModule extends AbstractModule {
- @Override
- protected void configure() {
- bind(TransactionLog.class).to(DatabaseTransactionLog.class);
-
bind(DatabaseTransactionLog.class).to(MySqlDatabaseTransactionLog.class);
- }
-}
-}}}
-In this case, when a `TransactionLog` is requested, the injector will
return a `MySqlDatabaseTransactionLog`.
-
-
-==Binding Annotations==
-Occasionally you'll want multiple bindings for a same type. For example,
you might want both a PayPal credit card processor and a Google Checkout
processor. To enable this, bindings support an optional *binding
annotation*. The annotation and type together uniquely identify a binding.
This pair is called a *key*.
-
-Defining a binding annotation requires two lines of code plus several
imports. Put this in its own `.java` file or inside the type that it
annotates.
-{{{
-package example.pizza;
-
-import com.google.inject.BindingAnnotation;
-import java.lang.annotation.Target;
-import java.lang.annotation.Retention;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
-import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.ElementType.FIELD;
-import static java.lang.annotation.ElementType.METHOD;
-
-...@bindingannotation @Target({ FIELD, PARAMETER, METHOD })
@Retention(RUNTIME)
-public @interface PayPal {}
-}}}
-You don't need to understand all of these meta-annotations, but if you're
curious:
- * `...@bindingannotation` tells Guice that this is a binding annotation.
Guice will produce an error if ever multiple binding annotations apply to
the same member.
- * `...@target({FIELD, PARAMETER, METHOD})` is a courtesy to your users. It
prevents `...@paypal` from being accidentally being applied where it serves no
purpose.
- * `...@retention(RUNTIME)` makes the annotation available at runtime.
-
-To depend on the annotated binding, apply the annotation to the injected
parameter:
-{{{
-public class RealBillingService implements BillingService {
-
- @Inject
- public RealBillingService(@PayPal CreditCardProcessor processor,
- TransactionLog transactionLog) {
- ...
- }
-}}}
-Lastly we create a binding that uses the annotation. This uses the
optional `annotatedWith` clause in the `bind()` statement:
-{{{
- bind(CreditCardProcessor.class)
- .annotatedWith(PayPal.class)
- .to(PayPalCreditCardProcessor.class);
-}}}
-
-
-...@named===
-Guice comes with a built-in binding annotation `...@named` that uses a string:
-{{{
-public class RealBillingService implements BillingService {
-
- @Inject
- public RealBillingService(@Named("Checkout") CreditCardProcessor
processor,
- TransactionLog transactionLog) {
- ...
- }
-}}}
-To bind a specific name, use `Names.named()` to create an instance to pass
to `annotatedWith`:
-{{{
- bind(CreditCardProcessor.class)
- .annotatedWith(Names.named("Checkout"))
- .to(PayPalCreditCardProcessor.class);
-}}}
-Since the compiler can't check the string, we recommend using `...@named`
sparingly.
-
-
-===Binding Annotations with Attributes===
-Guice supports binding annotations that have attribute values. In the rare
case that you need such an annotation:
- # Create the annotation `...@interface`.
- # Create a class that implements the annotation interface. Follow the
guidelines for `equals()` and `hashCode()` specified in the
[http://java.sun.com/javase/6/docs/api/java/lang/annotation/Annotation.html
Annotation Javadoc]. Pass an instance of this to the `annotatedWith()`
binding clause.
-
-
-==Instance Bindings==
-You can bind a type to a specific instance of that type. This is usually
only useful only for objects that don't have dependencies of their own,
such as value objects:
-{{{
- bind(String.class)
- .annotatedWith(Names.named("JDBC URL"))
- .toInstance("jdbc:mysql://localhost/pizza");
- bind(Integer.class)
- .annotatedWith(Names.named("login timeout seconds"))
- .toInstance(10);
-}}}
-Avoid using `.toInstance` with objects that are complicated to create,
since it can slow down application startup. You can use an `...@provides`
method instead.
-
-
-...@provides Methods==
-When you need code to create an object, use an `...@provides` method. The
method must be defined within a module, and it must have an `...@provides`
annotation. The method's return type is the bound type. Whenever the
injector needs an instance of that type, it will invoke the method.
-{{{
-public class BillingModule extends AbstractModule {
- @Override
- protected void configure() {
- ...
- }
-
- @Provides
- TransactionLog provideTransactionLog() {
- DatabaseTransactionLog transactionLog = new DatabaseTransactionLog();
- transactionLog.setJdbcUrl("jdbc:mysql://localhost/pizza");
- transactionLog.setThreadPoolSize(30);
- return transactionLog;
- }
-}
-}}}
-If the `...@provides` method has a binding annotation like `...@paypal` or
`...@named("Checkout")`, Guice binds the annotated type. Dependencies can be
passed in as parameters to the method. The injector will exercise the
bindings for each of these before invoking the method.
-{{{
- @Provides @PayPal
- CreditCardProcessor providePayPalCreditCardProcessor(
- @Named("PayPal API key") String apiKey) {
- PayPalCreditCardProcessor processor = new PayPalCreditCardProcessor();
- processor.setApiKey(apiKey);
- return processor;
- }
-}}}
-
-==Provider Bindings==
-When your `...@provides` methods start to grow complex, you may consider
moving them to a class of their own. The provider class implements Guice's
`Provider` interface, which is a simple, general interface for supplying
values:
-{{{
-public interface Provider<T> {
- T get();
-}
-}}}
-Our provider implementation class has dependencies of its own, which it
receives via its `...@inject`-annotated constructor. It implements the
`Provider` interface to define what's returned with complete type safety:
-{{{
-public class DatabaseTransactionLogProvider implements
Provider<TransactionLog> {
- private final Connection connection;
-
- @Inject
- public DatabaseTransactionLogProvider(Connection connection) {
- this.connection = connection;
- }
-
- public TransactionLog get() {
- DatabaseTransactionLog transactionLog = new DatabaseTransactionLog();
- transactionLog.setConnection(connection);
- return transactionLog;
- }
-}
-}}}
-Finally we bind to the provider using the `.toProvider` clause:
-{{{
-public class BillingModule extends AbstractModule {
- @Override
- protected void configure() {
- bind(TransactionLog.class)
- .toProvider(DatabaseTransactionLogProvider.class);
- }
-}}}
-If your providers are complex, be sure to test them!
\ No newline at end of file
+To create bindings, extend `AbstractModule` and override its `configure`
method. In the method body, call `bind()` to specify each binding. These
methods are type checked so the compiler can report errors if you use the
wrong types. Once you've created your modules, pass them as arguments to
`Guice.createInjector()` to build an injector.
\ No newline at end of file
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"google-guice-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/google-guice-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
