Chapter 5. Invoking Session Beans

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

Depending on the type of remote client, from a Jakarta Enterprise Beans 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 Jakarta Enterprise Beans receivers, this isn’t mandatory. If a standalone application has more than one EJBClientContext, a Jakarta Enterprise Beans 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 Jakarta Enterprise Beans client context. Whenever that application invokes another Jakarta Enterprise Beans, the corresponding Jakarta Enterprise Beans client context is used to find the correct Jakarta Enterprise Beans receiver, which then handles the invocation.

You can compress message streams containing Enterprise Beans protocol message

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 Jakarta Enterprise Beans 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 Jakarta Enterprise Beans 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 Jakarta Enterprise Beans Client to scan for annotations.

Remote Jakarta Enterprise Beans client applications use connectors defined in the remoting subsystem in order to connect to the server. You can use one of the following connectors based on your needs:

Default HTTP connector

The default connector is http-connector, which requires that the client use the URI scheme remote+http or remote+https. The default remote connection port is 8080, which is the same default port for undertow. The following example shows a jboss-ejb-client properties file:

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

Supporting clients from different JBoss EAP versions

If a client application uses the Jakarta Enterprise Beans client library from JBoss EAP 6 and requires a connection to a JBoss EAP 7 server, you must configure the server to expose a remoting connector on a port other than 8080. The client must then connect by using that newly configured connector.

A client application that uses the Jakarta Enterprise Beans client library from JBoss EAP 7 and requires a connection to a JBoss EAP 6 server must be aware that the server instance does not use the remoting http-remoting connector and instead uses a remoting connector connector. This is achieved by defining the following new client-side connection property:

remote.connection.default.protocol=remote

Supporting multiple connectors for Jakarta Enterprise Beans client applications

Prior to JBoss EAP 7.4, Jakarta Enterprise Beans client applications were limited to using only one remoting connector, defined in the remoting subsystem, to connect to a server. This connector was specified in the connector-ref attribute of the remote element of the ejb3 subsystem. You could either use the default http-connector for providing a connection through the HTTP upgrade feature of undertow with the remote+http protocol or use a legacy connector for providing a connection through the legacy remote protocol.

With JBoss EAP 7.4, you can specify a list of connectors that Jakarta Enterprise Beans clients can use for connection purposes. To specify this list, use the new connectors attribute of the remote element. The connectors attribute accepts a list of connectors defined in the remoting subsystem. This enables a single server to provide multiple connections for Jakarta Enterprise Beans client applications. For example, clients compatible with EAP 7.2 or later can connect to the server using the remote+http protocol with an http-connector and legacy clients compatible with prior versions of EAP 7.2 can connect using the legacy remote protocol with a connector.

/subsystem=ejb3/service=remote:write-attribute(name=connectors, value=[http-remoting-connector, legacy-remoting-connector])

You can view the domain.xml or standalone.xml file to check the configured remoting connectors in the ejb3 subsystem:

<remote cluster="ejb" connectors="http-remoting-connector legacy-remoting-connector" thread-pool-name="default">
  <channel-creation-options>
   <option name="MAX_OUTBOUND_MESSAGES" value="1234" type="remoting"/>
  </channel-creation-options>
</remote>

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

JBoss EAP supports CORBA/IIOP-based access to Jakarta Enterprise Beans deployed on JBoss EAP.

The <iiop> element is used to enable IIOP, CORBA, invocation of Jakarta Enterprise Beans. 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:2.1">

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:5.0">
  ...
  <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 a Jakarta Enterprise Beans That Communicates Using IIOP

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

You can determine the Jakarta Enterprise Beans client address using the SessionContext interface, as shown in the example below.

public class HelloBean implements HelloBeanRemote {
    @Resource
    SessionContext ctx;
    private Long counter;
    public HelloBean() {
    }
    @PostConstruct
    public void init() {
        counter = 0L;
    }
    @Override
    @RolesAllowed("users")
    public String hello() {
        final String message = "method hello() invoked by user " + ctx.getCallerPrincipal().getName()
                + ", source addr = " +  ctx.getContextData().get("jboss.source-address").toString();
        System.out.println(message);
        return message;
    }
}

Standalone Client Configuration

You can configure the outbound-bind-addresses element within the worker element having namespace urn:xnio:3.5 in the wildfly-config.xml file. The bind-address sub-element takes the attributes match, bind-address, bind-port, as defined below.

The following is an example of the standalone client configuration using the wildfly-config.xml file.

<configuration>
    <worker xmlns="urn:xnio:3.5">
        <worker-name value="default"/>
        <outbound-bind-addresses>
            <bind-address bind-address=IP_ADDRESS_TO_BIND_TO bind-port=OPTIONAL_SOURCE_PORT_NUMBER match=CIDR_BLOCK />
        </outbound-bind-addresses>
    </worker>
</configuration>

The outbound-bind-address requires the following attributes:

Container-based Configuration

Container-based configuration of the Jakarta Enterprise Beans client address is similar to the standalone client configuration defined in the wildfly-config.xml file.

The example below configures the outbound-bind-address on the default worker element of the io subsystem, which the ejb3 subsystem uses by default.

/subsystem=io/worker=default/outbound-bind-address=SPECIFY_OUTBOUND_BIND_ADDRESS:add(bind-address=IP_ADDRESS_TO_BIND_TO, bind-port=OPTIONAL_SOURCE_PORT_NUMBER, match=CIDR_BLOCK)

Jakarta Enterprise Beans invocation over HTTP includes two distinct parts: the client-side and the server-side implementations.

<dependency>
    <groupId>org.wildfly.wildfly-http-client</groupId>
    <artifactId>wildfly-http-ejb-client</artifactId>
</dependency>

/subsystem=undertow/server=default-server/host=default-host/setting=http-invoker:add(http-authentication-factory=myfactory, path="wildfly-services")