This documents outlines the design of jboss-injection which takes care of setting up the naming environment of application components and subsequently injecting them.

Status

A work-in-progress.

Scope

The component needs to take care of all functionality as defined in JavaEE 6 chapter 5, Resources, Naming and Injection.

The creation of Application Component Environment Namespaces (EE.5.2.2) is delegated to reloaded-naming. Reloaded-naming does nothing in terms of populating these namespaces with the exception of AppName and ModuleName as specified in EE.5.15.

Beyond scope is EE.5.3.4 last bullet, read only access for application components.

Consumers

There are two types of consumers for the jboss-injection component:

1. Application component frameworks that require injection (EE 6 page 69 table EE.5-1)
2. Resource providers that can be queried using resource references (see EE.5.1.1).

Technical Requirements

The core implementation should not depend on MicroContainer or other AS specific constructs. It should be possible to run these components in both AS 6 and AS 7.

Switchboard

One part of jboss-injection is the Switchboard component. From the perspective of an application component java:comp can be seen a switchboard to external resources. Switchboard (operator) is responsible for setting up java:comp on behalf of the application component.

Important to note is that Switchboard can not rely on resources to be globally available in JNDI. For example a Persistence Unit might not bind a PersistenceContext into global JNDI. Also some resource references have specific requirements untied to the globally bound resource, for example message-destination-usage on a message-destination-ref. For this reason Switchboard can not rely on using LinkRef alone to accomplish its goals.

Note that in most cases Switchboard can function without the actual resource provider being ready. If a resource provider can supply a LinkRef to something that does not exist yet, Switchboard can attain its goal of populating java:comp.

For each application component there is a Switchboard instance counterpart (in case of war deployments it'll be for the module). An application component container/manager (conceptually) injects this instance. The application component itself does nothing with Switchboard, it's only meant to make sure there is an explicit dependency.

@Deprecated
public interface JavaEEComponent {
   @Resource
   void setSwitchboard(Switchboard sb);
}

Refer to the SwitchBoard wiki for more details.

Injector

The second part of jboss-injection is the injector. It makes sure that an application component instance is properly injected with the values from the naming environment.

This is just iterating over some bits that do a lookup in java:comp and subsequently set the property with that value.

For each application component there is a separate Injector instance.

To make sure the naming context entries are available for injection the Injector creates an explicit dependency on the proper Switchboard instance.

public interface Injector {
   @Resource
   void setSwitchboard(Switchboard sb);
}

The Injector makes sure it can function after it has been constructed by setting explicit dependencies on the resources provided.

public interface JavaEEComponent {
   @Resource
   void setInjector(Injector injector);
}

Injector API

A proposal for the Injector API has been submitted by Pete: http://gist.github.com/579034. It has been translated into a working prototype by Marius and Jaikiran: https://github.com/jaikiran/jboss-injection.

Random Notes

This section contains notes that are related to injection, but not yet properly incorperated into the design itself.

Dependencies & SLSB

A lookup of a stateless bean does not fire up any injection, because no instance will be created. So the EJB container must not have any dependencies to bring up the stateless bean binding. While on invocation the EJB container should be ready to service the request fully.

This will be resolved by having a separate JNDI binder for EJBs. The SLSB binder will bind a lazy proxy on the proper JNDI name and provide a resource provider to resolve the proper EJB references.

Singleton Startup

EJB 3.1 4.8.1 Singleton Initialization:

"[...] if a Singleton has been designated [...] as requiring eager initialization, the container must initialize [...] all such startup-time Singletons before any external client requests (that is, client requests originating outside of the application) are delivered to any enterprise bean components in the application."

The DependsOn annotation is used to express explicit initialization ordering dependencies between multiple Singleton components in an application.