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. Variants of inject(...)
12.5. Internals and Testing
12.6. Disabling the Injection Scanner

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. The two key components of using the injection capabilities are:

TorqueBox supports injection for source files in the following locations (relative to the root directory of your application):

For instance:

TorqueBox::Injectors also provides an __inject__(...) method that can be used in classes that override the inject(...) method (classes that include Enumerable, for example). It is interchangeable with the inject(...) calls in any of the injection examples.

A variety of resources may easily be injected with the inject(...) 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 inject(...) 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

  include TorqueBox::Injectors

  def initialize()
    @java_service = inject( 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.

inject( Java::pl.softwaremine.PolishingService )

Messaging Destinations

Message destinations, such as queues and topics, may be injected into your components. If the argument to inject(...) includes the string fragment "/queue" or "/topic", TorqueBox will inject 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 inject(...) 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 inject(...).

Services

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

While the inject(...) method is overloaded to detect the correct type of resource, there are occasions where it may guess incorrectly. To overcome this, variant are provided that explicitly direct the injection analyzer to look for a specific type of resource. For string-based injections, the previously mentioned matching rules do not apply to the injection method variants.

inject_cdi(...)

Injects CDI resources by literal class name.

inject_queue(...)

Injects a messaging queue by literal name.

inject_topic(...)

Injects a messaging topic by literal name.

inject_naming(...)

Injects JNDI resources by literal name.

inject_msc(...)

Injects MSC services by literal name.

inject_service(...)

Injects a TorqueBox application service component

At runtime, each inject(...) 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 inject(...), 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 lookup key.

If you're not making use of injection, you can disable the injection scanner on a per-application basis. Simply add:

to your -knob.yml or torquebox.yml file, and injection scanning will be disabled for your application.