:title=OpenEJB 3.1.1 or later required}

The @LocalClient annotation (org.apache.openejb.api.LocalClient) is an innovation that crosses concepts of an Java EE Application Client with a plain Java SE client. This particular annotation is focused on clients of an Embeddable EJB container, i.e. local clients. There is another annotation in development called @RemoteClient that will be focused on remote clients; clients running outside the vm the container runs.

Any clients annotated with @LocalClient will be scanned at deployment time for usage of injection-related annotations. The references in the @LocalClient will be processed with the application just as if the class was a Java EE Application Client module, but with a few slight differences:

  1. Declaring field/method injection points as 'static' is not required
  2. References to EntityManagers via @PersistenceContext are allowed
  3. References to local business interfaces via @EJB is allowed
  4. References to UserTransaction via @Resource is allowed

As well since this is not a heavyweight Java EE Application Client, you are not required to use any special packaging or command-line parameters to run the client. Your client can be a Unit Test or any plain java code that needs to pull objects from the Embedded EJB container. Classes with @LocalClient can be placed in a Client module or an EJB module. A given module may have as many classes annotated with @LocalClient as it wishes.


The injection occurs via acquiring a LocalInitialContext via the LocalInitialContextFactory and calling bind("inject", instance) passing in the instantiated local client object:

public class MoviesTest extends TestCase {

    private Movies movies;

    private UserTransaction userTransaction;

    private EntityManager entityManager;

    public void setUp() throws Exception {
    Properties p = new Properties();
    p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
    InitialContext initialContext = new InitialContext(p);
    initialContext.bind("inject", this);

    //... other test methods


All EJB modules are scanned for @LocalClient classes, even if those EJB Modules are inside .war files as with the OPENEJB:Collapsed EAR . As well any modules that contain a META-INF/application-client.xml file will be scanned for @LocalClient classes.

If you see the following error message and are absolutely sure the module containing your @LocalClient class is being properly identified as an EJB module or a Client module, than it is possible you are seeing some classloading issues.

} javax.naming.NamingException: Unable to find injection meta-data for org.superbiz.MyClient. Ensure that class was annotated with @org.apache.openejb.api.LocalClient and was successfully discovered and deployed.

If you encounter this try setting this openejb-specific boot flag so that annotations will be treated specially and always loaded by the parent classloader


Copyright © 1999-2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.