Accessing Enterprise JavaBeans in OSGi applications

There are alternative mechanisms that you can use in a client bundle to access an enterprise bean in a service bundle. To maximize application availability during an update to a service bundle that contains one or more enterprise beans, use OSGi service references to access the enterprise beans.

From an OSGi client bundle, you can access an enterprise bean in a service bundle in any of the following ways:
  • Define a <reference> element, in the Blueprint XML file of the client bundle, that refers to the enterprise bean.
  • Use an @EJB annotation.
  • Define an EJB reference that is mapped to the JNDI name of the bean.
  • Use an "osgi:service/" JNDI lookup.

The alternative ways of accessing an enterprise bean, and the corresponding differences in application behaviour during an update to the service bundle, are discussed in more detail in the remaining sections of this topic.

Using a <reference> element to access an enterprise bean

You can access an enterprise bean by defining a reference element for the bean in the Blueprint XML file of the client bundle; for more information, see References and the Blueprint Container.

The enterprise bean must be in the list specified by the Export-EJB header in the bundle manifest file of the service bundle, or the value of the Export-EJB header must be set to a single space character so that all enterprise beans in the bundle are exported; for more information, see the description of the Export-EJB header in the bundle manifest file.

To access the enterprise bean from a blueprint-managed bean, you can inject the enterprise bean through a property on the blueprint-managed bean; for details, see References and the Blueprint Container.

To access the enterprise bean from a component that is not blueprint-managed, such as a servlet, use a "blueprint:comp/" JNDI lookup; for details, see JNDI lookup for blueprint components.

If you subsequently update the service bundle, the client bundle does not have to be restarted. During the update operation, an end user might experience a brief delay, because the service reference is damped, so the client bundle waits for the update operation to complete, rather than a runtime exception being thrown.

Using an @EJB annotation or an EJB reference to access an enterprise bean

You can create a reference to an enterprise bean in either of the following ways:
  • Use an @EJB annotation in the source code of the client bundle.
  • Define an EJB reference in an ejb-jar.xml or web.xml file and use a JNDI lookup in the source code.
In either case, you map the reference to the enterprise bean JNDI name in an ibm-ejb-jar-bnd.xml or ibm-web-bnd.xml file in the bundle, or in the WebSphere® Application Server administrative console when you deploy the bundle.

WebSphere Application Server automatically generates an enterprise bean JNDI name and maps the enterprise bean to it. In addition, you can explicitly map the enterprise bean to a JNDI name in the ibm-ejb-jar-bnd.xml file in the service bundle, or in the WebSphere Application Server administrative console when you deploy the bundle.

If you explicitly map the enterprise bean, and you subsequently update the service bundle, the client does not have to be restarted, but the service bundle is briefly unavailable, during which time a runtime exception is thrown if the client bundle attempts to call a method on the enterprise bean.

If you do not explicitly map the enterprise bean, and you subsequently update the service bundle, the JNDI name changes. The EJB reference to the JNDI name in the client bundle is updated automatically and the client bundle is restarted, during which time the client bundle is unavailable. In addition, the service bundle is briefly unavailable during the update operation, and if the client bundle becomes available before the service bundle and attempts to call a method on the enterprise bean, a runtime exception is thrown.

Using an "osgi:service/" lookup to access an enterprise bean

You can access an enterprise bean by using, in the source code of the client bundle, an "osgi:service/" lookup, in either of the following ways:
  • Use a JNDI lookup with a URL of the following form:
    osgi:service/interface_name/optional_filter
    For example:
      try {
        InitialContext ic = new InitialContext();
        return (BloggingService)
          ic.lookup("osgi:service/com.ibm.samples.websphere.osgi.blog.api.BloggingService");
      } catch (NamingException e) {
          .
          .
          .
  • Inject a reference to the enterprise bean by using an @Resource annotation of the following form:
    @Resource(lookup="osgi:service/interface_name/optional_filter")
    For example:
    @Resource(lookup="osgi:service/com.ibm.samples.websphere.osgi.blog.api.BloggingService")
    BloggingService bloggingService;

If you subsequently update the service bundle, the client bundle continues to run without interruption, but a ServiceUnavailableException is thrown if the code attempts to use the service object while the service bundle is being updated, so the source code must be written to handle this situation.

For details of the OSGi URL scheme, see section 126.6 of the OSGi Service Platform Release 4 Version 4.2 Enterprise Specification.

Summary

The following table summarizes the degree of availability during an update to an OSGi application that contains enterprise beans, depending on the enterprise bean access mechanism used:
Access mechanism Summary of application availability
OSGi service reference The client bundle remains available. The service reference is damped, so client threads block until the EJB service becomes available again.
@EJB annotation or EJB reference, with explicit JNDI name mapping The client bundle remains available. If the client bundle attempts to use the injected EJB, a runtime exception is thrown during the service bundle update.
"osgi:service/" JNDI lookup or injected reference The client bundle remains available. If the client bundle attempts use the injected EJB, a runtime exception is thrown during the service bundle update. This behavior is similar to using an @EJB annotation or EJB reference with explicit JNDI name mapping, but more client code is required to achieve the same result.
@EJB annotation or EJB reference, without explicit JNDI name mapping The client bundle is restarted. If the client bundle becomes available before the service bundle, attempts use the injected EJB will result in runtime exceptions being thrown until the service bundle update is complete.

Icon that indicates the type of topic Reference topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-base-iseries&topic=ra_access_ejbs
File name: ra_access_ejbs.html