Using enterprise JavaBeans with remote interfaces on Liberty
You can remotely access Enterprise Bean (EJB) methods with remote interfaces when the
Enterprise Bean is hosted by another Java virtual machine (JVM) or another application within the
same JVM. WebSphere® Application Server implements remote Enterprise Bean interfaces by using
RMI-IIOP technologies. You can enable remote Enterprise Bean support with the
ejbRemote-3.2
or enterpriseBeansRemote-4.0
feature.
About this task
To configure a Liberty server to run an
application with remote enterprise beans support enabled, you must set the
ejbRemote-3.2
or enterpriseBeansRemote-4.0
feature.
When you use remote enterprise beans interfaces, review the following considerations:
- Naming
-
- Using the
java:
namespace -
The Enterprise Beans specification requires that remote interfaces are bound to the
java:
namespace, which is available to the application server and the application client container, as shown in the following example:java:global/ExampleApp/ExampleModule/ExampleBean!com.ibm.example.ExampleRemoteInterface java:app/ExampleModule/ExampleBean!com.ibm.example.ExampleRemoteInterface java:module/ExampleBean!com.ibm.example.ExampleRemoteInterface
In version 20.0.0.12 and later, enterprise beans components are bound to both the default and the
ejblocal:
Java Naming and Directory Interface (JNDI) namespaces, as in WebSphere® Application Server traditional. In these versions, for enterprise beans components that are hosted within the same server,@EJB
lookups and bindings inibm-*-bnd.xml/xmi
files can use either thejava:
namespace or the heritage namespaces from WebSphere Application Server traditional. For enterprise beans components that are hosted in another server, lookups and bindings can usecorbaname
URLs. Before version 20.0.0.12, enterprise beans components are not bound to the default JNDI namespace and must use thejava:
names for enterprise beans components that are hosted within the same server. - Using
corbaname
URLs -
Interfaces are also bound to the ORB CosNaming name service in similar contexts to those interfaces used in the
java:global
namespace. These interfaces can be accessed through JNDI by usingcorbaname
URLs; for example:corbaname::test.ibm.com:2809#ejb/global/ExampleApp/ExampleModule/ExampleHomeBean!com.ibm.example.ExampleEJBHome corbaname:rir:#ejb/global/ExampleApp/ExampleModule/ExampleHomeBean!com.ibm.example.ExampleEJBHome
On the server, the
rir:
form of the URL uses the local name service. On the client, it uses the default or configured remote name service. - Escaping
corbaname
URLs -
According to the Object Management Group (OMG) Naming Service specification, some characters in
corbaname
URLs must be escaped. Liberty tries to determine whether acorbaname
URL that is derived from thejava:global
namespace needs to be escaped, and then escapes it automatically. It is not possible to do the escape in all cases. For example, if a name contains a single dot (.), and has no invalid characters, it cannot be escaped automatically. To force a name to be interpreted in a particular way, it is necessary to escape the URL manually as described in the OMG Naming Service specification.Consider the followingjava:global
name for an enterprise bean:
The simple form of thejava:global/TestApp/TestModule/TestBean!test.TestRemoteInterface
corbaname
URL cannot be escaped automatically because it represents a different, but valid location. Therefore, the following URL does not work as expected:
Instead, this URL must be manually escaped as follows:corbaname:rir:#ejb/global/TestApp/TestModule/TestBean!test.TestRemoteInterface
corbaname:rir:#ejb/global/TestApp/TestModule/TestBean!test%5c.TestRemoteInterface
Not all client and application server implementations support the use of%5c
in a JNDI name to represent an escape character. For these implementations, including WebSphere Application Server traditional, the backslash (\
) character can be used directly. Because a backslash must be escaped in a Java String, the URL can be manually escaped as shown in the following example:corbaname:rir:#ejb/global/TestApp/TestModule/TestBean!test\\.TestRemoteInterface
The syntax for escaping
corbaname
URLs is described fully in OMG Naming Service specification. - Using JNDI names programmatically
-
All of the URLs and JNDI names in these examples can be looked up programmatically from an
InitialContext
. When you look up ajava:
name, the resulting object can be cast directly to the expected type; for example:
However, when you retrieve objects by usingObject found = new InitialContext().lookup("java:global/ExampleApp/ExampleModule/ExampleBean!com.ibm.example.ExampleRemoteInterface"); ExampleRemoteInterface bean = (ExampleRemoteInterface) found;
corbaname
URLs, the RMI style of casting, called narrowing, must be used; for example:Object found = new InitialContext().lookup("corbaname:rir:#ejb/global/ExampleApp/ExampleModule/ExampleBean!com.ibm.example.ExampleRemoteInterface"); ExampleRemoteInterface bean = (ExampleRemoteInterface)PortableRemoteObject.narrow(found, ExampleRemoteInterface.class);
If the same context is used to look up multiple enterprise beans from the same remote server, thecorbaloc
value can be used when you create theInitialContext
class, as shown in the following example:Properties p = new Properties(); p.put(Context.PROVIDER_URL, "corbaloc::test.ibm.com:2809"); InitialContext c = new InitialContext(p); Object found = c.lookup("ejb/global/ExampleApp/ExampleModule/ExampleBean!com.ibm.example.ExampleRemoteInterface"); ExampleRemoteInterface bean = (ExampleRemoteInterface)PortableRemoteObject.narrow(found, ExampleRemoteInterface.class);
- Using the
- Interoperability
- Any product that supports the IIOP protocol can call enterprise beans that use the EJB 2.x
remote programming model with
EJBHome
andEJBObject
when it is packaged in an EJB JAR module with a version 2.0 deployment descriptor. The WLP_INSTALL_DIR/clients/ejbRemotePortable.jar file must be included on the class path of the remote client. This file contains system value classes that are required for communication with a Liberty server. This file is not required when you remotely access enterprise beans components from the WebSphere Application Server Liberty or WebSphere Application Server traditional. enterprise beans components that use the EJB 3 remote programming model on Liberty can be remotely accessed by WebSphere Application Server processes. Liberty does not provide a thin client to start enterprise beans components from a stand-alone Java process. Liberty does not provide workload management or failover capabilities for remote enterprise beans components, including when you start enterprise beans components that are hosted from WebSphere Application Server traditional. - Stub classes
- A client must include stub classes when you start a remote enterprise bean that is hosted on an
WebSphere Application Server. In some cases, if the client is WebSphere Application Server, the
product automatically generates the correct stub classes:
- If a client application starts a remote enterprise bean that is contained within the same application, Liberty automatically generates stub classes.
- If the target enterprise bean is running in a separate application and is using the EJB 2.x
remote programming model with
EJBHome
andEJBObject
, then the client must include stub classes on its class path. If the EJB is hosted on WebSphere Application Server traditional, you can copy the EJB client JAR from the application from the EAR after it is processed by the ejbdeploy command. If the enterprise beans is hosted on Liberty, you must use the rmic program that is included with your Java SDK to generate the stub classes for the target enterprise bean, and then you must include the stub classes with the client. - If the target enterprise bean is running in a separate application and is using the EJB 3 remote programming model, then the client Liberty or WebSphere Application Server traditional process automatically generates stub classes. Enterprise Beans components that use the EJB 3 remote programming model on Liberty can be remotely accessed by WebSphere Application Server or WebSphere Application Client processes only.
- Transaction propagation
- Liberty does not support outbound or
inbound transaction propagation. Additionally, the Enterprise Beans specification requires that,
even if a product supports outbound transaction propagation, it must still send a null transaction
context. This context must be rejected by enterprise beans components that use the
Required
(default),Mandatory
, orSupports
transaction attributes. A client with an active global transaction cannot start an enterprise bean with default transaction attributes if either the client or server is in Liberty. The client can start the enterprise bean if the enterprise bean is changed to use theRequiresNew
orNotSupported
transaction attributes. However, the transactional work that is done by the enterprise bean is not committed as part of the transactions of the client. - Asynchronous methods
- An enterprise beans remote interface can have an asynchronous method with a return value of type
Future
. The server will return a Future object to the client, which is used to retrieve the value. Remote asynchronous methods are not recommended because accumulation of unclaimed results can exhaust memory. To mitigate this problem, the server results expire if the client does not retrieve the result within 24 hours or if the maximum number of unclaimed results exceeds 1000. These values can be adjusted in the server.xml file; for example:<ejbContainer> <async maxUnclaimedRemoteResults="10"unclaimedRemoteResultTimeout="10m"/> </ejbContainer>