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.
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.
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.
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.
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) {
.
.
.
@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.
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. |