CDI Dependency Injection - Tutorial II - Annotation Processing and Plugins - Java EE

CDI provides a pluggable architecture allowing you to easily process your own annotations. Read this article to understand the inner workings of CDI and why this JSR is so important.

CDI simplifies and sanitizes the API for DI and AOP like JPA did for ORMs. Through its use of Instance and @Produces, CDI provides a pluggable architecture. This is a jaw dropping killer feature of CDI. Master this and you start to tap into the power of CDI. The last article was just to lay the ground work to the uninitiated for this article.

This article continues our tutorial of dependency injection with CDI.

This article covers:

• How to process annotations for configuration (injection level and class level)
• How to use an annotation for both injection and configuration (@Nonbinding)
• Using Instance to manage instances of possible injection targets
• CDI's plugin architecture for the masses

With this pluggable architecture you can write code that finds new dependencies dynamically. CDI can be a framework to write frameworks. This is why it is so important that CDI was led through the JSR process.

Just like last time, there are some instructions on how to run the examples: Source code for this tutorial, and instructions for use. A programming article without working sample code is like a sandwich with no condiments or dry toast without jelly.

Advanced CDI tutorial

The faint of heart stop here. All of the folks who want to understand the inner workings of CDI continue. So far, we have been at the shallow, warm end of the pool. Things are about to get a little deeper and colder. If you need to master CDI, then this article if for you. If you don't know what CDI is then read the first CDI DI article.

Advanced: Using @Produces and InjectionPoint to create configuration annotations

Our ultimate goal is to define an annotation that we can use to configure the retry count on a transport. Essentially, we want to pass a retry count to the transport.

We want something that looks like this:

Code Listing: TransportConfig annotations that does configuration

	@Inject @TransportConfig(retries=2)
	private ATMTransport transport;

(This was my favorite section to write, because I wanted to know how to create a annotation configuration from the start.)

Before we do that we need to learn more about @Produces and InjectionPoints. We are going to use a producer to read information (meta-data) about an injection point. A major inflection point for learning how to deal with annotations is the InjectionPoints. The InjectionPoints has all the metadata we need to process configuration annotations.

An InjectionPoint is a class that has information about an injection point. You can learn things like what is being decorated, what the target injection type is, what the source injection type, what is the class of the owner of the member that is being injected and so forth.

Let's learn about passing an injection point to @Produces. Below I have rewritten our simple @Produces example from the previous article, except this time I pass an InjectionPoint argument into the mix.

Code Listing: TransportFactory getting meta-data about the injection point

package org.cdi.advocacy;

import javax.enterprise.inject.Produces;
import javax.enterprise.inject.spi.InjectionPoint;

public class TransportFactory {


    @Produces ATMTransport createTransport(InjectionPoint injectionPoint) {
		
        System.out.println("annotated " + injectionPoint.getAnnotated());
        System.out.println("bean " + injectionPoint.getBean());
        System.out.println("member " + injectionPoint.getMember());
        System.out.println("qualifiers " + injectionPoint.getQualifiers());
        System.out.println("type " + injectionPoint.getType());
        System.out.println("isDelegate " + injectionPoint.isDelegate());
        System.out.println("isTransient " + injectionPoint.isTransient());

        return new StandardAtmTransport();
    }

}

Now we just run it and see what it produces. The above produces this output. Output

annotated AnnotatedFieldImpl[private org.cdi.advocacy.ATMTransport org.cdi.advocacy.AutomatedTellerMachineImpl.transport]
bean ManagedBeanImpl[AutomatedTellerMachineImpl, {@javax.inject.Named(value=atm), @Default(), @Any()}, name=atm]
member private org.cdi.advocacy.ATMTransport org.cdi.advocacy.AutomatedTellerMachineImpl.transport
qualifiers [@Default()]
type interface org.cdi.advocacy.ATMTransport
isDelegate false
isTransient false
deposit called
communicating with bank via Standard transport

It appears from the output that annotated tells us about the area of the program we annotated. It also appears that bean tells us which bean the injection is happening on.

From this output you can see that the annotated property on the injectionPoint has information about which language feature (field, constructor argument, method argument, etc.). In our case it is the field org.cdi.advocacy.AutomatedTellerMachineImpl.transport. is being used as the target of the injection, it is the thing that was annotated.

From this output you can see that the bean property of the injectionPoint is being used to describe the bean whose member is getting injected. In this case, it is the AutomatedTellerMachineImpl whose is getting the field injected.

I won't describe each property, but as an exercise you can.

Exercise: Look up the InjectionPoint in the API documentation. Find out what the other properties mean. How might you use this meta-data? Can you think of a use case or application where it might be useful? Send me your answers on the CDI group mailing list. The first one to send gets put on the CDI wall of fame. (All others get honorable mentions.)

Drilling further you can see what is in the beans and annotated properties.

Code Listing: TransportFactory.createTransport drilling further into the meta-data about the injection point

    @Produces ATMTransport createTransport(InjectionPoint injectionPoint) {
        
        System.out.println("annotated " + injectionPoint.getAnnotated());
        System.out.println("bean " + injectionPoint.getBean());
        System.out.println("member " + injectionPoint.getMember());
        System.out.println("qualifiers " + injectionPoint.getQualifiers());
        System.out.println("type " + injectionPoint.getType());
        System.out.println("isDelegate " + injectionPoint.isDelegate());
        System.out.println("isTransient " + injectionPoint.isTransient());

        Bean<?> bean = injectionPoint.getBean();

        System.out.println("bean.beanClass " + bean.getBeanClass());
        System.out.println("bean.injectionPoints " + bean.getInjectionPoints());
        System.out.println("bean.name " + bean.getName());
        System.out.println("bean.qualifiers " + bean.getQualifiers());
        System.out.println("bean.scope " + bean.getScope());
        System.out.println("bean.stereotypes " + bean.getStereotypes());
        System.out.println("bean.types " + bean.getTypes());

        Annotated annotated = injectionPoint.getAnnotated();
        System.out.println("annotated.annotations " + annotated.getAnnotations());
        System.out.println("annotated.annotations " + annotated.getBaseType());
        System.out.println("annotated.typeClosure " + annotated.getTypeClosure());
        
        return new StandardAtmTransport();
}

Now we are cooking with oil. Throw some gas on that flame. Look at the wealth of information that the InjectionPoint defines.

Output

...
bean.beanClass class org.cdi.advocacy.AutomatedTellerMachineImpl
bean.injectionPoints [InjectionPointImpl[private org.cdi.advocacy.ATMTransport org.cdi.advocacy.AutomatedTellerMachineImpl.transport]]
bean.name atm
bean.qualifiers [@javax.inject.Named(value=atm), @Default(), @Any()]
bean.scope interface javax.enterprise.context.Dependent
bean.stereotypes []
bean.types [class org.cdi.advocacy.AutomatedTellerMachineImpl, interface org.cdi.advocacy.AutomatedTellerMachine, class java.lang.Object]
annotated.annotations AnnotationSet[@javax.inject.Inject()]
annotated.annotations interface org.cdi.advocacy.ATMTransport
annotated.typeClosure [interface org.cdi.advocacy.ATMTransport, class java.lang.Object]
...

We see that bean.beanClass gives up the class of the bean that is getting the injected field. Remember that one, we will use it later.

We can see that bean.qualifiers gives up the list of qualifiers for the AutomatedTellerMachineImpl.

We can also see that annotated.annotations gives us the list of annotations that are associated with the injected field. We will use this later to pull the configuration annotation and configure the transport with it.

Exercise: Look up the Bean and Annotated in the API documentation. Find out what the other properties mean. How might you use this meta-data? Can you think of a use case or application where it might be useful? Send me your answers on the CDI group mailing list. The first one to send gets put on the CDI wall of fame. (All others get honorable mentions.)

Ok now that we armed with an idea of what an Injection point is. Let's get configuring our transport.

First let's define an TransportConfig annotation. This is just a plain runtime annotation as follows:

Code Listing: TransportConfig an annotation used for configuration

package org.cdi.advocacy;


import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;



@Retention(RUNTIME) @Target({TYPE, METHOD, FIELD, PARAMETER})
public @interface TransportConfig {
    int retries() default 5;
}

Notice that this annotation has one member retries, which we will use to configure the ATMTransport (transport).

Now go ahead and use this to decorate the injection point as follows:

Code Listing: AutomatedTellerMachineImpl using TransportConfig to configure retries

public class AutomatedTellerMachineImpl implements AutomatedTellerMachine {
	
    @Inject @TransportConfig(retries=2)
    private ATMTransport transport;

Once it is configured when you run it, you will see the following output from our producer:

Output

annotated.annotations AnnotationSet[@javax.inject.Inject(), @org.cdi.advocacy.TransportConfig(retries=2)]

This means the annotation data is there. We just need to grab it and use it. Stop and ponder on this a bit. This is pretty cool. The producer allows me to customize how annotations are consumed. This is powerful stuff and one of the many extension points available to CDI. CDI was meant to be extensible. It is the first mainstream framework that encourages you to consume your own annotation data. This not some obscure framework feature. This is in the main usage.

Please recall that the injectionPoint.annotated.annotations gives us the list of annotations that are associated with the injected field, namely, the transport field of the AutomatedTellerMachineImpl. Now we can use this to pull the configuration annotation and configure the transport with it. The party is rolling now.

Now we need to change the transport implementations to handle setting retires. Since this is an example, I will do this simply by adding a new setter method for retires (setRetries) to the ATMTranport interface like so:

Code Listing: ATMTransport adding a retries property

package org.cdi.advocacy;

public interface ATMTransport {
    public void communicateWithBank(byte[] datapacket);
    public void setRetries(int retries);
}

Then we need to change each of the transports to handle this new retries property as follows:

Code Listing: StandardAtmTransport adding a retries property

package org.cdi.advocacy;

public class StandardAtmTransport implements ATMTransport {
	
    private int retries;

    public void setRetries(int retries) {
        this.retries = retries;
    }


    public void communicateWithBank(byte[] datapacket) {
        System.out.println("communicating with bank via Standard transport retries=" + retries);
    }

}

Continue reading... Click on the navigation links below the author bio to read the other pages of this article.

Be sure to check out part I of this series as well: CDI DI Tutorial!

About the author
This article was written with CDI advocacy in mind by Rick Hightower with some collaboration from others. Rick Hightower has worked as a CTO, Director of Development and a Developer for the last 20 years. He has been involved with J2EE since its inception. He worked at an EJB container company in 1999. He has been working with Java since 1996, and writing code professionally since 1990. Rick was an early Spring enthusiast. Rick enjoys bouncing back and forth between C, Python, Groovy and Java development.

Although not a fan of EJB 3, Rick is a big fan of the potential of CDI and thinks that EJB 3.1 has come a lot closer to the mark.

Rick Hightower is CTO of Mammatus and is an expert on Java and Cloud Computing. Rick is invovled in Java CDI advocacy and Java EE. CDI Implementations - Resin Candi - Seam Weld - Apache OpenWebBeans