| Title: Local Client Injection |
| {note: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 |
| 1. References to EntityManagers via @PersistenceContext are allowed |
| 1. References to local business interfaces via @EJB is allowed |
| 1. 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. |
| |
| <a name="LocalClientInjection-Injection"></a> |
| # Injection |
| |
| The injection occurs via acquiring a LocalInitialContext via the |
| LocalInitialContextFactory and calling _bind("inject", instance)_ passing |
| in the instantiated local client object: |
| |
| |
| @LocalClient |
| public class MoviesTest extends TestCase { |
| |
| @EJB |
| private Movies movies; |
| |
| @Resource |
| private UserTransaction userTransaction; |
| |
| @PersistenceContext |
| 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 |
| } |
| |
| |
| <a name="LocalClientInjection-Discovery"></a> |
| # Discovery |
| |
| All EJB modules are scanned for @LocalClient classes, even if those EJB |
| Modules are inside .war files as with the [Collapsed EAR](collapsed-ear.html) |
| . 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. |
| |
| {panel} |
| 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. |
| {panel} |
| |
| 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 |
| |
| `openejb.tempclassloader.skip=annotations` |
| |
| |