WebSphere Application Server & Liberty

Join this online group to communicate across IBM product users and experts by sharing advice and best practices with peers and staying up to date regarding product enhancements.

View Only

Back to Blog List

EJB Lookup Use Cases for WebSphere Liberty Migration

By RANJIT KODALI posted 2 days ago

I. Overview and Considerations:

When developing new EJB application projects that involve Liberty and Traditional WebSphere or migrating EJB client applications from Traditional WebSphere to Liberty, one of the key challenges involve JNDI lookups being done on remote EJBs.

There are a few different combinations that one can use to lookup EJBs depending on whether the client is running on Liberty doing a remote EJB lookup to WebSphere or vice versa.

Also we would have to take into consideration with J2EE Client and Java Thin Client applications that can also achieve the remote EJB lookup to Liberty.

The different scenarios explained below show or explain how EJBs can be looked up between Traditional WebSphere and Liberty where each takes the role of a client making an EJB call or a server which has the EJBs deployed which can be invoked either locally or remotely . The document shows examples using remote EJB object.

Liberty Client to Traditional WebSphere Server
Traditional WebSphere Client to Liberty Server
Java Thin Client to Liberty Server
Liberty Client to Liberty Server
J2EE Client using LaunchClient doing remote EJB lookup on Liberty Server
Liberty Client (Client Container) doing remote EJB lookup on Liberty Server

The technote lists and explains common use case scenarios how the remote EJBs can be looked up between Traditional WebSphere and Liberty and vice versa with code samples for reference and details about relevant configuration files that need to be edited between both sides in order to make the EJB lookup successful.

At the end is a section that covers commonly seen errors and recommendations to resolve the errors.

References to relevant articles that could help additionally are included.

SDK Levels Supported between Traditional WebSphere vs Liberty:

Traditional WebSphere: Java 8 (IBM SDK)

Liberty: Supports Java 8 and above. Java SE support

EJB Specifications Supported between Traditional WebSphere vs Liberty:

Traditional WebSphere:

Version 8.5.5.x Supports 8.5.5 - supports EJB 3.1 specification, backwards compatible to EJB 1.1 - full specification.

Version 9.0.5.x supports EJB 3.2 specification, backwards compatible to EJB 1.1 - full specification

Open Liberty:

EJB-3.2 - supports EJB 3.2 specification, backwards compatible to EJB 1.1 - excludes optional features (no Entity, no EmeddableContainer, etc.)
EnterpriseBeans-4.0 - supports Jakarta Enterprise Beans 4.0 specification, backwards compatible to EJB 1.1 APIs (jakarta package version)- excludes optional features (no Entity, no EmeddableContainer, etc.)
For example, you can use an ejb-jar.xml at version 1.1, but the code must use the Jakarta package version of the APIs

WebSphere Liberty:

EjbLite-3.1 - supports the EJB 3.1 specification, backwards compatible to EJB 1.1 - only the EJB Lite API group

Additional Details to the Liberty Supported Specifications for EJBs can be referred through the following Article:

EJB support in Websphere Traditional vs Liberty

WebSphere WsnInitialContextFactory:

The "com.ibm.websphere.naming.WsnInitialContextFactory" class is the WebSphere's implementation and extension of the Oracle's CNCtxFactory. The WsnInitialContextFactory has additional features explained below that make developing a WebSphere client code simpler:

Support for short name lookups like "ejb/myEjb" instead of the fully-qualified name "cell/nodes/myNode/servers/myServer/ejb/myEJB".
Ability to lookup non-CORBA objects in WebSphere AppServer's name space. This includes resources like JMS Queues and Connection Factories, JDBC resources, Strings, etc.
Automatic use of the IBM ORB and its plug-ins that provide additional functionality.

With Liberty, when the EJB client application is being developed or migrated from the existing Traditional WebSphere environment, the use of "com.ibm.websphere.naming.WsnInitialContextFactory" class will NOT work.

This is because, the Liberty architecture is different from traditional WebSphere. The ORB that is used in Liberty is "YOKO" instead of the IBM WebSphere ORB implementation through "ibmorb.jar".

It does not use a specific Initial Context Factory class implementation, while defining the Initial Context Object. For example, in traditional WebSphere, we can use the WsnInitialContextFactory class mentioned above, however with Liberty, the InitialContext Object can be created without mentioning a specific ContextFactory class.
Example:
Object o = new InitialContext()

Example Lookup with traditional WebSphere:

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"com.ibm.websphere.naming.WsnInitialContextFactory");
env.put(Context.PROVIDER_URL,"corbaloc:iiop:rkodali.ibm.com:2809");
Context ct = new InitialContext(env);
Object o = ct.lookup("ejb/MyEJB");

Key takeaway points:
- Use of the IBM WebSphere ContextFactory class.
- Lookup string using shortname

Support for short name lookups as explained above are not supported in Liberty. Instead a fully qualified name of the EJB object is to be done based on the Naming Service Specification (Section 2.4) defined by the OMG (Object Management Group). Supported Lookup string syntax structures will be provided in the examples illustrated below in this technote.
Explanation on how the lookup strings are built is also included in the use case examples for reference. In short, it is more strict and standards compliant when compared to traditional WebSphere.

II. Use Cases:

Note:

Sample source code snippets provided below are not comprehensive, being mindful of the size of the blog. It is assumed that the code implementer has the required Java knowledge to be able to build Java enterprise projects or a Java standalone code based on the details and the relevant artifacts that are provided or explained in the samples shown below.
Each use-case has "Client side considerations" and "Server side considerations" segments, which detail the essential requirements that are to be fulfilled for the specific use-case being considered.

Liberty Client doing Remote EJB lookup on EJB deployed in Traditional WebSphere Application Server

In this example, a simple Web Application deployed in Liberty Server will complete a remote EJB lookup on the EJB deployed in WebSphere.

Client side considerations:

The generic InitialContext() is made with no reference to a specific ContextFactory class.
The lookup name is a fully qualified string object which can be built from the namespace binding output for the EJB Home object that is output from the WebSphere namespace.
- The client code lookup segment shows two lookup name string formats which are built based on the dumpNameSpace output that is seen on the WebSphere server side.
- Check the server side considerations section for more details.
Liberty Client would require the remote EJB client Stubs (JAR) for the remote EJB running in WebSphere. There are two tools that are available in WebSphere which can be used to create the EJB stubs.
- The ejbdeploy command
- Create stubs command
The EJB Client JAR (that is created using the tools mentioned above) should be included within the Liberty classpath and defined in the server.xml file.

Sample Code Snippet (Liberty Client):

====================================================
try {
//The two lookup String object syntax formats listed below are valid. Either one of them may be used for EJB invocations.
//Object o = new InitialContext().lookup("corbaname::iiop:rkodali.ibm.com:2810#cell/nodes/windows20161Node02/servers/server1/ejb/ejbs/WLMTestHome");
Object o = new InitialContext().lookup("corbaname:iiop:rkodali.ibm.com:2810#cell/applications/WLMTest/WLMEJB/WLMTest!ejbs\\.WLMTestHome");
WLMTestHome home = (WLMTestHome) PortableRemoteObject.narrow(o, WLMTestHome.class);
WLMTest bean = home.create();
...
}catch (Exception e){
// catch block code
}

====================================================

Server side considerations:

The dumpNameSpace tool can be run on the WebSphere server side that has the EJB resource binding information.
- Refer to the dumpNameSpace tool documentation on how to run the tool.
- Shown below is the snapshot of the EJB resource that appears with the tool execution on the WebSphere server side.
The lookup string that is built on the client code, should match the output from the dumpNameSpace tool execution.
The EJB resource is bound to the WebSphere namespace in couple of different ways. This is shown in the dumpNameSpace snippet shown below.

Dumpnamespace output snippet taken from WebSphere side:

=================================

73 (top)/nodes/windows20161Node02/servers/server1/ejb/ejbs/WLMTestHome

73 ejbs.WLMTestHome

...

178 (top)/applications/WLMTest/WLMEJB/WLMTest!ejbs.WLMTestHome

178 ejbs.WLMTestHome

=================================

WebSphere Client doing Remote EJB lookup on EJB deployed in Liberty Server:

In this example, a simple Web Application (servlet) deployed in Traditional WebSphere Application Server will complete a remote EJB lookup (EJB deployed in Liberty Server) on a remote host machine.

Client side considerations:

The generic InitialContext() is made with no reference to a specific ContextFactory class.
The lookup syntax is a fully qualified string which can be built using the namespace binding output for the EJB Home object taken from the Liberty JVM's logging. The corbaname syntax that is built confirms to the NamingServiceSpecification rules explained above, earlier in the document.
The messages.log will provide the details of the application binding information within the Liberty's cosNaming namespace during startup. No additional tracing is needed to generate this information.
Define the remote interface class file for the remote EJB that is being looked up, within the client project. This class file needs to be included in the classpath of the client project.
- Defining the remote interface class files for the EJB on the client project, will expose the business methods defined in the remote EJB object for the client.
- Classloader errors such as java.lang.NoClassDefFoundError would be thrown at runtime if the interface class is not defined.

Sample Code Snippet (WebSphere Client):

====================================================

try {

InitialContext ctx = new InitialContext();

Object objref = ctx.lookup("corbaname::iiop:rkodali.ibm.com:2820#ejb/global/TestEJB3_1Project/MyBean!test\\.MyBeanRemote");
MyBeanRemote libertyRemote = (MyBeanRemote) PortableRemoteObject.narrow(objref,MyBeanRemote.class);

...

}catch (Exception e){

// catch block code

}

====================================================

MyBeabRemote.java(Interface java class file)

==================================

package test:

public interface MyBeanRemote {

String sayHello(String name);

}
==================================

Server side considerations:

Liberty server.xml entries show the required features for the EJB and naming.
Liberty server.xml entries that define the iiop/iiops endpoint values and the EJB application definitions.
Liberty logging (messages.log) entries show how the EJB remote object is being bound within the Liberty namespace during the Liberty server startup.There are few other binding entries that are seen for the EJB objects, however the one that is used for the remote client lookup is highlighted below.
If the client lookup is being done using the EJB local object, there will be a corresponding CNTR0167I message for the relevant local EJB object in the messages.log file.

Liberty Logging Entries:

============================================================================

[4/16/26, 20:59:35:094 PDT] 00000033 com.ibm.ws.ejbcontainer.runtime.AbstractEJBRuntime I CNTR0167I: The server is binding the test.MyBeanRemote interface of the MyBean enterprise bean in the TestEJB3_1Project.jar module of the testEJB3_1 application.

The binding location is: java:global/TestEJB3_1Project/MyBean!test.MyBeanRemote

============================================================================

Liberty server.xml entries:

============================================================================

<?xml version="1.0" encoding="UTF-8"?>

<feature>ejbLite-3.2</feature>

<feature>ejbHome-3.2</feature>

<feature>ejbRemote-3.2</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint"

httpPort="9080"

httpsPort="9443" />

</server>

============================================================================

Java Thin Client doing Remote EJB lookup on EJB deployed in Liberty Server:

Liberty Thin Client Runtimes

In this example a traditional Java thin client application can be implemented to make a successful remote EJB lookup of an EJB deployed in Liberty Server.

Liberty Thin Client runtimes will allow you to copy a small number of jars to your client system which will allow you to lookup EJBs and other resources using JNDI.

The IBM Knowledge Center Documentation provides detailed explanation about each runtime jar that is required and what it can be used for:

Running the IBM Thin Client for Enterprise JavaBeans (EJB)

The restriction with a thin client setup, is that it needs to be implemented via the inclusion of the Traditional WebSphere Application Server thin client JARs, which in turn would limit the JDK that it can run on, to be at the highest level no greater than JDK 8, that which is supported by Traditional WebSphere.

NOTE: Thin client (Client side) support for higher JDKs (> Java 8) is not supported and has not been tested.

Client side considerations:

For the thin client to be able to do a successful lookup of the remote EJBs, it would require the remote EJB stub classes to be made available in its classpath.
- The remote EJB stubs can be generated using the Create stubs command tool available in the app_server_root/bin of the Traditional WebSphere Application Server install as createEJBStubs.bat(.sh) file.
Ensure that the EJBs that are being developed, are compiled using Java 8 compiler. You can come across classloader errors while trying to create the EJB stubs using the createEJBStubs tool, if the EJBs are compiled and built using JDK level higher than Java 8. The tool to create the stubs would fail with a classloader UnsupportedVersionException.
The document Running the IBM Thin Client for Enterprise JavaBeans (EJB) provides information on what dependencies are needed for the thin client to be setup in a supported manner.
A separate copy of the IBM ORB (ibmorb.jar) to be used with the Thin Client if you are not using the IBM JDK installed with WebSphere/Application Client, which by default includes the ORB.
Define the remote interface class file for the EJB that is being looked up on the client project. This class file would need to be available in the classpath of the client project. The interface class will expose the business methods defined in the remote EJB object. Classloader errors such as java.lang.NoClassDefFoundError would be thrown at runtime if the interface class is not defined.

Sample Code Snippet (Java client):

====================================================

try {

InitialContext ctx = new InitialContext();

Object objref = ctx.lookup("corbaname::rkodali.ibm.com:2820#ejb/global/InteropV9EJB/InteropV9EJB!ejb\\.InteropV9EJBRemote");
InteropV9EJBRemote libertyRemote = (InteropV9EJBRemote) PortableRemoteObject.narrow(objref,InteropV9EJBRemote.class);

...

}catch (Exception e){

// catch block code

}

====================================================

InteropV9EJBRemote.java (Interface java class file)

=============================================

package ejb;

public interface InteropV9EJBRemote {

public String getString();

public String getStringArray();

}

============================================

Server side considerations:

Liberty server.xml entries show the required features for the EJB and naming.
Liberty server.xml entries that define the iiop/iiops endpoint values and the EJB application definitions.
Liberty logging (messages.log) entries show how the EJB remote object is being bound within the Liberty namespace during the Liberty server startup.There are few other binding entries that are seen for the EJB objects, however the one that is used for the remote client lookup is highlighted below.
If the client lookup is being done using the EJB local object, there will be a corresponding CNTR0167I message for the relevant local EJB object in the messages.log file.

Liberty server.xml entries:

============================================================================

<?xml version="1.0" encoding="UTF-8"?>

<feature>ejbLite-3.2</feature>

<feature>ejbHome-3.2</feature>

<feature>ejbRemote-3.2</feature>

<feature>servlet-3.1</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint"

httpPort="9080"

httpsPort="9443" />

</server>

============================================================================

Liberty Logging Entries:

============================================================================

[4/28/26, 17:47:36:711 PDT] 00000030 com.ibm.ws.ejbcontainer.runtime.AbstractEJBRuntime I CNTR0167I: The server is binding the ejb.InteropV9EJBRemote interface of the InteropV9EJB enterprise bean in the InteropV9EJB.jar module of the interop_ejb application.

The binding location is: java:global/InteropV9EJB/InteropV9EJB!ejb.InteropV9EJBRemote

============================================================================

Liberty Client doing remote EJB lookup on Liberty Server:

In this example, a simple web application makes a remote EJB invocation to a Liberty server residing on a different host machine.

The example demonstrates the various artifacts that are needed between the the liberty client and liberty server side setups.

Client side considerations:

The generic InitialContext() is made with no reference to a specific ContextFactory class.
The lookup string is a fully qualified string which can be built using the namespace binding output for the EJB Home object taken from the server side Liberty JVM's logging. The String syntax that is built confirms to the NamingServiceSpecification rules explained earlier in the document.
Define the remote interface class file for the remote EJB that is being looked up, within the client project. This class file needs to be included in the classpath of the client side project artifacts.
- Defining the remote interface class files for the EJB on the client project, will expose the business methods defined in the remote EJB object for the client.
- Classloader errors such as the java.lang.NoClassDefFoundError would be thrown at runtime if the interface class is not defined.

Sample Code Snippet (Liberty client):
====================================================
try {
InitialContext ctx = new InitialContext();
Object objref = ctx.lookup("corbaname::rkodali.ibm.com:2820#ejb/global/TestEJB3_1Project/MyBean!test\\.MyBeanRemote");
MyBeanRemote myBean= (MyBeanRemote) PortableRemoteObject.narrow(objref,MyBeanRemote.class);
// EJB business method invocations
...
...
}catch (Exception e){

// catch block code
}

}
====================================================

MyBeanRemote.java (Interface java class file)

======================================

package test;

public interface MyBeanRemote {

String sayHello(String name);

}

======================================

Liberty server.xml entries (Client side):

==================================

<feature>ejbLite-3.2</feature>

<feature>ejbHome-3.2</feature>

<feature>ejbRemote-3.2</feature>

<feature>servlet-3.1</feature>

<feature>localConnector-1.0</feature>

</featureManager>

</server>

==================================

Server side considerations:

Liberty server.xml entries show the required features for the EJB and naming.
Liberty server.xml entries that define the iiop/iiops endpoint values and the EJB application definitions.
Liberty logging (messages.log) entries show how the EJB remote object is being bound within the Liberty's cosNaming namespace during the Liberty server startup.No additional tracing is needed to generate this information.
There are few other binding entries that are seen for the EJB objects, however the one that is used for the remote client lookup is highlighted below.
If the client lookup is being done using the EJB local object, there will be a corresponding CNTR0167I message for the relevant local EJB object in the messages.log file.

Liberty Logging Entries (Server side)

============================================================================

The binding location is: java:global/TestEJB3_1Project/MyBean!test.MyBeanRemote

============================================================================

Liberty server.xml entries (Server side):

==========================================================

<?xml version="1.0" encoding="UTF-8"?>

<feature>ejbLite-3.2</feature>

<feature>ejbHome-3.2</feature>

<feature>ejbRemote-3.2</feature>

<feature>servlet-3.1</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint"

httpPort="9080"

httpsPort="9443" />

</server>

===============================================================

J2EE Client using LaunchClient doing remote EJB lookup on Liberty Server:

In this example we use the LaunchClient tool from the WebSphere Application Client that is installed on the client machine. The launchClient tool can also be used from the traditional WebSphere Application Server instance if available on the client machine.

The client application is a simple Java application that is packaged inside an EAR, which will allow the launchClient tool to be able to run it from within the client container.

Useful articles that explain the LauchClient tool and its usage:

Client side considerations:

Unlike in the Java thin client use-case, it is not required to copy the thin client JARs, as the client container is available and will provide all the required dependencies for the client application to run.
It is not required to define the remote interface class file for the EJB that is being looked up on the client project.
For the J2EE Client to be able to do a successful lookup of the remote EJBs, it would require the remote EJB stub classes to be made available in its classpath.

The remote EJB stubs can be generated using the Create stubs command tool available in the WAS_HOME/bin of the Traditional WebSphere Application Server install as createEJBStubs.bat(.sh) file.
The createEJBStubs.bat(sh) tool is not available in the WebSphere Application Client.

Sample Code Snippet (J2EE client):
====================================================
try {

InitialContext ctx = new InitialContext();

...

}catch (Exception e){

// catch block code

}

====================================================

Server side considerations:

Liberty server.xml entries show the required features for the EJB and naming.
Liberty server.xml entries that define the iiop/iiops endpoint values and the EJB application definitions.
Liberty logging (messages.log) entries show how the EJB remote object is being bound within the Liberty namespace during the Liberty server startup.There are few other binding entries that are seen for the EJB objects, however the one that is used for the remote client lookup is highlighted below.
If the client lookup is being done using the EJB local object, there will be a corresponding CNTR0167I message for the relevant local EJB object in the messages.log file.

Liberty server.xml entries:

============================================================================

<?xml version="1.0" encoding="UTF-8"?>

<feature>ejbLite-3.2</feature>

<feature>ejbHome-3.2</feature>

<feature>ejbRemote-3.2</feature>

<feature>servlet-3.1</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint"

httpPort="9080"

httpsPort="9443" />

</server>

============================================================================

Liberty Logging Entries:

============================================================================

The binding location is: java:global/InteropV9EJB/InteropV9EJB!ejb.InteropV9EJBRemote

============================================================================

Liberty Client (Client Container) doing remote EJB lookup on Liberty Server:

<<To be Included soon>>

III. Commonly Seen Errors and Fixes:

Error:

[3/17/26 22:03:54:128 CDT] 00000095 ServletWrappe E com.ibm.ws.webcontainer.servlet.ServletWrapper service Uncaught service() exception thrown by servlet EJBTestServlet: java.lang.NoClassDefFoundError: ejb.InteropV9EJBRemote

at test.EJBTestServlet.doGet(EJBTestServlet.java:81)

at javax.servlet.http.HttpServlet.service(HttpServlet.java:575)

at javax.servlet.http.HttpServlet.service(HttpServlet.java:668)

at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1233)

Explanation:

error indicates the ejb.InteropV9EJBRemote class is not on the classpath of the WAR. It doesn't have to be in the WAR, but does need to be on the classpath.

The build path is irrelevant when running the application; what is important is how you have packaged it; what is actually being installed

Error:

(Liberty Client -> tWAS)

SRVE0315E: An exception occurred: java.lang.Throwable: java.lang.ClassCastException: ejbs.WLMTestHome

at com.ibm.ws.webcontainer.webapp.WebApp.handleRequest(WebApp.java:5154)

at [internal classes]

Caused by: java.lang.ClassCastException: ejbs.WLMTestHome

at com.ibm.ws.transport.iiop.internal.WSPortableRemoteObjectImpl.narrow(WSPortableRemoteObjectImpl.java:52)

at [internal classes]

at com.test.LibertyTestServlet.doGet(LibertyTestServlet.java:56)

at javax.servlet.http.HttpServlet.service(HttpServlet.java:686)

... 1 more

Explanation:

Error:

Liberty: (2820) : java.lang.ClassCastException : Unable to load class: ejb._InteropV9EJBRemote_Stub

Explanation:

When using a "thin" client, you must manually generate and package all required "Stub" classes.

Since this is for an EJB 3.x style remote interface that does not implement java.rmi.Remote, you must use the createEJBStubs command provided by tWAS. Instructions may be found here :

https://www.ibm.com/docs/en/was/8.5.5?topic=de3eb-create-stubs-command

Error:

I have a simple java(Thin Client) application that calls the InteropV9EJBRemote..

I am seeing this error where the "import javax.rmi.PortableRemoteObject" is not being recognized

Explanation:

The thin client only supports Java 8.

However The Liberty AppClient will support all Java levels that Liberty supports.

The tWAS AppClient would only support Java 8