Chapter 5. Invoking Session Beans

This task describes how to add support to a remote client for the invocation of session beans using JNDI. The task assumes that the project is being built using Maven.

The ejb-remote quickstart contains working Maven projects that demonstrate this functionality. The quickstart contains projects for both the session beans to deploy and the remote client. The code samples below are taken from the remote client project.

This task assumes that the session beans do not require authentication.

To invoke a session bean from a remote client you must first configure the project correctly.

You should now be able to configure a Maven project to support invoking session beans on a remote server and write the code invoke the session beans' methods using a proxy bean retrieved from the server using JNDI.

JBoss EAP introduced the EJB client API for managing remote EJB invocations. The JBoss EJB client API uses the EJBClientContext, which may be associated with and be used by one or more threads concurrently. The means an EJBClientContext can potentially contain any number of EJB receivers. An EJB receiver is a component that knows how to communicate with a server that is capable of handling the EJB invocation. Typically, EJB remote applications can be classified into the following:

Depending on the type of remote client, from an EJB client API point of view, there can potentially be more than one EJBClientContext within a JVM.

While standalone applications typically have a single EJBClientContext that may be backed by any number of EJB receivers, this isn’t mandatory. If a standalone application has more than one EJBClientContext, an EJB client context selector is responsible for returning the appropriate context.

In case of remote clients that run within another JBoss EAP instance, each deployed application will have a corresponding EJB client context. Whenever that application invokes another EJB, the corresponding EJB client context is used to find the correct EJB receiver, which then handles the invocation.

public class MyApplication {
    public static void main(String args[]) {
        final javax.naming.Context ctxOne = new javax.naming.InitialContext();
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...
    }
}

Remote client JNDI lookups are usually backed by a jboss-ejb-client.properties file, which is used to set up the EJB client context and the EJB receivers. This configuration also includes the security credentials, which are then used to create the EJB receiver that connects to the JBoss EAP server. When the above code is invoked, the EJB client API looks for the EJB client context, which is then used to select the EJB receiver that will receive and process the EJB invocation request. In this case, there is just the single EJB client context, so that context is used by the above code to invoke the bean. The procedure to invoke a session bean remotely using JNDI is described in greater detail here: Invoke a Session Bean Remotely using JNDI.

public class MyApplication {
    public static void main(String args[]) {
        // Use the "foo" security credential connect to the server and invoke this bean instance
        final javax.naming.Context ctxOne = new javax.naming.InitialContext();
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...

        // Use the "bar" security credential to connect to the server and invoke this bean instance
        final javax.naming.Context ctxTwo = new javax.naming.InitialContext();
        final MyBeanInterface beanTwo = ctxTwo.lookup("ejb:app/module/distinct/bean!interface");
        beanTwo.doSomething();
        ...
    }
}

In this case, the application wants to connect to the same server instance to invoke the EJB hosted on that server, but wants to use two different credentials while connecting to the server. Because the client application has a single EJB client context, which can have only one EJB receiver for each server instance, this means the above code uses just one credential to connect to the server and the code does not execute as the application expects it to.

An EJB can be invoked using either of the following methods:

EJB Remoting Call

To invoke EJB session beans with a JBoss EAP standalone client, the client must have a reference to the InitialContext object while the EJB proxies or UserTransaction are used. It is also important to keep the InitialContext object open while EJB proxies or UserTransaction are being used. Control of the connections will be inside the classes created by the InitialContext with the properties.

The following code example shows an EJB client that holds a reference to the InitialContext object. This code example was taken from the ejb-multi-server quickstart that ships with JBoss EAP.

package org.jboss.as.quickstarts.ejb.multi.server;

import java.util.Date;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;

import javax.naming.Context;
import javax.naming.InitialContext;

import org.jboss.as.quickstarts.ejb.multi.server.app.MainApp;
import org.jboss.ejb.client.ContextSelector;
import org.jboss.ejb.client.EJBClientConfiguration;
import org.jboss.ejb.client.EJBClientContext;
import org.jboss.ejb.client.PropertiesBasedEJBClientConfiguration;
import org.jboss.ejb.client.remoting.ConfigBasedEJBClientContextSelector;

public class Client {

/**
* @param args no args needed
* @throws Exception
*/
    public static void main(String[] args) throws Exception {
        // suppress output of client messages
        Logger.getLogger("org.jboss").setLevel(Level.OFF);
        Logger.getLogger("org.xnio").setLevel(Level.OFF);

        Properties p = new Properties();
        p.put("remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED", "false");
        p.put("remote.connections", "one");
        p.put("remote.connection.one.port", "8080");
        p.put("remote.connection.one.host", "localhost");
        p.put("remote.connection.one.username", "quickuser");
        p.put("remote.connection.one.password", "quick-123");

        EJBClientConfiguration cc = new PropertiesBasedEJBClientConfiguration(p);
        ContextSelector<EJBClientContext> selector = new ConfigBasedEJBClientContextSelector(cc);
        EJBClientContext.setSelector(selector);

        Properties props = new Properties();
        props.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
        InitialContext context = new InitialContext(props);


        final String rcal = "ejb:jboss-ejb-multi-server-app-main/ejb//" + ("MainAppBean") + "!" + MainApp.class.getName();
        final MainApp remote = (MainApp) context.lookup(rcal);
        final String result = remote.invokeAll("Client call at "+new Date());

        System.out.println("InvokeAll succeed: "+result);
    }

}

import org.jboss.ejb.client.EJBClient;
import javax.transaction.UserTransaction;
...
    Context context = null;
    UserTransaction tx = null;
    try {
      Properties props = new Properties();
      // REMEMBER: there must be a jboss-ejb-client.properties with the
      // connection parameter in the client's classpath
      props.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
      context = new InitialContext(props);
      System.out.println("\n\tGot initial Context: "+context);
      tx = EJBClient.getUserTransaction("yourServerName");
      System.out.println("UserTransaction = "+tx.getStatus());
      tx.begin();
      // do some work
      ...
    } catch (Exception e) {
      e.printStackTrace();
      tx.rollback();
    } finally{
      if(context != null) {
        context.close();
      }
    }

tx = EJBClient.getUserTransaction("yourServerName");

Internet Inter-ORB Protocol (IIOP) Remote Call

To invoke an EJB bean using an IIOP remote call, you must first enable IIOP on the server.

To enable IIOP you must have the iiop-openjdk subsystem installed and the <iiop/> element present in the ejb3 subsystem configuration. The standalone-full.xml configuration that comes with the distribution has both of these enabled.

For a bean to be reachable by IIOP remote call, it needs to use EJB 2 and home interface with narrowing. More details on IIOP remote invocation can be seen at Configure IIOP for Remote EJB Calls.

To enable JTS transactions on the server, you must change the transactions attribute from value spec to full in the iiop-openjdk subsystem and set the jts attribute in the transactions subsystem to true. You can accomplish this by using the following management CLI commands.

/subsystem=iiop-openjdk/:write-attribute(name=transactions,value=full)
/subsystem=transactions/:write-attribute(name=jts,value=true)

import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
import com.arjuna.ats.arjuna.recovery.RecoveryManager;
import com.arjuna.ats.internal.jts.ORBManager;
import com.arjuna.ats.internal.jts.context.ContextPropagationManager;
import com.arjuna.ats.jts.OTSManager;
import com.sun.corba.se.impl.orbutil.ORBConstants;
import com.arjuna.orbportability.ORB;
import com.arjuna.orbportability.OA;

final String host = "localhost";
final int port = 3528;

// For client we define how the Narayana will behave
System.setProperty("com.arjuna.ats.jts.alwaysPropagateContext", "true");

// Set orb to be initialized on client and being able to start ORB txn
Properties properties = new Properties();
properties.setProperty(ORBConstants.PERSISTENT_SERVER_PORT_PROPERTY, "15151");
properties.setProperty(ORBConstants.ORB_SERVER_ID_PROPERTY, "1");

// registers the appropriate filter with the ORB
new ContextPropagationManager();

org.omg.CORBA.ORB sunOrb = org.omg.CORBA.ORB.init(new String[0], properties);
ORB orb = null;
try {
    orb = com.arjuna.orbportability.ORB.getInstance("ClientSide");
    orb.setOrb(sunOrb);

    OA oa = OA.getRootOA(orb);
    org.omg.PortableServer.POA rootPOA = org.omg.PortableServer.POAHelper.narrow(sunOrb.resolve_initial_references("RootPOA"));
    oa.setPOA(rootPOA);

    oa.initOA();

    ORBManager.setORB(orb);
    ORBManager.setPOA(oa);

    // Recovery manager has to be started on client when we want recovery to work at client
    RecoveryManager.manager().startRecoveryManagerThread();

    // Getting context to lookup
    System.setProperty("com.sun.CORBA.ORBUseDynamicStub", "true");
    final Properties prope = new Properties();
    prope.put(Context.PROVIDER_URL, "corbaloc::" + host + ":" + port + "/JBoss/Naming/root");
    prope.setProperty(Context.URL_PKG_PREFIXES, "org.jboss.iiop.naming:org.jboss.naming.client");
    prope.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");
    Context context = new InitialContext(prope);

    // Bean lookup
    final Object iiopObj = context.lookup(IIOPBeanMandatory.class.getSimpleName());
    final IIOPBeanHome beanHome = (IIOPBeanHome) PortableRemoteObject.narrow(iiopObj, IIOPBeanHome.class);
    final IIOPRemote bean = beanHome.create();

    // Starting orb transaction
    OTSManager.get_current().begin();

    // Call bean - business logic
    bean.sayHello();

    // Manage the commit of the work
    OTSManager.get_current().commit(true);
    // or rollback
    // OTSManager.get_current().rollback();
} finally {
    // It's good to release resources - do it only once at the end
    if (orb != null) {
        orb.shutdown();
    }
    RecoveryManager.manager().terminate();
}

For more information, see Configuring Transactions in the JBoss EAP Configuration Guide.

JBoss EAP is secure by default. No communication can happen with a server instance from a remote client without passing the appropriate credentials, irrespective of whether it is a standalone client or another server instance. In order to allow a client server to communicate with a destination server, you must configure user credentials to be used during this server communication.

Following example demonstrates how to invoke EJBs deployed on a JBoss EAP server instance from another remote JBoss EAP server instance. For ease of reference, let us use the following aliases:

./standalone.sh -server-config=standalone-full.xml -Djboss.node.name=<add appropriate value here>

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

import javax.naming.Context;
import java.util.Hashtable;
import javax.naming.InitialContext;
…
public void invokeOnBean() {
        try {
            final Hashtable props = new Hashtable();
            // setup the ejb: namespace URL factory
            props.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
            // create the InitialContext
            final Context context = new javax.naming.InitialContext(props);
            // Lookup the Greeter bean using the ejb: namespace syntax which is explained here https://docs.jboss.org/author/display/AS71/EJB+invocations+from+a+remote+client+using+JNDI
            final Greeter bean = (Greeter) context.lookup("ejb:" + "myapp" + "/" + "myejb" + "/" + "" + "/" + "GreeterBean" + "!" + org.myapp.ejb.Greeter.class.getName());
            // invoke on the bean
            final String greeting = bean.greet("Tom");
            System.out.println("Received greeting: " + greeting);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
}

public class MyApplication {
    public static void main(String args[]) {

        // Use the "foo" security credential connect to the server and invoke this bean instance
        final Properties ejbClientContextPropsOne = getPropsForEJBClientContextOne():
        final javax.naming.Context ctxOne = new javax.naming.InitialContext(ejbClientContextPropsOne);
        final MyBeanInterface beanOne = ctxOne.lookup("ejb:app/module/distinct/bean!interface");
        beanOne.doSomething();
        ...
        ctxOne.close();

        // Use the "bar" security credential to connect to the server and invoke this bean instance
        final Properties ejbClientContextPropsTwo = getPropsForEJBClientContextTwo():
        final javax.naming.Context ctxTwo = new javax.naming.InitialContext(ejbClientContextPropsTwo);
        final MyBeanInterface beanTwo = ctxTwo.lookup("ejb:app/module/distinct/bean!interface");
        beanTwo.doSomething();
        ...
        ctxTwo.close();
    }
}

To use the scoped EJB client context, you configure EJB client properties programmatically and pass the properties on context creation. The properties are the same set of properties that are used in the standard jboss-ejb-client.properties file. To scope the EJB client context to the JNDI context, you must also specify the org.jboss.ejb.client.scoped.context property and set its value to true. This property notifies the EJB client API that it must create an EJB client context, which is backed by EJB receivers, and that the created context is then scoped or visible only to the JNDI context that created it. Any EJB proxies looked up or invoked using this JNDI context will only know of the EJB client context associated with this JNDI context. Other JNDI contexts used by the application to lookup and invoke EJBs will not know about the other scoped EJB client contexts.

JNDI contexts that do not pass the org.jboss.ejb.client.scoped.context property and are not scoped to an EJB client context will use the default behavior, which is to use the existing EJB client context that is typically tied to the entire application.

Scoped EJB client contexts provide user applications with the flexibility that was associated with the JNP based JNDI invocations in previous versions of JBoss EAP. It provides user applications with more control over which JNDI context communicates to which server and how it connects to that server.

Previous versions of JBoss EAP included a feature where the message stream that contained the EJB protocol message could be compressed. This feature has been included in JBoss EAP 6.3 and later.

Data compression hints can be specified via the JBoss annotation org.jboss.ejb.client.annotation.CompressionHint. The hint values specify whether to compress the request, response or request and response. Adding @CompressionHint defaults to compressResponse=true and compressRequest=true.

The annotation can be specified at the interface level to apply to all methods in the EJB’s interface such as:

import org.jboss.ejb.client.annotation.CompressionHint;

@CompressionHint(compressResponse = false)
public interface ClassLevelRequestCompressionRemoteView {
    String echo(String msg);
}

Or the annotation can be applied to specific methods in the EJB’s interface such as:

import org.jboss.ejb.client.annotation.CompressionHint;

public interface CompressableDataRemoteView {

    @CompressionHint(compressResponse = false, compressionLevel = Deflater.BEST_COMPRESSION)
    String echoWithRequestCompress(String msg);

    @CompressionHint(compressRequest = false)
    String echoWithResponseCompress(String msg);

    @CompressionHint
    String echoWithRequestAndResponseCompress(String msg);

    String echoWithNoCompress(String msg);
}

The compressionLevel setting shown above can have the following values:

The compressionLevel setting defaults to Deflater.DEFAULT_COMPRESSION.

Class level annotation with method level overrides:

@CompressionHint
public interface MethodOverrideDataCompressionRemoteView {

    @CompressionHint(compressRequest = false)
    String echoWithResponseCompress(final String msg);

    @CompressionHint(compressResponse = false)
    String echoWithRequestCompress(final String msg);

    String echoWithNoExplicitDataCompressionHintOnMethod(String msg);
}

On the client side ensure the org.jboss.ejb.client.view.annotation.scan.enabled system property is set to true. This property tells JBoss EJB Client to scan for annotations.

The default remote connection port is 8080. The jboss-ejb-client properties file looks like this:

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

Default Connector

The default connector is http-remoting.

Besides EJB client remoting interoperability, you can connect to legacy clients using the following options:

JBoss EAP supports CORBA/IIOP-based access to EJBs deployed on JBoss EAP.

The <iiop> element is used to enable IIOP, CORBA, invocation of EJBs. The presence of this element means that the iiop-openjdk subsystem is installed. The <iiop> element includes the following two attributes:

Enabling IIOP

To enable IIOP you must have the IIOP OpenJDK ORB subsystem installed, and the <iiop/> element present in the ejb3 subsystem configuration. The standalone-full.xml configuration that comes with the distribution has both of these enabled.

IIOP is configured in the iiop-openjdk subsystem of the server configuration file.

<subsystem xmlns="urn:jboss:domain:iiop-openjdk:1.0">

Use the following management CLI command to access and update the iiop-openjdk subsystem.

/subsystem=iiop-openjdk

The IIOP element takes two attributes that control the default behavior of the server.

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
  ...
  <iiop enable-by-default="false" use-qualified-name="false"/>
  ...
</subsystem>

The following management CLI command adds the <iiop> element under the ejb3 subsystem:

/subsystem=ejb3/service=iiop:add(enable-by-default=false, use-qualified-name=false)

Create an EJB That Communicates Using IIOP

The following example demonstrates how to make a remote IIOP call from the client: