Make H2 Log Via SLF4J

If you want your in-memory H2 database to log via SLF4J so you can control its logging output using your logging framework of choice, add this canonical string to your JDBC URL:

INIT=SET TRACE_LEVEL_FILE=4

The actual property you are setting in this case is the INIT property.  Here, you have set it to be equal to exactly one statement.  You can of course set it to be equal to several statements:

INIT=SET TRACE_LEVEL_FILE=4;SET DB_CLOSE_DELAY=-1;

The examples above are canonical strings, free of escape characters.  If you are setting these inside a Java String you’ll need to escape things properly.  Here’s a sample JDBC URL written as a double-quoted Java String that makes H2 log using SLF4J and runs some DDL on every connection:

"jdbc:h2:mem:chirp;INIT=SET TRACE_LEVEL_FILE=4\\;RUNSCRIPT FROM 'classpath:foo.ddl'"

Note the double backslashes: the first backslash escapes the next one, which, in turn, escapes the semicolon, because the semicolon is used as a delimiter in the actual JDBC URL itself.

The important thing in all of these cases is that SET TRACE_LEVEL_FILE=4 must come first in the INIT property value.

Introducing microBean™ Jersey Netty Integration

I’m really excited about my latest personal side project.  After a couple of false starts, I’ve put together microBean™ Jersey Netty Integration, available on Github.

This project inserts Jersey properly and idiomatically into a Netty pipeline without the flaws usually encountered by other projects that attempt to do this (including the experimental one actually supplied by the Jersey project).  Let’s take a look at how it works.

The Pipeline

First, a little background.

The first construct to understand in Netty is the ChannelPipeline.  A ChannelPipeline is an ordered collection of ChannelHandlers that each react to a kind of event or message and ideally do a single thing as a result.  Events flow in from the “left” in a left-to-right direction, are acted upon, and flow back “out” in a right-to-left direction.  (In the ChannelPipeline Javadocs, events flow “in” and “up” from the “bottom”, and are written from the “top” and flow “down”.)

ChannelHandlers in the pipeline can be inbound handlers or outbound handlers or both.  If a ChannelHandler is an inbound handler, then it participates in the event flow as the events come in left-to-right from the socket.  If a ChannelHandler is an outbound handler, then it participates in the event flow as the events go out right-to-left to the socket.

Used normally, ChannelHandlers are invoked by only a single thread, so you are insulated from threading gymnastics when you’re writing one.  However, the thread that invokes them is usually the Netty event loop: a thread whose main job is and that is in the process of ferrying bytes to and from a socket.  So it’s critical that any work you do that might block this thread gets offloaded elsewhere.

Events are basically messages that are read, and messages that are written.  There are other kinds of events, but that’s a good start.

A ChannelPipeline is hooked up to a Channel, which is an abstraction over sockets.  So you can see that a socket read ends up flowing left-to-right through the pipeline, and is transformed at some point along the way by a ChannelHandler into a socket write.

I am painting with a very broad brush and only so I can talk about plugging Jersey in to this machinery properly.  For more, you really should buy Netty in Action from your favorite local bookstore.

The Pipeline Philosophy

This elegant architecture is very much in the spirit of Unix’s “do one thing and do it well” philosophy, and I’m sure it is not unintentional that a Netty pipeline resembles a Unix pipeline.

In a well-behaved Netty pipeline, a handler near the head of the pipeline is usually performing translation work.  It takes handfuls of bytes, and turns them into meaningful objects that can be consumed as events by handlers further on up the pipeline.  This act is called decoding, and Netty ships with lots of decoders.

Decoder

One such decoder is the HttpRequestDecoder, which converts bytes into HttpRequest and HttpContent objects.  When this is at the head of the pipeline, then every other inbound handler upstream from it can now wait to receive HttpRequest and HttpContent objects without worrying about how they were put together.

What’s important to notice here is that the HttpRequestDecoder does just one thing: it takes in bytes and transforms them into another message, fires it up the pipeline, and that’s it.

On the writing front, there is, unsurprisingly, an HttpResponseEncoder that accepts requests to write HttpResponses and HttpContent objects, and turns them into bytes suitable for supplying (eventually) to the socket layer.  Like its decoding sister, this handler just does translation, but in the other direction.

Of HttpRequests and ContainerRequests

So now we have a pipeline that deals in HttpObjects (HttpRequests and HttpContent objects on the way in, and HttpResponses and HttpContent objects on the way out).  That’s nice.

Let’s say we want to put Jersey “into” this pipeline in some fashion.  Clearly we’d put it somehow after the decoder on the way in, so it can read HttpObjects, and before the encoder on the way out, so it can also write HttpObjects.

Sadly, however, Jersey does not natively know about Netty objects such as HttpObject, HttpRequest, HttpContent and HttpResponse.  To put Jersey in this pipeline, we will have to adapt these Netty objects into the right kind of Jersey objects using other decoders.

Additionally, of course, Jersey exists to run JAX-RS (or Jakarta RESTful Web Services) applications, and we don’t know what those applications are going to do.  Remember the bit above where I said that we shouldn’t block the event loop?  That comes into play here.

So what are we to do?

Jersey has a container integration layer.  In this parlance, a container is the Thing That Hosts Jersey, whatever “hosts” might mean.  Many times this is a Servlet engine, such as Jetty, or a full-blown application server, such as Glassfish.

But it doesn’t have to be.  (Some people aren’t aware that JAX-RS (or Jakarta RESTful Web Services) does not require Servlet at all!  It’s true!)

As it turns out, all you need to get started with Jersey integration is a ContainerRequest.  A ContainerRequest is the bridge from whatever is not Jersey, but is hosting it in some way, to that which is Jersey, which will handle it.  So as you can see from its constructor, you pass in information that Jersey needs to do its job from wherever you got it, and Jersey takes it from there.  In this case, we’ll harvest that information from HttpRequest and HttpContent objects.

Combining Messages

The proper and idiomatic way to do this sort of thing is to further massage our pipeline.  Just as Netty ships relatively small handlers that do one thing and do it well, we’re not going to try to cram Jersey integration into a single class.  Instead, we want to turn a collection of HttpRequest and HttpContent objects into a ContainerRequest object first.  Do one thing and do it well.  We’ll worry about what comes after that in a moment.

This decoding is a form of message aggregation.  In some cases, we’ll need to combine an initial HttpRequest with a series of HttpContent objects that may follow it into a single ContainerRequest.

Accordingly, microBean™ Jersey Netty Integration ships with a decoder that consumes HttpRequest and HttpContent messages, and emits ContainerRequest messages in their place.  This forms the first part of idiomatic Netty-and-Jersey integration.

HttpObjectToContainerRequestDecoder

Creating a ContainerRequest from an HttpRequest is relatively simple.  The harder part is deciding whether to let the ContainerRequest under construction fly up the pipeline or not.

For example, some incoming HttpRequests represent simple GET requests for resources, and have no accompanying payload and therefore a Content-Length header of 0.  These are easy to deal with: there’s no further content, so translating such an HttpRequest into a ContainerRequest is a one-for-one operation.  Grab some fields out of the HttpRequest, use them to call the ContainerRequest constructor, and you’re done.  That case is easy.

On the other hand, a POST usually features an incoming payload.  The ContainerRequest we’re building will need an InputStream to represent this payload.  This case is a little trickier.

Specifically, in Netty, a complete HTTP request is deliberately represented in several pieces: the initial HttpRequest, and then several “follow-on” HttpContent items representing the incoming payload, terminated with a LastHttpContent message indicating the end of the payload.  Netty does things this way to avoid consuming lots of memory, and for speed reasons.

You could wait for all such messages to arrive, and only then combine them together, create an InputStream that somehow represents the whole pile of HttpContents, install it, and fire the resulting ContainerRequest up the pipeline.

But that’s a lot of waiting around, and therefore isn’t very efficient: Jersey is going to have to read from the ContainerRequest before it starts writing, so you might as well give it the ability to do that as soon as possible, even if all the readable content isn’t there yet.  Remember too that ideally Jersey will ultimately be running on a thread that is not the event loop!

Really what you need to do is hold the ContainerRequest being built for a moment, specifically only until the first HttpContent describing its payload shows up.  At that point, you can create a special InputStream that will represent the yet-to-completely-arrive inbound payload, and install it on the ContainerRequest.  Then you can let the ContainerRequest fly upstream, attached to this InputStream pipe, even though strictly speaking it’s still incomplete, and wait for incoming HttpRequests to start the process all over again.  The special InputStream you install can read the remaining and yet-to-arrive HttpContent pieces later, on demand.  We’ll discuss this special InputStream shortly.

This is, of course, what microBean™ Jersey Netty Integration does.  This approach means that more things can happen at the same time that would otherwise be the case, and that keeps the event loop from being blocked.  In many ways, the special InputStream is the heart of the microBean™ Jersey Netty Integration project.

Encoding

Now we can happily leave all the translation work behind.  Because of the beauty of the Netty pipeline architecture, we can now simply trust that at some point there will be a ContainerRequest delivered via a Netty pipeline.

What are we going to do with it?

The quickest possible answer is: we’re going to hand it to an ApplicationHandler via its handle(ContainerRequest) method.  That kicks off the Jersey request/response cycle, and we’re done, right?

No.  We haven’t discussed writing yet.

It is true that we’re basically done with the reading side of things.  We have relied upon HttpRequestDecoder to turn bytes into HttpRequests and HttpContents.  We’ve posited a decoder that reads those messages and turns them into a ContainerRequest and emits it.  And we know that the final reader in our pipeline will be some sort of inbound ChannelHandler that will accept ContainerRequest instances.  Now we need to handle that ContainerRequest and write something back to the caller.

On the Jersey end of things, ContainerRequest contains everything Jersey needs to know about a JAX-RS (or Jakarta RESTful Web Services) Application.  Jersey will use its InputStream to read incoming payloads, and will use its ContainerResponseWriter to write outgoing payloads (by way, of course, of following the setup of the user’s Application).  We haven’t talked about ContainerResponseWriter yet, but we will now.

ContainerRequest.png

ContainerResponseWriter

Once a ContainerRequest gets a ContainerResponseWriter installed on it it is then possible to actually write messages back to the caller from within Jersey.  A Jersey application typically relies on finding (by well-established rules) a MessageBodyWriter to encode some kind of Java object relevant to the user’s Application into byte arrays that can then be written by Jersey to an OutputStream.  Once the writeTo method has been called, Jersey considers its writing job done.

Of course our job is not done, as now we have to somehow hook this OutputStream up to the outbound part of the Netty channel pipeline.  And, of course, recall that our decoder, following the “do one thing and do it well” philosophy, deliberately never installed a ContainerResponseWriter on the ContainerRequest it sent on up the pipeline.

microBean™ Jersey Netty Integration tackles this problem by having an inbound ChannelHandler implementation that is itself a ContainerResponseWriter.  It is set up to consume ContainerRequest objects, and, when it receives one, it immediately installs itself as that ContainerRequest‘s ContainerResponseWriter implementation.

To do this, this handler-that-is-also-a-ContainerResponseWriter will need an OutputStream implementation that it can return from the writeResponseStatusAndHeaders method it is required to implement for those cases where a payload is to be sent back to the caller.

The OutputStream implementation that is used functions as its own kind of mini-decoder.  It “accepts” byte arrays, as all OutputStreams do, and it “decodes” them into appropriate HttpObjects, namely HttpResponse and HttpContent objects.  Along the way, this requires first “decoding” byte arrays into Netty’s native collection-of-bytes container: ByteBuf.

Without spending much time on it, a ByteBuf is in some ways the lowest-level object in Netty.  If you have a ByteBuf in your hand, decoding it into some other Netty-supplied object is usually pretty trivial.  In this case, creating a DefaultHttpContent out of a ByteBuf is as simple as invoking a constructor.

Getting a ByteBuf from an array of bytes is also straightforward: just use the Unpooled#wrappedBuffer method!  So on every write to this OutputStream implementation you are effectively emitting HttpContent objects of a mostly predictable size.

Next, the OutputStream implementation does not, obviously, “point at” a file or any other kind of traditional destination you might be useful.  Instead, it wraps a ChannelOutboundInvoker implementation.  A ChannelOutboundInvoker implementation, such as a ChannelHandlerContext, is the “handle” that you use to send a write message up the Netty channel pipeline.  So every OutputStream#write operation becomes a ChannelOutboundInvoker#write operation.

Finally, you want the OutputStream implementation that “consumes” byte arrays and writes HttpObjects of the right kind to do so without necessarily waiting for all the content that Jersey might write over the stream before sending it up the pipeline.  So the OutputStream implementation in question automatically calls its own flush() method after a configurable number of bytes have been writtenThe OutputStream, in other words, is auto-flushing.  (Unless you don’t want it to be!)

About that flush() method: it’s mapped to (you guessed it) ChannelOutboundInvoker#flush.

So now we have connected the dots: a ContainerRequest goes to Jersey, which processes it.  Jersey writes to an OutputStream we provide that itself bridges to the actual Netty channel pipeline.  And downstream in the pipeline we have a Netty-supplied HttpResponseEncoder that accepts the HttpResponse and HttpContent objects we emit.

microBean Jersey Netty

Threading

Now let’s talk about threads.  In Netty, as noted, events coming up the pipeline—events being read, events being processed by ChannelInboundHandlers—are executed by the event loop: a thread that is devoted to processing what amount to socket events.  It is very important to let these event loop threads run as fast and free as possible.  We’ve already talked about how a Jersey application should not, therefore, be run on the event loop, because you don’t know what it is going to do.  Will it sleep?  Will it run a monstrous blocking database query?  You don’t know.  More concretely, this means that therefore our ChannelInboundHandler-that-is-also-a-ContainerResponseWriter must not execute ApplicationHandler#handle(ContainerRequest) on the event loop.

Most other projects that integrate Jersey with Netty in some way use a thread pool or Jersey’s own schedulers to do this.  But they overlook the fact that Netty lets you do this more natively.  This native approach is the one that microBean™ Jersey Netty Integration has taken.

First, let’s just note that the only mention that we’ve made so far of anything in the integration machinery that could block is the special InputStream that is supplied to a ContainerRequest as its entity stream.  We mentioned that this InputStream gets installed on a ContainerRequest as a kind of empty pipe before (potentially) the entire incoming payload has been received.  Therefore, Jersey might start reading from it before there are bytes to read, and indeed, that InputStream implementation will block in that case, by contract, until the downstream (or “leftstream”) decoder catches up and fills the pipe with other HttpContent messages.

But you’ll note that otherwise we haven’t made mention of anything like a ConcurrentHashMap or a LinkedBlockingQueue or anything from the java.util.concurrent.locks package.  That’s on purpose.  To understand how microBean™ Jersey Netty Integration gets away with this minimal use of blocking constructs, we have to revisit the ChannelPipeline.

When you add a ChannelHandler to a pipeline—when, as a Netty developer, you build your pipeline in the first place—you typically use various flavors of the ChannelPipeline#addLast method.  This appends your ChannelHandler in question to the tail of the pipeline as you might expect.  And then all the event handling we’ve talked about flows through the pipeline in the way that we’ve talked about it.

But note that there’s another form of the ChannelPipeline#addLast method that takes an EventExecutorGroup!

In this form, if you supply a new DefaultEventExecutorGroup as you add a ChannelHandler, then its threads will be those that run your ChannelHandler‘s event-handling methods, and not those of the event loop!  So all you have to do to get the Jersey ApplicationHandler#handle(ContainerRequest) method to be run on a non-event loop thread is to set up your pipeline using this variant of the ChannelPipeline#addLast method, supplying a DefaultEventExecutorGroup.  Then whatever the JAX-RS or Jakarta RESTful Web Services Application does (slow database access, Thread.sleep() calls…) will not block the event loop.

Now, another tenet of the Netty framework is that Thou Shalt Not Write to the Pipeline Except on the Event Loop.  So if our ApplicationHandler#handle(ContainerRequest) method is being run on a non-event-loop thread, then don’t we have to do something to “get back on” the event loop thread when our OutputStream implementation calls ChannelOutboundInvoker#write(Object, ChannelPromise)?

As it turns out, no, because since a ChannelOutboundInvoker‘s whole job is to “do” IO, it always ensures that these operations take place on the event loop.  In other words, even though our Jersey application is correctly running its workload on one non-event-loop thread, when our special OutputStream invokes ChannelOutboundInvoker#write(Object, ChannelPromise), the implementation of that method will ensure that the write takes place on the event loop by enqueuing a task on the event loop for us.

To put it one final other way, if you have introduced queues of any kind or homegrown thread pools into your Netty integration machinery—other than the minimal amount of blocking necessary for adapting incoming entity payloads into InputStreams as previously discussed—you’re doing it wrong, because Netty already has them.

Conclusion

There is a lot more to this library than I’ve covered here, including HTTP/2 support.  I encourage you to take a look at its Github repository and get involved.  Thanks for reading!

Jersey and Netty Together Again For The First Time Once More

I had some time and put together a Jersey-and-Netty integration that I think is pretty interesting.

Its Github repository is here: https://github.com/microbean/microbean-jersey-netty.  Its website is here: https://microbean.github.io/microbean-jersey-netty/.

It lets you run Jersey as a Java SE application using Netty to front it.  It supports HTTP and HTTP/2, including upgrades.

Jersey itself ships with a Netty integration, but it seems to have some problems and parts of it are designated by its author as very experimental.  I wanted to see if I could do a decent integration myself, both to learn more about Netty and to solve a real problem that I’ve had.

The main challenge with Netty is to ensure that its event loop is never blocked.  But the very nature of JAX-RS, with its InputStreams supplying inbound payloads, means that some blocking in general is necessary, so immediately you’re talking about offloading that blocking onto extra threads or executors to free up the event loop, and therefore coordination of IO activity between the Jersey side of the house and the Netty side of the house.

This in itself is not terribly difficult on the face of it and can be addressed in many different ways.  The Jersey-supplied integration accomplishes this by passing InputStreams to Jersey using blocking queues.  This is fine, but now the integration author has to deal with queue capacity, and rejecting submissions, and so forth.  As you might expect there is at least one issue around this that turns out to be somewhat severe (apparently).  This also involves creating a fair number of objects.

But of course Netty already has a really nice system of queues that it uses to do this same sort of thing, and you can easily get access to it: it’s the event loop itself, which lets you submit things to it.

Netty also has its ByteBuf construct, which is a better cheaper faster ByteBufferByteBufs are sort of Netty’s “coin of the realm”.  Netty goes to extraordinary lengths to ensure a minimum of object allocations and garbage generation occur when you’re working with ByteBufs, so they seem like a good thing to center any integration strategy around.  They are not thread-safe, but if you mutate them only on the event loop, you’re good.

So the general approach I take is: instead of making extra queues to shuttle byte arrays or other Java-objects-wrapping-byte-arrays back and forth between Jersey land and Netty land, I use a CompositeByteBuf that gets the ByteBuf messages that Netty supplies in its HTTP message constructs added to it as they come in on the Netty event loop, and use the Netty event loop task queue to ensure that all ByteBuf operations of any kind always take place on the event loop.

This means that I can take advantage of everything Netty gives me under the covers in terms of memory efficiency and potential transparent usage of off-heap buffers and such, while also gleefully punting any task queue saturation issues to Netty itself, which already has customizable strategies for dealing with them.  A lower chance of bugs for you, since Netty has to deal with this sort of problem all day every day, and a lower chance of bugs for me, since it is their code, not mine, doing this coordination.  Win-win!

On the outbound side, I take advantage of Netty’s ChunkedWriteHandler, which, contrary to how it might appear at first, has nothing to do with Transfer-Encoding: chunked.  Instead, it is a nice little handler that deals with user-supplied-but-Netty-managed hunks of arbitrarily-typed data, writing them when their contents are available, and doing other things when it can’t.  The upshot: your Jersey OutputStreams are chunked up and enqueued on the event loop using a single ByteBuf implementation that is optimized for IO as data is written to them.

The net effect is a nice little as-nonblocking-as-JAX-RS-can-get tango that Netty and Jersey perform together, coordinated by Netty’s and Jersey’s own constructs.

microBean™ Jersey Netty has extensive Javadocs and is available on Maven Central.

A CDI Primer: Part 4

In the previous post, we learned that the only Contextuals that matter, really, are Beans, and we learned a little bit about injection points and loosely how they’re filled.

In this post we’ll look at how CDI actually discovers things, and how it normalizes them into Bean implementations, and how it marries them with Context implementations to figure out what their lifecycles are going to be.

The Container Lifecycle

CDI has a very well-specified lifecycle.  There is a general startup phase during which all the raw materials in the world are discovered, arranged and pared down to form a network of Bean implementations that produce and consume each other.  Once that startup phase has completed, the actual application—whatever it might be, that makes use of all these producers and consumers—starts, and runs, and does its thing.  Then there is a shutdown free-for-all where all Bean implementations can, indirectly, get a chance to clean up, and that’s all there is to it.

But what are you, the end-user, the ordinary developer, supposed to do with all this?  In your hand, you have a class that has some injection points in it (fields or methods annotated with Inject), and you want them filled.  What does this have to do with Bean implementations?  After all, your class doesn’t implement Bean.  We’ll see how internally, in a way, it sort of does.

Discovering Things

As part of the startup phase, CDI performs type discovery and bean discovery.

Type discovery is a fancy name for taking stock of what classes exist on the classpath.  Plugins, called portable extensions, can affect this; that’s a subject for another day.  For now, know that CDI will scan the classpath for particular classes and will add them to a set of such classes that represents its type world.

Once types have been discovered, CDI performs bean discovery, where some of those types it found lying around are normalized into Bean implementations internally.

It’s important to realize what’s going on here.  For the typical developer scenario, most classes that are discovered are turned into producers.  This can be a little counterintuitive—I don’t know about you, but that’s not usually what I think of when I have a class in my hand named with a noun, like Person or Customer.  Really?  Customer is a producer?  A producer of what?  Well, of instances of itself, it turns out.  Which of course we all actually know, because it has a constructor.

Managed Beans

So consider our ongoing stupid example of a Backpack class, with a simple zero-argument constructor, annotated with Singleton, and a Gorp-typed field annotated with Inject.  Let’s say that CDI discovers it.  Internally during bean discovery CDI creates a Bean to represent it:

A Bean implementation built internally like this is called a managed bean, and the class itself is frequently called a managed bean as well.

It’s important to realize that for a given managed bean one of its bean types and its bean class are always identical.

Producer Methods

Another very common kind of bean is a producer method.  In this case, CDI has done its type discovery, and has found a class called CandyShop also annotated with Singleton (I’m picking Singleton because it is a scope that everyone is intuitively familiar with.)  Let’s say this class has a method in it declared like this:

@Produces
@Singleton
public Candy produceCandy() {
  return new Candy();
}

This time, CDI will create a Bean internally for CandyShop that looks a lot like the one above, namely:

But then it will also create a Bean internally that represents the producer method:

Do you see that the bean class here is CandyShop but the getTypes() method returns a Set of bean types that includes Candy.class, not CandyShop.class?  The takeaway here is that usually when you’re considering a true CDI bean you are, as a normal developer, interested in one of its bean types, not its bean class.  In other words, you’re interested in (in this example) Candy.class, and normally not so interested in the fact that the producer method that creates its instances happens to be housed in a class called CandyShop.  The terminology in the documentation certainly does its best to make this about as clear as mud.

Producer Fields

Just as you can have a producer method whose bean class is one thing while its bean types are another, you can have a producer field.  Let’s say our CandyShop class from the example above also has a field in it declared like this:

@Produces
@Singleton
private PeanutButter peanutButter;

Once again, CDI will create a Bean for CandyShop, just as it did before, and here it will also create another Bean:

In practice, producer fields are comparatively rare.  They exist primarily to bridge the worlds of Java EE, where you might have a field that is annotated with Resource (so is being set by some kind of JNDI-aware machinery), and CDI where you can have the very same field annotated with Produces.  This lets CDI set up a Bean implementation under the covers that creates instances from Java EE-land without any other aspects of the CDI ecosystem really being aware that Java EE is even in the picture.

Decorators and Interceptors

Two other primary Bean implementations are Decorators and Interceptors.  I’m not going to talk about them because although it may look like it by this point I’m not writing a book.  Suffice it to say they are represented in the CDI ecosystem by Beans, and so are inherently producers of things, which can also be counterintuitive.

Custom Beans

Finally, without digging deep into portable extensions, we can at least say that portable extensions have a variety of ways to cause a Bean implementation to be created by hand at container startup time.  When Beans are added into the system this way, the portable extension has absolute full control over them.

Putting It Together

The biggest takeaway here is that everything in CDI is a Bean.  In the documentation, almost everything is a little-b bean.  A bean, represented by a Bean, is fundamentally a producer of something.  There are recipes that we’ve just enumerated that translate ordinary Java constructs into Bean implementations when bean discovery is performed: a creator and a destroyer (Contextual) together with bean types and a scope (BeanAttributes), a hosting bean class and a set of injection points (Bean).

There’s another thing that falls out of this.  Bean is a parameterized type: you have a Bean<T>.  The <T> is, however, always usage-specific, because it comes by way of Contextual, whose usage of its type parameter is the return type from its create method.  That is, <T> represents one of a Bean‘s bean types—one of the kinds of things it can make—not its bean class—the class hosting the producer method or constructor.

Consider a Bean<Person>.  Because a Bean<Person> is a Contextual<Person>, it follows that you can call its create method and get a Person back.  But it does not follow that calling its getBeanClass() method will return Person.class!  Perhaps the Bean<Person> you are looking at represents a producer method, or a producer field, for example.

Finally

So finally we can see how CDI makes @Inject work, which was what we set out to do in part 0:

  • CDI discovers types
  • For each type found during type discovery, CDI creates a Bean to represent it, or at least tries to
  • For each producer method and producer field (and other cases), CDI creates another Bean to represent it
  • For every InjectionPoint found in this pile of Beans, CDI performs typesafe resolution to see what Beans have bean types that “match” the InjectionPoint‘s type
  • Assuming that all slots get matched up to producers, whenever CDI needs to obtain an instance of something, it does so through the right Context which is in the business of handing out contextual instances
  • CDI can find the right Context by checking out the scope available from each Bean
  • Ultimately the Context, when asked to produce an instance of something, will call through to a Bean‘s create method

I’ve deliberately left out qualifiers, which are extremely important, but are deserving of their own article later.

There’s much more to say about CDI, but I think I’ll stop there for now.

Thanks for reading this primer!

A CDI Primer: Part 3

In the previous post, we learned about typesafe resolution (the process of matching producers (Contextual implementations) with consumers) and where, exactly, Contexts fit in.

We also learned that you can “label” a Context with a scope, an annotation class standing in for the kind of lifecycle you want a Context whose getScope method returns it to implement.

We also learned that in some unspecified way you can apply the same annotation to a Contextual implementation.

The net result was that we sketched out our first hazy picture of how a Gorp-typed slot in a consumer (Backpack) might receive a singleton Gorp produced by a Contextual implementation whose type parameter is Gorp.  (If you’re wondering what all this is about, I heartily recommend you start at the beginning with part 0.)

Nevertheless, as we did this, we waved our hands furiously over certain details.  Specifically, while describing typesafe resolution, we made many references to CDI linking together producers and consumers without describing exactly how this happens, and we spoke a lot about Contextuals, but never really covered what they are, exactly.  We’ll look into that in some detail in this article.

Contextual Implementations: Beans

Throughout this series of articles, we’ve talked about Contextuals as being CDI’s implementation of producers in the dependency injection mindset (which we described in part 0).

Contextuals produce contextual instances.  And contextual instances are what Contexts supply to fill @Inject-annotated slots.  You get all that by this point I’m sure.  But we haven’t discussed what Contextualare.

Strictly speaking, of course, a Contextual implementation only has to implement the create and destroy methods.  Great.

Let’s say you write a two-method-long class that does that.  Now what?  Nothing, that’s what.

It turns out that CDI doesn’t really give you an “in” using this interface: you can compile a Contextual implementation, stick it somewhere, and it will happily sit there until the end of time waiting to be discovered and used, which will never happen.

But a subclass (subinterface) of Contextual is Bean, and we’ve all heard that term before.

As it turns out, the only direct subtype of Contextual that CDI inherently knows about is Bean.

So in most cases where I’ve written about Contextuals, you can substitute Beans, and be just fine.  A Bean “is a” Contextual, and CDI deals primarily in Beans.  (There are mechanisms throughout CDI for getting Bean implementations “into” the system, but none for directly getting “raw” Contextuals that are not Beans into the system.  We’ll cover this interesting structural fiesta below.)

So if that’s all true, why have I been talking about Contextuals all this time, and not Beans?

Because Contextual is the part of the Bean interface that deals with production (it consists solely of create and destroy methods, after all).  The rest of the Bean interface, as we’ll see, deals with other things.

We’ve backed into this series of articles from the production end: we have been shining a light on exactly how “CDI makes @Inject work”.  So production has been front and center, and that’s what Contextuals give you.

Now with the production facet of Beans under our belts, we can turn our attention to the other facets.

Let’s start with one such facet—the BeanAttributes interface.

BeanAttributes

CDI was defined originally back in an era where inheritance was used a lot, and composition…not so much.  As a result some compositional concerns in CDI are expressed—conveniently but a little opaquely—in terms of inheritance.  This is true of the trio formed by Bean, BeanAttributes and Contextual.  Luckily we can tease them apart.

Here is a class diagram showing that Bean inherits from both Contextual and BeanAttributes:

CDI Primer 3

This is certainly obviously how the interfaces are actually structured, but it hides the more important fact that each of the collections of methods defined by each interface is really a facet of the same underlying object.  With only a few rare exceptions, CDI assumes that the object “behind the curtain” of a Contextual interface, for example, will also implement Bean.

That is, a Bean “is a” Contextual, sure, but really a Bean “has a” Contextual facet: it has a facet that deals with production.  We’ve covered Contextual extensively.

A Bean also “is a” BeanAttributes, but really, again, Bean “has a” BeanAttributes facet: it has a facet that deals only with discovery- and typesafe resolution-related concerns.  (You’ll note in particular that the T type parameter used by create and destroy is not used anywhere in the BeanAttributes interface!)

A BeanAttributes is a facet of a Bean that is concerned with its overall place in the CDI world.  We’ll look at its methods selectively and carefully, ignoring those that don’t yet make any sense.

(And finally the collection of methods defined by the Bean interface itself is a facet of a Bean implementation that is concerned with its role as a consumer.  We’ll cover this below.)

getScope()

The first BeanAttributes method of interest we’ll consider is getScope(), which returns an annotation class representing a scope.

Here we can finally see explicitly what we handwaved over in part 2: effectively in CDI, every Contextual implementation is always also a BeanAttributes implementation, so every Contextual is capable of essentially reporting which Context manages the lifecycle of its produced objects.  See part 2 for more on this.

This lets BeanAttributes that are producers (which is to say all of them, since in CDI’s ecosystem they’re all also effectively Contextuals) still have a say in the lifecycle management of their produced objects, but they don’t actually have to implement that management themselves.  Nice.

getTypes()

The next one is getTypes(), which reports the Set of Types that a producer can make.  Again, this method only makes sense when it is tacitly understood that BeanAttributes and Contextual are always facets of the same underlying object, i.e. that all BeanAttributes are always producers (Contextuals).

So, for example, if your Contextual implementation gets instantiated with a type parameter value of Object, then if your Contextual implementation is also a BeanAttributes implementation, as it should be, you can specify with this method exactly what subtypes of Object your create method produces.

CDI calls this method to gain insight into how to “fill” a consumer’s @Inject-annotated slot with an appropriately-typed contextual instance.  When trying to locate a suitable producer it can winnow the field by looking at the return value from this method and perform typesafe resolution using the results.  (For more on typesafe resolution, see part 2.)

Other BeanAttributes Methods

We’re going to table discussion of the other BeanAttributes methods for now, as they’re really another layer on top of these fundamentals.  We’ll come back to them in a later article.

Bean

Finally, the third facet of the Bean interface consists of the methods it defines itself apart from those defined by Contextual and BeanAttributesThese methods are related to a producer’s also being a consumer.

On Consuming Producers, Producer Classes and InjectionPoints

Back in part 0, we saw that there’s nothing wrong with a producer also being a consumer!  Producers frequently need to consume raw materials to do their jobs.

We also saw that producers come in many abstract flavors: methods, fields and constructors.

A producer also needs a “host class” (a method, field or constructor has to “live in” a class, after all), and in part 0 we decided to call such host classes producer classes for want of a better term.  (CDI calls them “bean classes” for reasons we are only now capable of understanding and which we’ll look into below.)

We’ve also talked throughout this article series about consumers and producers in terms of “slots” and “filling slots”.  I have a Backpack; it has an @Inject-annotated Gorp-typed “slot”; CDI performs automatic wiring and “fills” the “slot” with a contextual instance of Gorp sourced from the right Context by way of a Contextual implementation.  (We went into some detail on this example in part 1.)

In the spirit of less handwaving, let’s call these slots what they’re actually called in CDI: injection points.

An injection point is a slot that can be filled with a contextual instance.  It is a point at which CDI performs (dependency) injection.  Injection points are represented in CDI by the appropriately-named interface InjectionPointInjectionPoints have a type (and some other stuff, which we’ll cover another day).

So our Backpack consumer has a Gorp-typed injection point.

While it does not explicitly use these terms, CDI says that a consumer simply is something with InjectionPoints: it is a Thing With Slots That Have To Be Filled.

As we’ve seen, effectively all Contextuals—all producers—are also Beans.

And we’ve seen that a producer can be a consumer.

And finally we’ve seen that a producer is housed in a producer class, which I’ve told you CDI calls a bean class.

So it should come as no surprise that this consumer facet of a Bean is represented by two methods:

getInjectionPoints is pretty simple: it returns the set of “slots” that the producer needs values for in order to do its job.  If the producer is a method, for example, then the injection points will represent the method’s parameters.  If the producer is ultimately represented by a constructor, for a more complicated example, the injection points will represent possibly the constructor itself as well as any other @Inject-annotated fields and methods in the class.

getBeanClass is a little trickier, and is in my experience one of the most misunderstood methods in all of CDI.

​​getBeanClass()

getBeanClass returns the producer class, not the class of the thing being produced.

That is, if you have a producer that is a method, getBeanClass returns its “host class”—its declaring class—not the class of its return type.  This will become important when we talk about CDI producer methods.

Similarly, if you have a producer that is a field, getBeanClass returns its declaring class, not the class of the field.  This will become important when we talk about CDI producer fields.

Finally, if you have a producer that is fundamentally a constructor, obviously a constructor makes instances of its own declaring class, so getBeanClass will return the producer class, sure, but that will also be the class of the thing being constructed!  This will become important when we talk about the most common kind of Bean implementation found in CDI: the managed bean.

The most important things to take away from these CDI internals so far are:

  • CDI has many ways of discovering things, but all producers and consumers from the dependency injection mindset can be represented in CDI as Bean implementations
  • a Bean is fundamentally a producer of things, not the things produced, and a consumer only secondarily
  • all Contextual implementations normally found in a CDI application are Bean implementations too

Automatic Wiring (Almost Entirely) Demystified

Our picture of how CDI accomplishes automatic wiring just got a little clearer.  Every producer in the system now has a facility for reporting:

  • what kinds of things it makes (getTypes())
  • what Context the things it makes should “belong” to (getScope())
  • what it needs to do its job (getInjectionPoints())
  • what class it “lives in”, of which an instance might need to be produced for the producer to be invoked (getBeanClass())

If CDI could find Bean implementations in various flavors lying around, and then normalize them into true Bean implementations in memory, it could match the Gorp-typed InjectionPoint of the Backpack-typed Bean implementation to hopefully the one Bean implementation whose getTypes method contains Gorp.class in its return value.  It could then locate the appropriate Context implementation, by looking at the return value of the getScope method, and could ask that Context to get a Gorp.  It could then use the InjectionPoint to set the actual Gorp value.

That is, of course, exactly what CDI does.

In the next post, we’ll get rid of the remaining handwavy bits and will look at how CDI:

  • “normalizes” “Bean implementations in various flavors lying around” into “true Bean implementations in memory”
  • “locate[s] the appropriate Context implementation”
  • Uses “the InjectionPoint to set the actual Gorp value”

Thanks for reading along so far!

A CDI Primer: Part 2

In the previous post we covered Contexts and Contextuals and the relationship between them.  A Contextual, briefly, is the CDI representation of a producer (a CDI-independent concept within the dependency injection mindset we covered in part 0) focused solely on the mechanics of production, with no responsibility for caching or storage or any other kind of lifecycle management.  A Context is CDI’s façade of sorts for Contextuals that has no responsibility for making objects of a given kind—it uses Contextuals for that—but all kinds of responsibility for managing the lifecycles of those manufactured or acquired objects.

We also learned that contextual instances are effectively the return values from the Context#get(Contextual, CreationalContext) method invoked on a given Context (and by extension the return values of implementations of the Contextual#create(CreationalContext) method.)  If your class has an @Inject-annotated “slot” in it, and it gets “filled” by CDI, then you just took delivery of a contextual instance from a Context, created by a Contextual.

In this post we’ll start looking at the actual mechanics that CDI uses to match contextual instances to consumer “slots”, and the beginnings of how those pieces of the machinery are found in the first place.

A Digression on Java Generics

And now, for everyone’s favorite subject: Java generics.

First, some housekeeping.  I’m going to run right into the utterly awful WordPress editor which is schizophrenic about angle brackets.  Java generics feature a lot of angle brackets.  They disappear in WordPress.  (Using ampersand-lt-semicolon and similar SGML-entity-based “solutions” doesn’t work, because the helpful editor will expand it in place, then save the result, neutering the attempt to use them in the first place.)  So I’ll use curly braces instead.  Just squint a lot and you might even be able to see them as angle brackets.

Suppose I have a field whose type is List{Number} and you have a List{Integer}.  Can I take your List{Integer} and put it into my List{Number}-typed field?  No, I cannot.  You can learn more about this from the Java Tutorial if you need to.  This is a case of trying to figure out assignability of parameterized types (like List{Number} and Class{T} and so on).  In order to do wiring properly, you—or the magic system that is going to do the wiring for you, like CDI—have to get this right.

Now, if I have a field whose type is List{? extends Number} and you have a List{Integer}, that will “go into” my field just fine.  So the person or machine doing wiring has to take wildcards into account as well.

Typesafe Resolution

This process of accounting for all sorts of different types—simple-typed slots like fields with types like Number or complicated slots with parameterized types like List{Number}—and matching those slots to compatible types, such as the return types of all producers in the system, is known as typesafe resolution.  “Typesafe” here is meant to emphasize the fact that—unlike some other dependency injection frameworks such as the machinery that was in Java EE at the time—CDI matches types, not names: your @Inject-annotated field’s type is matched to a producer’s type.  (Earlier dependency injection frameworks used name matches, which are more brittle.)  “Resolution” refers to the fact that a consumer’s slot has been matched, or resolved, to a particular production type—and thereby to a particular dependency.

Let’s say that CDI can somehow find all the slots in my classes that need contextual instances.  And it can find producers that make all different sorts of contextual instances of all different sorts of types.  If there is exactly one producer in that big pile of producers (of any kind—constructor, method, field…) whose production type is assignable to a given slot, then we have a match: we say that typesafe resolution has completed successfully, and we know that that wiring can be set up automatically.  If I have a slot that asks for a Gorp, and there is exactly one producer that returns a Gorp (or a Gorp subclass), then as we saw back in part 1 we can just “see” that that producer should be called to fill that slot.  CDI can therefore also “see” that this is the case, so is able to make it work.

Unsatisfied Dependencies

What happens when there is no producer whose production type is assignable to my @Inject-annotated field’s type?  We say in this case that typesafe resolution failed because we have an unsatisfied dependency.  I asked for a Gorp , but there wasn’t any Gorp producer that could respond.  The wiring cannot be completed automatically.

Ambiguous Dependencies

What happens when there are lots of producers whose production types are all assignable to my @Inject-annotated field’s type?  We say in this case that typesafe resolution failed because it was ambiguous.  The wiring cannot be completed automatically.  Without further information, CDI can’t make a call on which producer to select to produce an object to go in the right slot.

Finding the Right Context

Let’s say that I have a class named Backpack with a field whose type is Gorp, and there is exactly one producer in the world (represented as always in CDI by a Contextual under the covers) in some handwavy unspecified fashion that returns Gorp, and so CDI in the abstract is able to at least conceptually connect the two—i.e. typesafe resolution succeeds.

While talking about typesafe resolution, we’ve been talking about consumers and producers (Contextuals), but we’ve quietly tabled any mention of Contexts.  Let’s bring them back into the conversation.

Recall that a Context is responsible for fronting a producer (a Contextual), and for deciding when and for how long to cache its results, and that it is a Context implementation that ultimately supplies dependencies, calling upon the services of a Contextual implementation when required.

Graphically, our little case might look like this, using UML notation:

ProducerConsumerContextClassDiagram

Here, I’ve colored the CDI internal interfaces gray, our application classes (Backpack and Gorp) cyan, and then have highlighted in pink and red respectively a hypothetical Context implementation and a hypothetical Contextual implementation.  I’ve also used «stereotypes» to help with keeping the terminology straight.  Once again I’m going to have to use curly braces in my text below instead of angle brackets thanks to the WordPress editor’s many flaws.

You can see that in general a Context uses a variety of Contextual implementations to serve dependencies.

You can also see that in this case there is a Some Context Implementation? that fronts a Some Contextual{Gorp} Implementation? that is the ultimate producer of Gorp instances.

The Context implementation is going to have rules in it about when to return the same Gorp instance and when to create a new one.

The Contextual{Gorp} implementation is the producer and is going to be concerned with how to make a Gorp instance.

These classes are components in the same way that our Backpack and Gorp classes are components.  There can be many Context implementations in the system, and there can be many Contextual implementations in the system, all supplying different types, and all blissfully unaware of who might be asking for those types.  Further, a Contextual doesn’t know what Contexts might be using it, and a Context doesn’t know what Contextuals there are in the world.

So how does CDI figure out which Context implementation to pick to serve up Backpack‘s Gorp dependency?  And, even if it somehow magically does that, how does it then also figure out that the Context in question should use a particular Contextual to “back” it?

You can see, I hope, that there must be some kind of a mechanism available to let CDI know at the very least how a Contextual implementation might be linked with a Context implementation.  That hinting mechanism is a CDI construct called a scope.

Scopes

If a Context implementation is where contextual instances used by consumers come from, then a scope is a construct that indicates to CDI that this Contextual over here “goes with” that Context over there.

That is, in a very abstract sense—and we’ll get concrete soon enough—you mark a Contextual in some way that lets CDI see from that marking that the Contextual “belongs” to a certain Context implementation.

So if there is a Context in the world in some kind of handwavy unspecified fashion, and it can somehow identify itself to CDI as a producer of singletons (let’s say), and you have a Contextual implementation whose returned objects you want to be singletons, then you brand your Contextual in a particular way that identifies it as belonging to the singleton Context implementation.

The shape that this mechanism actually takes in CDI is very simple.  A scope is a particular kind of annotation class.  (Scopes happen to be any annotation classes that are themselves annotated with either javax.inject.Scope or javax.enterprise.context.NormalScope, but for this discussion we don’t really care about that for the moment.)

Let’s keep rolling with our singleton Gorp case.

When we introduced Contexts, we focused exclusively on the get methods.  But there is another interesting method on Context.  It is getScope.

That method returns an annotation class that basically ends up labelling the Context implementation.  The Context can now be matched or looked up under this annotation class label.

So, for example, CDI happens to ship with a built-in Context whose getScope method returns javax.inject.Singleton.class.

On the “other side”, it turns out you can mark certain Contextual implementations with that same annotation.  We’ll see exactly what shape this takes a little later; for now just know you can do it.

So if our Contextual{Gorp} implementation is somehow annotated with javax.inject.Singleton, then CDI now has what it needs: it can find the Context implementation indexed under Singleton.class, and “link” it with the Contextual{Gorp} implementation annotated with that annotation.

Then, assuming that typesafe resolution has succeeded, as it would in our trivial example, CDI now knows that it can complete the wiring automatically: our Backpack class will make an implicit request of CDI’s built-in-Context-implementation-associated-with-Singleton.class, and that Context implementation will use the Contextual{Gorp} that was annotated in some handwavy way with @Singleton.  The circuit is complete.

Our Backpack can now take delivery of a Gorp and anyone else who asks for a Gorp will get back the very same Gorp instance, not a new one.

Enough Handwaving

We’ve done a lot of handwaving to get to this point.

  • We’ve handwaved over what Contextual implementations can look like.
  • We’ve handwaved over how CDI figures out what producers and consumers exist in its world.
  • We’ve handwaved over how CDI figures out what Contexts exist in its world.
  • We’ve handwaved over exactly when CDI performs all this discovery.

We’ve probably also handwaved over a lot of other stuff.

At least some of the handwaving will start to end in the next post!

A CDI Primer: Part 1

In the previous article, we dabbled briefly in looking at the surface of the iceberg that is the CDI machine for making @Inject work as a way of answering some basic questions about what, exactly, CDI does and why you might want to use it.

We also, much more importantly, looked into the dependency injection mindset.  We talked about abstract notions of producers and consumers and wiring them together.  We introduced the idea that if you look through the right lenses, fields, methods and constructors can all be producers housed in particular producer classes.  And finally we pointed out that producers can be consumers and vice versa.

Now let’s talk about lifecycles.

Object Lifecycles and “Producer Proxies”

When a producer of any kind “wants” to make or supply or acquire an object, two decisions have to be made:

  1. how to make or supply or acquire the object
  2. when to make or supply or acquire the object regardless of how that happens

Some producers, as we saw in the previous article, are, as often found in the trenches of enterprise Java development, what I’ll call singleton suppliers.  They acquire the (mostly!) One True Instance™ of the object in question somehow, sometimes creating it once if necessary, sometimes by interrogating some ancient snarling hairball of a legacy system, and then from that time forward in the whole life of the application, that’s the object you get if you ask them to supply it to you.

Other producers, like constructors, create a new object each time one is to be produced because they can’t do anything else, or they’re kind of uninterested in the ways that they might be called, so they shrug and say, hey, if you want a new object, call me; otherwise, don’t; I don’t store or cache nothin’.

What’s interesting about producers of any kind, in isolation, without any other technologies such as CDI or its subsystems in play, is: producers in isolation combine how an object is produced with when it is produced.

For example, what I’ll call singleton suppliers—those all-too-common “enterprisey” methods that somehow acquire a Singleton From Elsewhere™ and then return it when asked—are combining the mechanics of how the singleton is produced (maybe it’s looked up from some other system) with when it is produced (maybe this system lookup only happens once and then the result is stored as a static singleton).

Or constructors: if you acquire an object from a constructor—a kind of producer, remember—then no matter what you do and no matter what it does you’ll get a new instance of the produced object each time because that’s what constructors do.

What would be nice is to let producers do what they do—acquire or make things when called for—and have there be some other subsystem that controls when a produced object is handed to a consumer.  Something that can go “back to the well”—the producer “well”—when needed, but not when not needed, and is in full control of when that happens, but does not itself know how the manufactured items it is storing or caching are made.  Something that is kind of like a proxy for producers: something that can stand in front of them and hand out their results when appropriate, regardless of how they were made or from what system they were acquired, according to its own notions of lifecycle.

ProducerConsumerUseCase

In such a situation a producer can focus on how to acquire an object but not on how to cache it; a producer proxy can focus on when to cache an object, if at all, and when to clear the cache; a consumer, in grand dependency injection mindset fashion, can remain blissfully ignorant of both of these things.

Also in grand dependency injection mindset fashion, we want this producer proxy (my term, incidentally, not CDI’s) to not look up or acquire or otherwise scrounge around for its relevant producer(s).  We want it to simply declare somehow that it needs one, and then punt the problem of getting one to its caller (we’ll talk about who that might be in a moment).

CDI implements this producer proxy concept with a construct called a Context and it is the first CDI construct we’ll look at in depth.

Contexts…

The first thing to know about a Context is that as a CDI end user you’ll interact with it many, many times—and as a consumer you’ll never see it or know that’s what you’re doing.

A Context, in other words, is part of the internal CDI plumbing by which automatic wiring between producers and consumers is implemented.

A Context is the nexus where a consumer needing an object of a certain kind is wired in an abstract fashion to a producer that is capable of producing objects of that kind, and where the lifecycle of such a produced object is managed.

Inside the depths of CDI, when you mark a field or a parameter with @Inject, CDI asks a particular Context for the kind of object you want.  That Context, in turn, ends up asking a producer, when necessary, to make or acquire the kind of object that should go in your @Inject-annotated slot.

From the standpoint of a Context, a producer is represented by something kind of odd called a Contextual.  A Contextual is simply a producer that can also destroy the things it makes.  A Contextual can make any number of different things of a given type (so, for example, a Contextual whose type parameter is Object could make Gorp, Chocolate, PeanutButter or whatever).  Most of the time, though, a given Contextual makes one kind of thing.

Finally, a Contextual should not have, as its core concern, or any concern if at all possible, how long an object should live—it is a “pure” producer: it just makes ’em, ma’am, it doesn’t hang onto ’em.

Here is what the contents of the Contextual interface look like, in their entirety, and for now we can ignore the second of these two methods:

I hope you can see how simple that is.

Contextual is another one of those interfaces that is in the internals of CDI.  You rarely, if ever, implement it directly.  But you could.  And you do in some cases, usually indirectly, as we’ll see much later.

For example, ignoring CreationalContext—a subject for a later post—you could see that you might implement the create method in such a way that it wraps a constructor invocation (you’d be implementing a producer that is constructor-based).  Or you could see that you could implement the create method in such a way that it wraps a method invocation (you’d be implementing a producer that is method-based), though consuming other dependencies in this case might be a little trickier.  Or a field access.  And in many cases your destroy implementation might not have to do anything.

The takeaway here is that you can represent all producers as Contextuals of a particular kind.

Context, then, uses Contextuals to produce the objects it will then manage the lifecycle of.  Here are the (relevant at the moment) contents of this interface, and trust me when I tell you that for now we can ignore the second method:

Again, very simple.

The first method is the real workhorse.  It takes in a Contextual and a CreationalContext, as you can see.  Once again, we’ll ignore the CreationalContext.  (The second method is for certain cases where CDI wants to ensure that no creation at all happens: it just wants the Context to supply a cached instance if one exists; it doesn’t want the Context to make a new one.  We’ll ignore it for the sake of mental clarity.)

The first method’s contract is to acquire and return a T.  You’ll note that Context itself is not a parameterized type (it doesn’t have any angle brackets or type parameters in its name).  So you can see here that a Context can get a whole variety of different kinds of objects.

You can also probably squint and see that if I tell you (as I have) that a Context‘s responsibility is to manage the lifecycle of objects, not actually make them, then when it decides that it needs a new one it can (and should) just call the create method on the Contextual that has just been handed to it.  The Context knows “when”; the Contextual knows “how”.

If it already has an existing instance and has determined that this incoming demand can be satisfied by the existing instance, well, then it can just hand it back.

That’s all very convenient.  So a Context as a consumer remains blissfully ignorant of what kind of Contextual (producer) has been handed to it, and can use this raw material if it wants in order to fulfill its contract of supplying T instances.  And the Contextual can remain blissfully ignorant of lifecycle and caching concerns and can just return Its Thing™, whatever that might be, when asked to make it.

…and Dependency Injection

CDI stands for Contexts and Dependency Injection.  And now with the introduction of Contexts we have an incomplete and blurry view—but a view nonetheless—of how the major parts work together, and why “Contexts” is important enough to be listed in the title of the specification:

  • A consumer of some kind (your business-critical class) gets wired in some currently opaque-to-us way (involving @Inject) to a Context implementation that supplies it with the dependency it needs (via the Context#get(Contextual, CreationalContext) method).
  • The Context implementation gets wired in some opaque way to a Contextual implementation that knows how, but not necessarily when, to make those kinds of things.
  • A Contextual is a kind of producer but everybody but the Contextual implementation itself doesn’t know what kind.

The result is that CDI is now conceptually capable of injecting dependencies, taking into account desired lifecycles, and letting producers and consumers and producer proxies all focus on what they do best, and on nothing else.

Contextual Instances

I’ve spoken very loosely about producers making things of a particular kind.  And I’ve spoken equally loosely about consumers needing things of a particular kind.  And I’ve spoken just as loosely about the wiring process where a producer of a thing of a particular kind gets wired in some fashion to a consumer that needs those things, mediated by a producer proxy—a neutral term I invented to describe the lifecycle/lifespan-managing component that decouples when something is handed out from how it is made or acquired.

Now we’ve also learned that producers in CDI are represented by Contextuals and are effectively “fronted” by Contexts, and that producer proxies are represented by Contexts, and that Contexts therefore are the sources of instances that producers—Contextuals—make.  Consequently when a Context‘s get method hands you (indirectly) an object, that object is known throughout CDI’s literature as a contextual instance.  It is an instance of something that a given Context manages.

Still speaking loosely, when you ask for a Gorp to be supplied to you (injected) by CDI by using the @Inject annotation, you’re going to get a contextual instance of Gorp in the annotated “slot”.

Or, equivalently: if an object “comes out of” a Context, then it is a contextual instance, and its existence must be owed to the fact that CDI invoked get on a Context and the Context ultimately invoked the create method of a Contextual that produced it.  CDI “knows about” all contextual instances.  CDI does not know about (for the most part) objects that are not contextual instances.

In the next post, we’ll look at the mechanics of how CDI wires Contextual implementations that can make certain contextual instances of particular kinds to Context implementations that implement a lifecycle, and how CDI wires consumers of contextual instances to Context instances that can provide them.