OpenEJB was founded on the idea that it would be embedded into third-party environments whom would likely already have three things:

• their one "server" platform with existing clients and protocols
• their own way to configure their platform
• existing services like TransactionManager, Security, and Connector

Thus the focus of OpenEJB was to create an EJB implementation that would be easily embeddible, configurable, and customizable.

Part of achieving that is a drive to be as simple as possible as to not over-define and therefore restrict the ability to be embeddible, configurable and customizable. Smaller third-party environments could easily 'downscale' OpenEJB in their integrations by replacing standard components with lighter implementations or removing them all together and larger environments could 'upscale' OpenEJB by replacing and adding heavier implementations of those standard components likely tailored to their systems and infrastructure.

Container and Server are mentioned in the EJB spec as being separate things but are never defined formally. In our world Containers, which implement the basic component contract and lifecycle of a bean are not coupled to any particular Server, which has the job of providing a naming service and providing a way for it's clients to reference and invoke components (beans) hosted in Containers. Because Containers have no dependence at all only Server, you can run OpenEJB without any Server at all in an embedded environment for example without any work or any extra overhead. Similarly you can add as many new Server components as you want without ever having to modify any Containers.

There is a very strong pluggability focus in OpenEJB as it was always intended to be embedded and customized in other environments. As a result all Containers are pluggable, isolated from each other, and no one Container is bound to another Container and therefore removing or adding a Container has no repercussions on the other Containers in the system. TransactionManager, SecurityService and Connector also pluggable and are services exposed to Containers. A Container may not be dependent on specific implementations of those services. Service Providers define what services they are offering (Container, Connector, Security, Transaction, etc.) in a file they place in their jar called service-jar.xml.

The service-jar.xml should be placed not in the META-INF but somewhere in your package hierarchy (ours is in /org/apache/openejb/service-jar.xml) which allows the services in your service-jar.xml to be referenced by name (such as DefaultStatefulContainer) or more specifically by package and id (such as org.apache.openejb#DefaultStatefulContainer).

The same implementation of a service can be declared several times in a service-jar.xml with different ids. This allows for you to setup several several different profiles or pre-configured versions of the services you provide each with a different name and different set of default values for its properties.

In your openejb.conf file when you declare Containers and Connectors, we are actually hooking you up with Service Providers automatically. You get what is in the org/apache/openejb/service-jar.xml by default, but you are able to point specifically to a specific Service Provider by the 'provider' attribute on the Container, Connector, TransactionManager, SecurityService, etc. elements of the openejb.conf file. When you declare a service (Container, Connector, etc.) in your openejb.conf file the properties you supply override the properties supplied by the Service Provider, thus you only need to specify the properties you'd like to change and can have your openejb.conf file as large or as small as you would like it. The act of doing this can be thought of as essentially instantiating the Service Provider and configuring that instance for inclusion in the runtime system.

For example Container(id=NoTimeoutStatefulContainer, provider=DefaultStatefulContainer) could be declared with it's Timeout property set to 0 for never, and a Container(id=ShortTimeoutStatefulContainer, provider=DefaultStatefulContainer) could be declared with it's Timeout property set to 15 minutes. Both would be instances of the DefaultStatefulContainer Service Provider which is a service of type Container.

Overview

This example demonstrates the use of the injection of environment entries using @Resource annotation.

"EJB Core Contracts and Requirements" specification section 16.2.2"

• "A field or method of a bean class may be annotated to request that an entry from the bean's environment
  be injected. Any of the types of resources or other environment entries described in this chapter may
  be injected. Injection may also be requested using entries in the deployment descriptor corresponding to
  each of these resource types."

• "Environment entries may also be injected into the bean through bean methods that follow the
  naming conventions for JavaBeans properties. The annotation is applied to the set method for
  the property, which is the method that is called to inject the environment entry. The JavaBeans
  property name (not the method name) is used as the default JNDI name."

PurchaseOrderBean class shows use of @Resource annotation through a bean field.

InvoiceBean class shows the use of @Resource annotation through a setter method.

The source for this example can be checked out from svn:

$ svn co http://svn.apache.org/repos/asf/incubator/openejb/trunk/openejb3/examples/resource-injection/^{Image Removed}

To run the example change to the directory containting example and run Maven:
(openejb3_project_dir is the top level directory of OpenEJB3 project)

$ cd <openejb3_project_dir>/examples/resource-injection

$ mvn clean install

The Code

Injection through field

maxLineItem field in PurchaseOrderBean class is annotated with @Resource annotation to inject a simple environment entry. Default value of10 is assigned. Deployer can modify the values of the environment entries at deploy time in deployment descriptor.

@Resource annotation of a field

@Resource
int maxLineItems = 10;

Injection through a setter method

setMaxLineItem method in InvioceBean class is annotated with @Resource annotation to inject a simple environment entry. By default, the JavaBeans propery name is combined with the name of the class in which the annotation is used and is used directly as the name in the bean's naming context. JNDI name for this entry would be:

• java:comp/env/org.apache.openejb.examples.resource.InvoiceBean/maxLineItems

@Resource annotation of a setter method

 
@Resource
public void setMaxLineItems(int maxLineItems) {
    this.maxLineItems = maxLineItems;
}

env-entry in ejb-jar.xml

...

<env-entry>
     <description>The maximum number of line items per invoice.</description>
     <env-entry-name>org.apache.openejb.examples.injection.InvoiceBean/maxLineItems</env-entry-name>
     <env-entry-type>java.lang.Integer</env-entry-type>
     <env-entry-value>15</env-entry-value>
</env-entry>

Using @Resource annotated env-entry

public void addLineItem(LineItem item) throws TooManyItemsException {
   if (item == null) {
      throw new IllegalArgumentException("Line item must not be null");
   }

   if (itemCount <= maxLineItems) {
      items.add(item);
      itemCount++;
   } else {
      throw new TooManyItemsException("Number of items exceeded the maximum limit");
   }
}

JUnit Test

Writing an JUnit test for this example is quite simple. We need just to write a setup method to create and initialize the InitialContext, and then write our test methods.

Test fixture

protected void setUp() throws Exception {
    Properties properties = new Properties();
    properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
    properties.setProperty("openejb.deployments.classpath.include", ".*resource-injection.*");
    initialContext = new InitialContext(properties);
}

Test methods

public void testAddLineItem() throws Exception {
    Invoice order = (Invoice) initialContext.lookup("InvoiceBeanBusinessRemote");
    assertNotNull(order);
    LineItem item = new LineItem("ABC-1", "Test Item");

    try {
        order.addLineItem(item);
    } catch (TooManyItemsException tmie) {
        fail("Test failed due to: " + tmie.getMessage());
    }
}

Running

Running the example is fairly simple. Just execute the following commands:

$ cd <openejb3_project_dir>/examples/resource-injection
$ mvn clean install

...