JBoss.orgCommunity Documentation

Chapter 12. TorqueBox Resource Injection

12.1. What is Resource Injection?
12.2. Basics of Resource Injection
12.3. Injectable Resources
12.4. Internals and Testing

Resource injection is the term given a software architectural strategy that moves the responsibility of finding and connecting components to a container, allowing components to remain simple and testable. Components declare what they need, and when instantiated by the container, the container also satisfies those needs.

What's a resource?

A resource may be most any component within your application, ranging from instances of Java classes, to messaging destinations.

TorqueBox supports injection within the context of jobs, services, messaging-handlers, Stomplets and web applications. To look up a value from the injection registry, use the TorqueBox.fetch(...) method.

For instance:

A variety of resources may easily be injected with the TorqueBox.fetch(...) method.

CDI Resources

The Java Context and Depedency Injection (CDI) spec defines a method for managing relationships between components. CDI-enabled components may be injected by providing a fully-qualified Java class name to the TorqueBox.fetch(...) method. Typically CDI components should be packaged in a JAR archive, and placed in your application's lib/ or vendor/jars/ directory.

TorqueBox uses the JBoss Weld implementation of CDI. Please see the Weld website for more information.

class MyService

  def initialize()
    @java_service = TorqueBox.fetch(com.mycorp.MyJavaService)
  end

end

JRuby explicitly supports the simple syntax for common US-centric package names starting with com, org, net, java, and javax, amongst others. For other top-level packages based on country codes, such as pl, de, or za, to perform injection you should reference your class through the Java ruby package.

TorqueBox.fetch(Java::pl.softwaremine.PolishingService)

CDI Injection Requires Full Distribution

You must be running the full distribution of TorqueBox on top of JBoss EAP in order to use CDI injection.

Messaging Destinations

Message destinations, such as queues and topics, may be injected into your components. If the argument to TorqueBox.fetch(...) includes the string fragment "/queue" or "/topic", TorqueBox will look up the relevant TorqueBox::Messaging::Queue or TorqueBox::Messaging::Topic.

Using injection is the preferred method for obtaining a reference to a destination, to ensure that your job, service or web application relying upon the destination does not begin operation until the destination has been completely provisioned.

Naming & Directory Entries

Arbitrary items within the application's naming environment may be injected if the argument to TorqueBox.fetch(...) begins with "java:comp/env".

JBoss MSC Services

JBoss Modular Service Container is the container that drives the entire TorqueBox AS. Many components are accessible as MSC Services. These may be injected by passing the ServiceName as a string to TorqueBox.fetch(...).

Services

TorqueBox Services may be injected into your components if the argument to TorqueBox.fetch(...) begins with "service:" followed by the key used to configure the service in torquebox.yml.

At runtime, each TorqueBox.fetch(...) method looks up the injected resource through the TorqueBox::Registry singleton. In test environments, you may desire to populate this registry, using the merge!(...) method, which accepts a key/value Hash.

The key for each entry should match either the string argument used with TorqueBox.fetch(...), or the Ruby version of the Java class name, if performing CDI injection. The value should be an appropriate object.

For instance, the Java class of java.util.Set should be converted into a string of "Java::JavaUtil::Set" when used as an injection look-up key.