Skip to end of metadata
Go to start of metadata

The purpose of this chapter is to demonstrate how to lookup and invoke on EJBs deployed on an AS7 server instance from another AS7 server instance. This is different from invoking the EJBs from a remote standalone client

Let's call the server, from which the invocation happens to the EJB, as "Client Server" and the server on which the bean is deployed as the "Destination Server".

Note that this chapter deals with the case where the bean is deployed on the "Destination Server" but not on the "Client Server".

Application packaging

In this example, we'll consider a EJB which is packaged in a myejb.jar which is within a myapp.ear. Here's how it would look like:

Note that packaging itself isn't really important in the context of this article. You can deploy the EJBs in any standard way (.ear, .war or .jar).


In our example, we'll consider a simple stateless session bean which is as follows:


JBoss AS 7.1 is secure by default. What this means is that no communication can happen with an AS7 instance from a remote client (irrespective of whether it is a standalone client or another server instance) without passing the appropriate credentials. Remember that in this example, our "client server" will be communicating with the "destination server". So in order to allow this communication to happen successfully, we'll have to configure user credentials which we will be using during this communication. So let's start with the necessary configurations for this.

Configuring a user on the "Destination Server"

As a first step we'll configure a user on the destination server who will be allowed to access the destination server. We create the user using the add-user script that's available in the JBOSS_HOME/bin folder. In this example, we'll be configuring a Application User named ejb and with a password test in the ApplicationRealm. Running the add-user script is an interactive process and you will see questions/output as follows:


As you can see in the output above we have now configured a user on the destination server who'll be allowed to access this server. We'll use this user credentials later on in the client server for communicating with this server. The important bits to remember are the user we have created in this example is ejb and the password  is test.

Note that you can use any username and password combination you want to.
You do not require the server to be started to add a user using the add-user script.

Start the "Destination Server"

As a next step towards running this example, we'll start the "Destination Server". In this example, we'll use the standalone server and use the standalone-full.xml configuration. The startup command will look like:

Ensure that the server has started without any errors.

It's very important to note that if you are starting both the server instances on the same machine, then each of those server instances must have a unique system property. You can do that by passing an appropriate value for system property to the startup script:

Deploying the application

The application (myapp.ear in our case) will be deployed to "Destination Server". The process of deploying the application is out of scope of this chapter. You can either use the Command Line Interface or the Admin console or any IDE or manually copy it to JBOSS_HOME/standalone/deployments folder (for standalone server). Just ensure that the application has been deployed successfully.

So far, we have built a EJB application and deployed it on the "Destination Server". Now let's move to the "Client Server" which acts as the client for the deployed EJBs on the "Destination Server".

Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server"

As a first step on the "Client Server", we need to let the server know about the "Destination Server"'s EJB remoting connector, over which it can communicate during the EJB invocations. To do that, we'll have to add a "remote-outbound-connection" to the remoting subsystem on the "Client Server". The "remote-outbound-connection" configuration indicates that a outbound connection will be created to a remote server instance from that server. The "remote-outbound-connection" will be backed by a "outbound-socket-binding" which will point to a remote host and a remote port (of the "Destination Server"). So let's see how we create these configurations.

Start the "Client Server"

In this example, we'll start the "Client Server" on the same machine as the "Destination Server". We have copied the entire server installation to a different folder and while starting the "Client Server" we'll use a port-offset (of 100 in this example) to avoid port conflicts:

Create a security realm on the client server

Remember that we need to communicate with a secure destination server. In order to do that the client server has to pass the user credentials to the destination server. Earlier we created a user on the destination server who'll be allowed to communicate with that server. Now on the "client server" we'll create a security-realm which will be used to pass the user information.

In this example we'll use a security realm which stores a Base64 encoded password and then passes on that credentials when asked for. Earlier we created a user named ejb and password test. So our first task here would be to create the base64 encoded version of the password test. You can use any utility which generates you a base64 version for a string. I used this online site which generates the base64 encoded string. So for the test password, the base64 encoded version is dGVzdA==

While generating the base64 encoded string make sure that you don't have any trailing or leading spaces for the original password. That can lead to incorrect encoded versions being generated.
With new versions the add-user script will show the base64 password if you type 'y' if you've been ask

Now that we have generated that base64 encoded password, let's use in the in the security realm that we are going to configure on the "client server". I'll first shutdown the client server and edit the standlaone-full.xml file to add the following in the <management> section

Now let's create a "security-realm" for the base64 encoded password.

Notice that the CLI show the message "process-state" => "reload-required", so you have to restart the server before you can use this change.

upon successful invocation of this command, the following configuration will be created in the management section:


As you can see I have created a security realm named "ejb-security-realm" (you can name it anything) with the base64 encoded password. So that completes the security realm configuration for the client server. Now let's move on to the next step.

Create a outbound-socket-binding on the "Client Server"

Let's first create a outbound-socket-binding which points the "Destination Server"'s host and port. We'll use the CLI to create this configuration:

The above command will create a outbound-socket-binding named "remote-ejb" (we can name it anything) which points to "localhost" as the host and port 4447 as the destination port. Note that the host information should match the host/IP of the "Destination Server" (in this example we are running on the same machine so we use "localhost") and  the port information should match the remoting connector port used by the EJB subsystem (by default it's 4447). When this command is run successfully, we'll see that the standalone-full.xml (the file which we used to start the server) was updated with the following outbound-socket-binding in the socket-binding-group:

Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding"

Now let's create a "remote-outbound-connection" which will use the newly created outbound-socket-binding (pointing to the EJB remoting connector of the "Destination Server"). We'll continue to use the CLI to create this configuration:

The above command creates a remote-outbound-connection, named "remote-ejb-connection" (we can name it anything), in the remoting subsystem and uses the previously created "remote-ejb" outbound-socket-binding (notice the outbound-socket-binding-ref in that command). Furthermore, we also set the security-realm attribute to point to the security-realm that we created in the previous step. Also notice that we have set the username attribute to use the user name who is allowed to communicate with the destination server.

What this step does is, it creates a outbound connection, on the client server, to the remote destination server and sets up the username to the user who allowed to communicate with that destination server and also sets up the security-realm to a pre-configured security-realm capable of passing along the user credentials (in this case the password). This way when a connection has to be established from the client server to the destination server, the connection creation logic will have the necessary security credentials to pass along and setup a successful secured connection.

Now let's run the following two operations to set some default connection creation options for the outbound connection:

Ultimately, upon successful invocation of this command, the following configuration will be created in the remoting subsystem:

From a server configuration point of view, that's all we need on the "Client Server". Our next step is to deploy an application on the "Client Server" which will invoke on the bean deployed on the "Destination Server".

Packaging the client application on the "Client Server"

Like on the "Destination Server", we'll use .ear packaging for the client application too. But like previously mentioned, that's not mandatory. You can even use a .war or .jar deployments. Here's how our client application packaging will look like:

In the client application we'll use a servlet which invokes on the bean deployed on the "Destination Server". We can even invoke the bean on the "Destination Server" from a EJB on the "Client Server". The code remains the same (JNDI lookup, followed by invocation on the proxy). The important part to notice in this client application is the file jboss-ejb-client.xml which is packaged in the META-INF folder of a top level deployment (in this case our client-app.ear). This jboss-ejb-client.xml contains the EJB client configurations which will be used during the EJB invocations for finding the appropriate destinations (also known as, EJB receivers). The contents of the jboss-ejb-client.xml are explained next.

If your application is deployed as a top level .war deployment, then the jboss-ejb-client.xml is expected to be placed in .war/WEB-INF/ folder (i.e. the same location where you place any web.xml file).

Contents on jboss-ejb-client.xml

The jboss-ejb-client.xml will look like:

You'll notice that we have configured the EJB client context (for this application) to use a remoting-ejb-receiver which points to our earlier created "remote-outbound-connection" named "remote-ejb-connection". This links the EJB client context to use the "remote-ejb-connection" which ultimately points to the EJB remoting connector on the "Destination Server".

Deploy the client application

Let's deploy the client application on the "Client Server". The process of deploying the application is out of scope, of this chapter. You can use either the CLI or the admin console or a IDE or deploy manually to JBOSS_HOME/standalone/deployments folder. Just ensure that the application is deployed successfully.

Client code invoking the bean

We mentioned that we'll be using a servlet to invoke on the bean, but the code to invoke the bean isn't servlet specific and can be used in other components (like EJB) too. So let's see how it looks like:

That's it! The above code will invoke on the bean deployed on the "Destination Server" and return the result.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 13, 2012

    Hi Jaikiran,

    I have tried the steps mentioned above, but, still I am not able to connect to my remote EJB. My EJB (server) is packed in a EAR, and the client is packaged as a WAR. I have placed the "jboss-ejb-client.xml" in the classes folder under WEB-INF directory.

    Have performed all the changes on the client side as well as server side, but when i try to invoke any method on my EJB, i get the following error:

    java.lang.IllegalStateException: No EJB receiver available for handling [appName:MyEar,modulename:MyBeans,distinctname:] combination for invocation context.

    The JNDI name of the EJB is correct, since if i try to invoke a local instance, then the EJB lookup succeeds and the method invocation is successful. I am using JBoss AS 7.1.1.Final

    Could you please help me on this, as I am unaware of how to resolve this.



    1. Jun 18, 2012

      I think you may try to place your "jboss-ejb-client.xml" under WEB-INF/classes directory of your client war.

  2. Jun 20, 2012

    I followed the example, but am getting this Warning on deployment:

    16:55:21,748 INFO  [org.jboss.ejb.client.remoting.RemotingConnectionEJBReceiver] (MSC service thread 1-3) Successful version handshake completed for receiver context EJBReceiverContext

    Unknown macro: {clientContext=org.jboss.ejb.client.EJBClientContext@1976d490, receiver=Remoting connection EJB receiver [connection=Remoting connection <1acedc74>,channel=jboss.ejb,nodename=dest]}

    on channel Channel ID a9f6f5d2 (outbound) of Remoting connection 4aeee916 to localhost.localdomain/
    16:55:21,749 WARN  [org.jboss.ejb.client.remoting.ChannelAssociation] (Remoting "client" task-4) Unsupported message received with header 0xffffffff
    16:55:21,785 INFO  [org.jboss.web] (MSC service thread 1-1) JBAS018210: Registering web context: /client-app-war
    16:55:21,789 INFO  [] (DeploymentScanner-threads - 1) JBAS018565: Replaced deployment "client-app.ear" with deployment "client-app.ear"

    Then this error when trying to invoke?

    16:55:27,254 ERROR [org.apache.catalina.core.ContainerBase.[jboss.web].[default-host].[/client-app-war].[TestRemoteEjb]] (http-localhost.localdomain- Servlet.service() for servlet TestRemoteEjb threw exception: java.lang.ClassNotFoundException: org.myapp.ejb.Greeter from [Module "deployment.client-app.ear.client-app-war.war:main" from Service Module Loader]

    any thoughts as to what may be wrong?


    1. Jun 21, 2012

      Got around this by bundling the myejb.jar as a library reference.  I was thinking you only had to use it as a reference for building it


  3. Jun 25, 2012

    Is this instruction a joke? Why there is no org.jboss.naming.ExternalContext or equivalent? If I have sufficiently complicated app that calls 50 ejbs over 2 or more app servers, administration overhead is just insane to get it just to work. Just WTF :/

  4. Jun 28, 2012

    This example assumes there is only single EJB receiver being defined. What if I will have to put more than one EJB receiver and be able to programatically look up the targeted EJB receiver ? any pointers to the relevant documentation is very much appreciated. Thanks

  5. Sep 15, 2012

    With a lot of extra effort I could make this guide work.

    Things a did different to get two instances working on the  same machine:

    1. Add the user in the destination server and don't start it yet. Only start it after configuring the client server.
    2. Start the client server without doing port-offset when you intend to configure it. Use sh bin/ -server-config=standalone-full.xml and then in another terminal connect with CLI: sh bin/ --connect . Then do the client configuration above and enter quit to exit CLI. After that, shutdown the client server.
    3. Start the destination server: sh bin/ -server-config=standalone-full.xml
    4. Deploy your EAR with the remote EJBs.
    5. Start the client server: sh bin/ -server-config=standalone-full.xml -Djboss.socket.binding.port-offset=100
    6. Deploy your client application. In case it's a WAR, put jboss-ejb-client.xml inside WAR_ROOT/META-INF. Pay attention, META-INF is in the same level as WEB-INF (WAR_ROOT/WEB-INF) and not inside it.
    7. Do the ejb lookup as explained above. In my case the string was: ejb:myear/myear-ejb//MemberRegistrationBean! . The "//" isn't wrong.
    8. If you did all right, during the client application deploy, jboss prints some INFO messages like:

    16:18:46,784 INFO  [org.jboss.ejb.client.remoting.RemotingConnectionEJBReceiver] (MSC service thread 1-4) Successful version handshake completed for receiver context EJBReceiverContext{clientContext=org.jboss.ejb.client.EJBClientContext@600a08, receiver=Remoting connection EJB receiver [connection=Remoting connection <18f57d2>,channel=jboss.ejb,nodename=nodeone]} on channel Channel ID b3e3f879 (outbound) of Remoting connection 0024e39f to localhost/

    If this doesn't show up, in my experience, you're bad. Redo your client config and verify if  jboss-ejb-client.xml is on the right place.

    Hope it helps. cheers.

  6. Oct 18, 2012

    I am struggling with this

    In the destination server ( i created and deployed a war application thas has a Remote EJB.

    Then in my computer i deploy another war application that has the client.

    When i deploy the client war, i can see the message than Marcio Dantas refers to:

    Successful version handshake completed 

    But i keep getting the:

    java.lang.IllegalStateException: No EJB receiver available for handling [appName:remoteProvider,modulename:,distinctname:] combination for invocation context org.jboss.ejb.client.EJBClientInvocationContext@1b10810
    java.lang.IllegalStateException: No EJB receiver available for handling [appName:remoteProvider,modulename:,distinctname:] combination for invocation context org.jboss.ejb.client.EJBClientInvocationContext@1b10810

    I have already tried placing the jboss-ejb-client.xml in the [WEB-APP-ROOT]/META-INF, [WEB-APP-ROOT]/WEB-INF/classes and even in [WEB-APP-ROOT]/WEB-INF/classes/META-INF and still nothing

    The standalone-full.xml file appears to be ok. I even have added some properties to the props, like this:

    Hashtable props = new Hashtable();

    props.put("jboss.naming.client.ejb.context", true);

    props.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");

    props.put(Context.SECURITY_PRINCIPAL, "ejb");

    props.put(Context.SECURITY_CREDENTIALS, "test");

    Context context = new javax.naming.InitialContext(props);


    1. Oct 18, 2012

      Hi Jose,

      I don't think you can have remote EJBs in a WAR.

      Ejbs in WARs are lite ejbs, which are restricted (you can't use MDBs or remote clients).

      Take a look for the EJB LITE section in the spec:


      1. Oct 19, 2012

        Thanks Marcio

        I deployed my remote ejbs in a ear application, and then the webapp application was able to consume them


      2. Dec 10, 2013

        I don't think that's true. Chapter 20.4 "Enterprise Beans Packaged in a .war" does not state those EJBs might be lite . The only restriction I could find is that WAR-embedded EJBs don't have an JAX-RPC client view.

  7. Nov 07, 2012


    I followed the directions given in this article here but I still get the error 

    The error output is actually several hundred lines starting with

    I can understand from this article how the container can lookup op a host, username and password  from the jboss-ejb-receiver defined in jboss-ejb-client.xml

    What I don't understand is how the container knows on which host the GreetingsBean is on? There is nothing in the JNDI name or the properties that ties it to a particular server. This thread seems to suggest that the container contacts all the servers (indirectly) specified in the jboss-ejb-client.xml file and checks which beans they have available (I just have one remoting-ejb-receiver at the moment but in principle there could be more). And if so, when does it contact the remote servers. Do the remote servers have to be running when the bean is initially loaded? And if so, what could be the cause of the error above. 

    I've verified that there are no errors earlier in the log file and that that telnet <host> 4777 gets through.

    The complete configuration files are here: jboss-ejb-client.xmlstandalone-full.xml.

    The whole logfile is here: server.log

    (I don't want to attach them since I don't want them to be accessible indefinately).

    The remote server apparantly deploys the GreaterBean correctly:

    Here is how I try to look up and invoke the remote bean:

    Any help appreciated.

    1. Nov 08, 2012

      Hi Thor,

      you should have a look into my example project ejb-multi-server. If it dosn't help please create a thread here with the appropriate information and we can continue there. The documetation is not the best place for that IMHO.

      cheers Wolf

      1. Nov 14, 2012

        Hi Wolf-Dieter,

        I tried going through the ejb-multi-server example but ran into a problem early in the process. I described the problem on the forum you suggested (here), but haven't gotten an answer yet.

        I think future readers of this article could benefit from the answer to the central question in my post above: How does the container know on which host(s) to look for a particular bean?



  8. Dec 07, 2012

    hi ,

    these steps will work even when the jboss servers are running on two different machines...?

    in my case the i have the servers on different machine and i get the following exception...

     ERROR [] (EJB default - 3) JBAS014134: EJB Invocation failed on component Hellobean for method public abstract java.lang.String

    elloworld.Hello.createHelloMessage(java.lang.String) throws javax.naming.NamingException: javax.ejb.EJBException: java.lang.reflect.UndeclaredThrowableException

            at [jboss-as-ejb3-7.1.2.Final.jar:7.1.2.Final]

    5:12:18,007 ERROR [] (EJB default - 3) JBAS014134: EJB Invocation failed on component Hellobean for method public abstract java.lang.String
    elloworld.Hello.createHelloMessage(java.lang.String) throws javax.naming.NamingException: javax.ejb.EJBException: java.lang.reflect.UndeclaredThrowableException
            at [jboss-as-ejb3-7.1.2.Final.jar:7.1.2.Final]

    please help , 


    Rohan Emmanuel

  9. Dec 26, 2012

    'This example assumes there is only single EJB receiver being defined. What if I will have to put more than one EJB receiver and be able to programatically look up the targeted EJB receiver ? any pointers to the relevant documentation is very much appreciated. Thanks'

    I'm having the same question, my web app supposed to use 3 different EJB ear modules deployed on 3 different hosts. Is it possible? How to config?

  10. Jan 28, 2013

    I'm looking at creating a distributed application with different services on different nodes (or clusters). I'm trying to decide between using the Local / Remote EJB mechanisms or defining a REST API for each service. It's all JEE / JBoss, so I thought the EJB route might be easier given JDNI, etc., but after reading this article, my impression is that HTTP-based REST APIs using JSON might actually be an easier to manage. Thanks for any help pointing me in the right direction.

    1. Jan 30, 2013


      that depends on your requirements (transaction, load-balancing etc.) if you need those you have to use EJB otherwise you may decide.

      BTW you might ask that in the forms, i.e. this will be the right place, within the doc you have not a lot of people to answer your question.

  11. Feb 27, 2013

    I got a follow-up question

    At the begining of the article says that it "deals with the case where the bean is deployed on the Destination Server but not on the Client Server".
    How to deal when the bean is deployed in both, client and destination server?

    I have tried it and it calls the bean on the client server instead of the destination server.

    Any help would be appreciated.

  12. Apr 23, 2013

    Seems many are are confused about how the application server decides on which server to invoke a bean. This isn't explicitly stated in the article or anywhere else in the documentation I have read, but as far as I can see the only possibliltity is that it looks for the bean on all known servers, possibly including the local one. It would be nice to have this explicitly confirmed or corrected.

    1. Apr 23, 2013

      Thor, I was looking for the same info and asked Jaikirian explicitly to outline what's going on there. Here is the thread that has some info related to the jboss internal logic:

      1. Apr 24, 2013

        Thanks. That thread explains a lot.

  13. Oct 25, 2013

    I used the above article and was successful to do ejb call when both the client server and destination server were on the same machine.But when client and destination servers are on different machines it is unable to do lookup and gives me error "No ejb receiver found ".To check i used a standalone client to do ejb lookup and i was successful.Please help

    1. Oct 25, 2013

      it should work (i.e. i'm able to use it in production), so double check your config... try to bring client and server in different order. if it doesn't help enable verbose logging and see what's going on.

      1. Oct 25, 2013


        what do u mean by bring client and server in different order.Do u mean changing the machines where server and client are?

        II noticed that when i tried to shut down the client server then in the log of destination server it wrote  remote connection aborted .Let me recheck my config and see

      2. Oct 27, 2013


        As said by you i followed the the instructions again  but was not successful.

        I have attached the server log server.log



        1. Oct 27, 2013

          I can see at least one problem (with the authentication)  in your log file, but there can be more. Can you share some info about your application architecture and deployment?

          1. Oct 28, 2013


            The application is a spring based application.the following is the structure          

            |--- META-INF
            |        |
            |        |--- jboss-ejb-client.xml
            |--- nxtgn.war
            |        |
            |        |--- WEB-INF/classes
            |        |        |
            |        |        |---- nxtgen clases// classes in the web app
            |--------WorkFLowClient.jar(has the api to call the ejb )                                                                             

            1. Oct 28, 2013

              You should have a user=tk2 password=123456 as application user at the destination.

              You might have a look to the ejb-multi-server quickstart for that.

              If you still have problems you should start a thread here =>

          2. Oct 31, 2013


            servererrorlog.txt        This is the new server log when i go for client look up.

  14. Nov 03, 2013

    Hi Abhishek, please create a community thread.

  15. Nov 13, 2013

    First thing this document is not helpful , In my case Jboss 7.2 , EAP 6.1 wasn´t work always got "No EJB Receiver available for handling", I spend two days trying this things to work.. first thing .. forget all about configure the Jboss Client Server by CLI way leave it as is

    The only successful way to proceed is:

    setup ejb properties:




    remote.connection.default.password=JGVqYjEyMzQ=  # the password must be in base64 encoded


    org.jboss.ejb.client.scoped.context=true  # don´t forget if not , you will get famous error

    Also in the jboss:deployment-structure  need add xnio

    <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">



                <module name="org.apache.log4j" />



       <module name="org.jboss.xnio" />




    Do not add  jboss-client.jar in WEB_INF/lib  

    the lookup must be in the ejb: way


    I will continue try to see if this will work in two machines , currently now I have both servers in my notebook

    1. Nov 14, 2013

      Hello Andres,

      as you are using AS7.2/EAP6.1 you should use the correct document for that, try the AS7.2 doc.
      The solution here works fine if the configuration is correct, that should be the same in AS7.2 or EAP6.1.

      You might have a look to the ejb-multi-server quickstart which show the configuration and use.

      What you do with your approach is to use the scoped-context which is implemented in AS7.2 first. Also the password should not be added as base64 this is definitive wrong.
      If you have further questions you should open a thread in the community forum.

  16. Sep 28, 2014


    I have the same question as asked above: i have a requirement to connect the EJB Client to different EJB receiver dynamically. i have gone thru the above steps it worked for one connection but still not getting a way to connect dynamically to different EJB receiver. I tried like below jboss-ejb-client.xml and some where it works but still the number of outbound-connetion-ref will be constant where i need it dynamic means today i might have 2 EJB receiver but tomorrow might be 20 in that case i do not want to change my jar and give it back. Would be great if anyone has solution to it. 

    <jboss-ejb-client xmlns="urn:jboss:ejb-client:1.0">
                <remoting-ejb-receiver outbound-connection-ref="remote-ejb-connection"/>
                <remoting-ejb-receiver outbound-connection-ref="remote-ejb-connection-1"/>

    I have seen one link ejb-multi-server but it is not working for me. Can anyone help me as i am new to it.


  17. Nov 06, 2014


    I am facing similar issue with entity beans in my enterprise project. (Session beans work fine.) I have tried everything suggested here but nothing seems to work. The context lookup successfully returns a proxy object, but exception is obtained as soon as any method on the EJB is called.

    This is the error i am getting:

    java.lang.IllegalArgumentException: JBAS014156: Could not find EJB *****Bean in deployment [app: *EAR module: **EJB distinct-name: ]

    any idea if there has to be an additional step for entity beans to work?

    1. Nov 06, 2014

      For such questions you should use this forum.

      Also you might upgrade to the latest version of WildFly