Migrating EJB Applications
Traditional WebSphere Application Server → WebSphere Liberty
Purpose and Scope
Why does this document exist?
Many teams experience unexpected challenges when migrating EJB based applications from Traditional WebSphere Application Server (tWAS‑) to WebSphere Liberty. Although both runtimes are IBM products and support Java EE specifications, they differ significantly in architecture, runtime behavior, and EJB integration mechanisms.
Typical migration pain points include:
- Differences in EJB support levels (Lite vs Full)
- Incompatible or unsupported Entity Beans
- Remote EJB lookup failures due to different ORB implementations
- Changes in JNDI naming conventions
- Dependencies on IBM-specific extensions available only in traditional WAS
- ORB and IIOP interoperability issues between Liberty and tWAS
This document exists to:
- Explain why these issues occur
- Clarify EJB and ORB differences between Traditional WAS and Liberty
- Provide practical guidance to reduce migration risk
- Help teams understand what must change, what will work, and what will not
For additional EJB lookup scenarios—including tWAS-to-Liberty, Liberty-to-tWAS, Java Thin Client-to-Liberty, Liberty-to-Liberty, and J2EE LaunchClient-to-Liberty remote lookups—see this blog.
EJB Support Differences
Q: What is the overall difference in EJB support between Traditional WebSphere and Liberty?
A:
Traditional WebSphere Application Server implements a full, historically complete EJB model, including legacy features and IBM extensions.
WebSphere Liberty is a lightweight, modular runtime that supports both the Lite and Full profiles of the EJB specification. What Liberty does not support is optional functionality such as Entity Beans and older IBM extensions, some of which have been replaced by more modern specifications, such as JPA.
Q: How do EJB specification levels differ between tWAS and Liberty?
A:
|
Runtime
|
EJB Level
|
Entity Beans
|
|
tWAS 8.5.5
|
EJB 3.1
|
Required, supported
|
|
tWAS 9.0.5
|
EJB 3.2
|
Optional, supported
|
|
Liberty
|
EJB 3.1 Lite
|
Not Required, Not supported
|
|
Liberty / Open Liberty
|
EJB 3.2 and Enterprise Beans 4.0
|
Optional, not supported
|
Even though Liberty supports newer EJB specifications, Entity beans are intentionally excluded since they have been replaced by JPA
Q: Why does Liberty not support Entity Beans even though EJB 3.2 allows them?
A:
Beginning with EJB 3.2, Entity Beans became an optional feature. Vendors are not required to support them.
Liberty was designed as:
- Lightweight
- Modular
- Optimized for containers and microservices
Entity Beans:
- Require older deployment tooling (EJBDeploy)
- Introduce performance and lifecycle complexity
- Are functionally replaced by JPA
As a result, Liberty does not implement the optional Entity Bean feature, even though Traditional WAS does.
ORB and Remote EJB Differences
Q: What role does the ORB play in EJB communication?
A:
An Object Request Broker (ORB) enables communication between distributed Java components using RMI/IIOP. It allows:
- Clients to invoke methods on remote EJBs
- Location transparency between client and server processes
- Interoperability across JVMs and servers
EJB remote access is fundamentally ORB‑dependent.
Q: What ORB does Traditional WebSphere use?
A:
Traditional WebSphere uses the IBM ORB, which:
- Is tightly integrated into the full WAS runtime
- Supports extensive IBM extensions
- Provides strong backward compatibility for older EJB applications
Many older applications rely—often unintentionally—on these behaviors.
Q: What ORB does WebSphere Liberty use, and how is it different?
A:
WebSphere Liberty uses Yoko ORB, which:
- Is an open‑source, CORBA 2.3‑compliant ORB
- Is maintained by IBM and forked from Apache Yoko
- Is stricter and more standards‑compliant
- Avoids IBM‑specific extensions found in traditional WAS
The real interoperability issues stem from the difference in the WebSphere traditional and Liberty NameService implementations, and not so much the ORB.
Q: Why do remote EJB lookups often fail after migrating to Liberty?
A:
WebSphere traditional provides
- A Federated (or distributed) NameService
- Supports the spec-defined Java: namespaces locally in a server (i.e., Java: JNDI names are generally not accessible remotely)
- Supports WebSphere proprietary JNDI names (default and custom) for lookup in the server locally (server root JNDI context)
- Supports topology-based (qualified) JNDI names to remotely look up EJBs anywhere in the Cell - using the proprietary names
- Supports fixed (persistent) JNDI names also available anywhere in the Cell
Liberty provides
- A lightweight, simplified NameService
- Supports the spec-defined Java: namespaces locally in a server (i.e., Java: JNDI names are generally not accessible remotely)
- Supports WebSphere proprietary JNDI names (default and custom) for lookup in the server locally (server root JNDI context)
- Does not support either topology-based or fixed JNDI names; not possible to access the proprietary JNDI names remotely
- Supports a simplified remote JNDI name derived from the specification-defined Java:global name.
- Simply replace the "Java:global" prefix with "corbaname::<host>:<port>#ejb/global" prefix.
Reference :
Q: What JNDI format is required for remote EJB lookups in Liberty?
A:
Liberty requires the standard CORBA/IIOP format:
corbaname::host:port#ejb/global/AppName/[ModuleName/]BeanName!Interface
Key points:
- Custom tWAS JNDI names will work on Liberty, but only locally; not remotely between servers.
- java:global works only inside the same server for both traditional and Liberty.
- Yes, remote lookups always require corbaname.
Q: Can Liberty access remote EJBs from Traditional WAS and vice versa?
A:
Yes, but only if:
- Remote interfaces exist
- It is not a Remote EJB if a Remote interface does not exist. So, this may be redundant since this question is about remote EJBs.
- IIOP ports are accessible
- IIOP ports are required, regardless of server type.
- Correct corbaname formatting is used
- It is important to know that the "corbaname format" for a tWAS EJB is different from that of a Liberty EJB. Specifically, the JNDI part after the
#
- Security settings are compatible
When Liberty accesses an EJB that exists on tWAS, then Liberty is effectively considered a "thin client" of tWAS and would need to follow the documentation for tWAS clients. These topics attempt to cover some of the details:
https://www.ibm.com/docs/en/was-nd/8.5.5?topic=interface-example-looking-up-ejb-home-cosnaming
https://www.ibm.com/docs/en/was-nd/9.0.5?topic=applications-running-thin-client-enterprise-javabeans-ejb
Net is, when Liberty is the client, the corbaname would look like: corbaname:iiop:myHost:2809/NameServiceServerRoot#mycompany/accounting
Where NameServiceServerRoot is a tWAS thing that gets you to the server root context as mentioned above. From there, they use the "proprietary default or custom" JNDI name.
Deployment and Runtime Behavior
Q: Why do EJBs sometimes start in Liberty but fail in Traditional WAS (or the opposite)?
A:
This usually indicates a deployment or routing issue, not an EJB logic problem.
Common scenarios:
- Servlets are installed, but EJB modules are not
- Requests are routed to servers where EJBs are not installed
- Applications silently ignore NameNotFoundException
- Different servers use different ORB or EJB configurations
Understanding where the EJB application is installed and started is critical.
Migration Strategy
Q: What should teams do before migrating an EJB application to Liberty?
A:
Always start by running the WebSphere Migration Tool for Liberty.
The tool:
- Identifies unsupported EJB features
- Flags Entity Bean usage
- Detects problematic JNDI lookups
- Scales well for applications with hundreds of beans
This is especially critical for large or long‑lived EJB applications.
Q: What are the most common EJB migration actions required?
A:
- Replace Entity Beans with JPA
- Update remote JNDI lookup strings
- Enable ejbRemote only when truly required
- Remove dependencies on IBM‑specific extensions
- Prefer local EJBs with service endpoints over remote EJB access
Remote EJB Lookup and Bindings:
Q: Why do some EJB lookups or injections that worked in Traditional WAS fail in Liberty?
A:
- Some EJB lookups or injections that worked in Traditional WAS may fail in Liberty because Traditional WAS can perform additional deployment-time EJB binding processing during application installation. Depending on the deployment options, tWAS may generate or modify EJB bindings, and those bindings are stored in the
ibm-*-bnd.xml / ibm-*-bnd.xmi files.
- During migration, if those generated bindings are not carried forward or recreated in Liberty, EJB references that previously resolved in tWAS may fail.
- Liberty supports specification-defined EJB naming as well as features such as
ejblocal. The issue is generally not that Liberty has stricter EJB resolution rules, but that applications may have depended on tWAS-generated deployment bindings or application-specific naming configurations that need to be migrated.
Q: What is the difference between ejblocal and java:global in Liberty?
ejblocal is a legacy naming mechanism from Traditional WAS. Liberty historically did not support all ejblocal lookup scenarios; however, support was added in Liberty 20.0.0.12 and fully supported in Liberty 25.0.0.5 (OLGH31167).
- For example, applications that rely on
ejblocal sub-context lookups such as: ejblocal:MyApp-1.0 should run on Liberty 25.0.0.5 or later.
Q: Can java:global be used across different applications on the same Liberty server?
A:
Yes. When multiple applications (EARs) are deployed to the same WebSphere Liberty server (same JVM), server‑side EJB injection and lookup using java:global is fully supported.
Important distinction:
- ✅ Same server (server‑side code):
java:global works
- ❌ External or standalone clients:
java:global does not work
Remote clients must use:
corbaname::host:port#ejb/global/...
Q: Why does @EJB(beanName=...) work in tWAS but fail in Liberty for cross‑application EJB injection?
A:
- The
beanName attribute (and ejb-link in ejb-jar.xml) can only identify EJBs within the same application. This is an EJB specification rule.
- In traditional WebSphere Application Server (tWAS), cross‑application EJB references may appear to work because EJB bindings can be generated during application installation. For example, if "Allow EJB references to resolve automatically" is enabled, tWAS can create bindings that allow the reference to resolve successfully. If this option is disabled, the application would fail on tWAS as well.
- Liberty does not automatically generate these cross‑application bindings, so the reference cannot be resolved unless an explicit binding is provided.
To make cross‑application EJB references work, provide an explicit binding by either:
- Adding a
lookup or lookup-name to the EJB reference.
- Defining the binding in an
ibm-*-bnd.xml file.
- Defining the binding in
server.xml.
There is no need to remove existing beanName or ejb-link values. They can remain as deployment hints. The important requirement is that a cross‑application EJB reference must have a binding that resolves it to the target EJB.
Tip: If the application currently works on tWAS, exporting the deployed application can help identify the bindings that need to be recreated in Liberty.
Q: How can applications track the authenticated user across remote EJB calls in Liberty?
A:
This behavior is related to differences between the IBM ORB used by traditional WebSphere Application Server (tWAS) and the Apache Yoko ORB used by Liberty.
The IBM ORB supports an optional RMI/IIOP optimization called co-located invocation, where a remote EJB call within the same server can be dispatched on the same thread. The Yoko ORB does not support this behavior and always dispatches remote EJB calls on a separate thread.
As a result, any information stored in a ThreadLocal by the calling application will not be visible to the remote EJB method in Liberty because the EJB executes on a different thread.
Security information is one example of data that applications sometimes store in thread-local variables, but the same issue can affect any application-specific context stored that way.
Liberty automatically propagates the authenticated security subject across local and remote EJB calls. Therefore, applications should retrieve the authenticated user using supported APIs such as:
SecurityContext.getCallerPrincipal() (Servlets/JAX-RS)SessionContext.getCallerPrincipal() (EJBs)WSSubject.getCallerSubject() (Liberty-specific)
✅ Applications should not rely on ThreadLocal state to track users or application context across remote EJB calls. Instead, use the supported security APIs or explicitly pass application context as method parameters when needed.