org.jboss.ejb.client.EJBClient Maven / Gradle / Ivy
Go to download
This artifact provides a single jar that contains all classes required to use remote Jakarta Enterprise Beans and Jakarta Messaging, including
all dependencies. It is intended for use by those not using maven, maven users should just import the Jakarta Enterprise Beans and
Jakarta Messaging BOM's instead (shaded JAR's cause lots of problems with maven, as it is very easy to inadvertently end up
with different versions on classes on the class path).
/*
* JBoss, Home of Professional Open Source.
* Copyright 2011, Red Hat, Inc., and individual contributors
* as indicated by the @author tags. See the copyright.txt file in the
* distribution for a full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.jboss.ejb.client;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Proxy;
import java.util.Collection;
import java.util.HashSet;
import java.util.concurrent.Future;
import javax.transaction.UserTransaction;
/**
* The main EJB client API class. This class contains helper methods which may be used to create proxies, open sessions,
* and associate the current invocation context.
*
* @author jpai
* @author David M. Lloyd
*/
public final class EJBClient {
private static final Logs log = Logs.MAIN;
static {
log.greeting(Version.getVersionString());
}
private EJBClient() {
}
private static final ThreadLocal> FUTURE_RESULT = new ThreadLocal>();
/**
* Get an asynchronous view of a proxy. Any {@code void} method on the proxy will be invoked fully asynchronously
* without a server round-trip delay. Any method which returns a {@link java.util.concurrent.Future Future} will
* continue to be asynchronous. Any other method invoked on the returned proxy will return {@code null} (the future
* result can be acquired by wrapping the remote call with {@link #getFutureResult(Object)} or by using {@link #getFutureResult()}).
* If an asynchronous view is passed in, the same view is returned.
*
* @param proxy the proxy interface instance
* @param the proxy type
* @return the asynchronous view
* @throws IllegalArgumentException if the given object is not a valid proxy
*/
@SuppressWarnings("unchecked")
public static T asynchronous(final T proxy) throws IllegalArgumentException {
final InvocationHandler invocationHandler = Proxy.getInvocationHandler(proxy);
if (invocationHandler instanceof EJBInvocationHandler) {
final EJBInvocationHandler remoteInvocationHandler = (EJBInvocationHandler) invocationHandler;
// determine proxy "type", return existing instance if it's already async
if (remoteInvocationHandler.isAsyncHandler()) {
return proxy;
} else {
return (T) Proxy.newProxyInstance(proxy.getClass().getClassLoader(), proxy.getClass().getInterfaces(), remoteInvocationHandler.getAsyncHandler());
}
} else {
throw log.unknownProxy(proxy);
}
}
/**
* Get the future result of an operation. Should be called in conjunction with {@link #asynchronous(Object)}.
*
* @param operation the operation
* @param the result type
* @return the future result
* @throws IllegalStateException if the operation is not appropriately given
*/
@SuppressWarnings("unchecked")
public static Future getFutureResult(final T operation) throws IllegalStateException {
if (operation != null) {
return new FinishedFuture(operation);
}
final ThreadLocal> futureResult = FUTURE_RESULT;
try {
final Future future = futureResult.get();
if (future == null) throw log.noAsyncInProgress();
return (Future) future;
} finally {
futureResult.remove();
}
}
/**
* Get the future result of an operation. Should be called in conjunction with {@link #asynchronous(Object)}.
*
* @return the future result
* @throws IllegalStateException if the operation is not appropriately given
*/
public static Future getFutureResult() throws IllegalStateException {
final ThreadLocal> futureResult = FUTURE_RESULT;
try {
final Future future = futureResult.get();
if (future == null) throw log.noAsyncInProgress();
return future;
} finally {
futureResult.remove();
}
}
static void setFutureResult(final Future future) {
FUTURE_RESULT.set(future);
}
/**
* Create a new proxy for the remote object identified by the given locator.
*
* @param locator the locator
* @param the proxy type
* @return the new proxy
* @throws IllegalArgumentException if the locator parameter is {@code null} or is invalid
*/
public static T createProxy(final EJBLocator locator) throws IllegalArgumentException {
return createProxy(locator, null);
}
/**
* Creates a new proxy for the remote object identified by the given locator and
* associates that proxy with the passed {@link EJBClientContextIdentifier identifier}
*
* @param locator The locator
* @param identifier The EJB client context identifier to associate this proxy with. Can be null.
* @param The proxy type
* @return IllegalArgumentException if the locator {@code null}
*/
public static T createProxy(final EJBLocator locator, final EJBClientContextIdentifier identifier) {
if (locator == null) {
throw Logs.MAIN.paramCannotBeNull("EJB locator");
}
return locator.createProxyInstance(new EJBInvocationHandler(identifier, locator));
}
/**
* Determine whether an object is indeed a valid EJB proxy object created by this API.
*
* @param object the object to test
* @return {@code true} if it is an EJB proxy, {@code false} otherwise
*/
public static boolean isEJBProxy(final Object object) {
return object != null && Proxy.isProxyClass(object.getClass()) && Proxy.getInvocationHandler(object) instanceof EJBInvocationHandler;
}
/**
* Create a new EJB session.
*
* @param viewType the view type
* @param appName the application name
* @param moduleName the module name
* @param beanName the EJB name
* @param distinctName the module distinct name
* @return the new session ID
* @throws Exception if an error occurs
*/
// TODO: narrow exception type(s)
public static StatefulEJBLocator createSession(final Class viewType, final String appName, final String moduleName, final String beanName, final String distinctName) throws Exception {
return createSession(null, viewType, appName, moduleName, beanName, distinctName);
}
/**
* Create a new EJB session.
*
* @param ejbClientContextIdentifier The EJB client context identifier. Can be null in which case the session will
* be created using the {@link org.jboss.ejb.client.EJBClientContext#requireCurrent() current active EJB client context}
* @param viewType the view type
* @param appName the application name
* @param moduleName the module name
* @param beanName the EJB name
* @param distinctName the module distinct name
* @return the new session ID
* @throws Exception if an error occurs
*/
// TODO: narrow exception type(s)
public static StatefulEJBLocator createSession(final EJBClientContextIdentifier ejbClientContextIdentifier, final Class viewType, final String appName, final String moduleName, final String beanName, final String distinctName) throws Exception {
final EJBClientContext clientContext;
if (ejbClientContextIdentifier != null) {
// find the appropriate EJB client context
clientContext = EJBClientContext.require(ejbClientContextIdentifier);
} else {
// use the "current" EJB client context
clientContext = EJBClientContext.requireCurrent();
}
return createSessionWithPossibleRetries(clientContext, new HashSet(), viewType, appName, moduleName, beanName, distinctName);
}
/**
* Create a new EJB session with possible retries to different eligible node(s) if the session creation failed on some node(s)
*
* @param clientContext The EJB client context
* @param excludedNodeNames The node names of EJB receivers which have to be ignored while selecting a EJB receiver for handling the session creation
* @param viewType The view type
* @param appName The app name
* @param moduleName Module name
* @param beanName bean name
* @param distinctName Distinct name
* @param
* @return
* @throws Exception
*/
private static StatefulEJBLocator createSessionWithPossibleRetries(final EJBClientContext clientContext, final Collection excludedNodeNames, final Class viewType, final String appName,
final String moduleName, final String beanName, final String distinctName) throws Exception {
// find a receiver
final EJBReceiver ejbReceiver = clientContext.requireEJBReceiver(excludedNodeNames, appName, moduleName, distinctName);
final EJBReceiverContext receiverContext = clientContext.requireEJBReceiverContext(ejbReceiver);
try {
return ejbReceiver.openSession(receiverContext, viewType, appName, moduleName, distinctName, beanName);
} catch (Exception e) {
Logs.MAIN.debugf(e, "Retrying session creation which failed on node %s due to:", ejbReceiver.getNodeName());
// retry ignoring the current failed node
excludedNodeNames.add(ejbReceiver.getNodeName());
return createSessionWithPossibleRetries(clientContext, excludedNodeNames, viewType, appName, moduleName, beanName, distinctName);
}
}
/**
* Get the locator for a proxy, if it has one.
*
* @param proxy the proxy
* @return the locator
* @throws IllegalArgumentException if the given proxy is not a valid client proxy instance
*/
public static EJBLocator getLocatorFor(T proxy) throws IllegalArgumentException {
return EJBInvocationHandler.forProxy(proxy).getLocator();
}
/**
* Get the {@link EJBClientContextIdentifier} associated with the passed EJB proxy. If no {@link EJBClientContextIdentifier}
* is associated with the proxy then this method returns null.
*
* @param proxy The EJB proxy
* @return
* @throws IllegalArgumentException If the passed proxy is not a valid EJB proxy
*/
public static EJBClientContextIdentifier getEJBClientContextIdentifierFor(Object proxy) throws IllegalArgumentException {
return EJBInvocationHandler.forProxy(proxy).getEjbClientContextIdentifier();
}
/**
* Get a {@code UserTransaction} object instance which can be used to control transactions on a specific node.
*
* @param targetNodeName the node name
* @return the {@code UserTransaction} instance
* @throws IllegalStateException if the transaction context isn't set or cannot provide a {@code UserTransaction} instance
*/
public static UserTransaction getUserTransaction(String targetNodeName) {
return EJBClientTransactionContext.requireCurrent().getUserTransaction(targetNodeName);
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy