This article summarizes some new features that will be enabled in EAP 7.1 for applications using remote EJB clients. These new features will improve some aspects of the remote EJB communication such as:
- A simplified method for looking up remote EJBs
- A new annotation to control transaction propagation from remote EJB clients
- A new annotation to enable Client side interceptors for EJB calls
- An update in the remote EJB client configuration file
- Simplified lookup of remote EJBs
Let's see them in detail:
Simplified Initial context lookup
Traditionally, the lookup of remote EJBs required a bit of complexity for the developers (See the following solution). The most common approach was to embed the remote destination host and port (along with security information) into a separate configuration file (jboss-ejb-client.properties). Although this decoupling is considered a good design practice, for the sake of writing quickly a simple application client with as little as a Java class, you can now embed this information into the Initial Context, through the "remote+http" protocol as in the following example:
import org.jboss.ejb.client.EJBClient;
public void callRemoteEjb() {
HelloRemote remote = getInitialContext(host, port, user, pass).lookup("ejb:helloWorld/helloWorld-ejb/HelloWorldSLSB!org.jboss.examples.ejb.HelloRemote");
remote.helloWorld();
}
public static Context getInitialContext(String host, Integer port, String username, String password) {
Properties props = new Properties();
props.put(Context.INITIAL_CONTEXT_FACTORY, "org.wildfly.naming.client.WildFlyInitialContextFactory");
props.put(Context.PROVIDER_URL, String.format("%s://%s:%d", "remote+http", host, port));
props.put(Context.SECURITY_PRINCIPAL, username)
props.put(Context.SECURITY_CREDENTIALS, password);
return new InitialContext(props);
}
Also, please note that, since EAP 7.1, the new Initial Context Factory to be used for the lookup is now org.wildfly.naming.client.WildFlyInitialContextFactory.
New remote configuration file
The file jboss-ejb-client.properties which we have already mentioned, can still be used is used to define the remote connection properties and authentication details, however, it's now deprecated. EAP 7.1 features the new Elytron security framework, so you are encouraged to migrate to the wildfly-config.xml file, which allows a wider range of authentication/authorization options. As a proof of concept, the following wildfly-config.xml can be used to allow an SASL Digest-MD5 authentication using the credentials "admin" and "password123!".
<configuration>
<authentication-client xmlns="urn:elytron:1.0">
<authentication-rules>
<rule use-configuration="default" />
</authentication-rules>
<authentication-configurations>
<configuration name="default">
<allow-sasl-mechanisms names="DIGEST-MD5" />
<forbid-sasl-mechanisms names="JBOSS-LOCAL-USER" />
<set-user-name name="admin" />
<credentials>
<clear-password password="password123!" />
</credentials>
<use-service-loader-providers />
</configuration>
</authentication-configurations>
</authentication-client>
<jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
<connections>
<connection uri="${remote.ejb.url}" />
</connections>
</jboss-ejb-client>
</configuration>
Also, please notice in the above example, that the EJB Client relevant part (in the jboss-ejb-client stanza) is where we provide the Connection URI as a System Property.
EJB Client interceptors
EJB Interceptors are mostly used, as the word suggest, to intercept a call to an EJB method so that you can apply any proxy logic to it. For example, you could log the call to the EJB or deny accessing some methods under some conditions. EJB Interceptors can be however placed also in the Client side of the remote call. Until JBoss EAP 7.1, if you wanted to register Interceptors to the remote EJB client communication you had to apply one of the following approaches:
- Programmatically:
EJBClientContext.getCurrent().registerInterceptor(0, new HelloClientInterceptor());
- Creating a file in the META-INF/services directory named org.jboss.ejb.client.EJBClientInterceptor and list the fully qualified name of your client interceptor class. For example:
$ echo "com.jboss.examples.ejb3.client.HelloClientInterceptor" > META-INF/services/org.jboss.ejb.client.EJBClientInterceptor
Now since EAP 7.1 there is now annotation @org.jboss.ejb.client.annnotation.ClientInterceptors which makes the client side work very similar to the way the standard EE service side interceptors work:
import org.jboss.ejb.client.annotation.ClientInterceptors;
@ClientInterceptors({HelloClientInterceptor.class})
public interface HelloBeanRemote {
public String hello();
}
Here is the sample Client Interceptor which implements the EJBClientInterceptor interface:
import org.jboss.ejb.client.EJBClientInterceptor;
import org.jboss.ejb.client.EJBClientInvocationContext;
public class HelloClientInterceptor implements EJBClientInterceptor {
@Override
public void handleInvocation(EJBClientInvocationContext context) throws Exception {
context.getContextData().put(CLIENT_DATA, clientData);
context.sendRequest();
}
@Override
public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
try {
return context.getResult();
} finally {
context.getContextData().get(CLIENT_DATA), SERVER_DATA, context.getContextData().get(SERVER_DATA)));
}
}
}
The new ClientTransaction annotation
In EAP 7.1 a new annotation, named @org.jboss.ejb.client.annotation.ClientTransaction has been introduced to handle transaction propagation from an EJB Client so that you can either mandate it (i.e. fail if the client has no transaction) or prevent it (i.e. propagate no transaction even if the client has one active). You can control the policy of the ClientTransaction annotation through the Constants of org.jboss.ejb.client.annotation.ClientTransactionPolicy interface, which is the following:
- MANDATORY: Fail with exception when there is no client-side transaction context; propagate the client-side transaction context when it is present.
- NEVER: Invoke without propagating any transaction context; if a client-side transaction context is present, an exception is thrown.
- NOT_SUPPORTED: Invoke without propagating any transaction context whether or not a client-side transaction context is present.
- SUPPORTS: Invoke without a transaction if there is no client-side transaction context; propagate the client-side transaction context if it is present.
If no annotation is present, the default policy is "org.jboss.ejb.client.annotation.ClientTransactionPolicy#SUPPORTS", which means that the transaction will be propagated if it is present, but will not fail regardless of whether or not a transaction is present.
The annotation applies to each method of the remote interface, or to the completely remote interface as a default value. It affects only calls to that method on that interface.
@ClientTransaction(ClientTransactionPolicy.MANDATORY)
public interface RemoteCalculator {
public void callRemoteEjb() { }
}
@Stateless
@Remote(RemoteCalculator.class)
public class CalculatorBean implements RemoteCalculator {
@Override
public void callRemoteEjb() { }
}
The annotation gives a way for the remote interface provider to tell the remote interface consumer that transactions are not needed, or are required, for a method, allowing the client to avoid or require outflow as needed.
About the Author:
Francesco Marchioni is a Senior Technical Account Manager on Middleware products based in Rome (Italy). Some of its contributions to the Community of JBoss developers are available on the site http://www.mastertheboss.com
References:
https://access.redhat.com/solutions/3061121
Click here and quickly get started with Red Hat JBoss EAP download.
Last updated: March 22, 2023