http://www.jroller.com/sjivan/entry/lingo_spring_remoting_passing_client

Lingo (Spring Remoting) : Passing client credentials to the server

Spring Remoting allows you to export a service interface which a remote client then then look up. Once the remote service interface is looked up, the client can work with this reference like its a local object reference. Well, kinda. There are certain limitations that are associated depending on the remoting transport protocol used.

The Spring distribution currently supports RMI, Spring‘s HTTP invoker, Hessian, Burlap and JAX-RPC. One of the biggest limitations in these transports is that none of them support passing a method argument by reference. This can be a show stopper for a several usecases such as callbacks. RMI as a transport protocol does support pass-by-reference however the Spring RMI Remoting Strategy does not support this yet. Regardless, RMI is a heavy weight protocol so I‘m not a big fan of it.

This brings us to Lingo, an implementation of Spring Remoting over JMS which does support remote callbacks - the contract being that such arguments must either implement java.rmi.Remote or java.util.EventListener. Lingo also supports asynchronous one-way method invocations.

A common requirement in a client-server communication protocol is the propagation of the client‘s security context to the server during a remote method invocation. One could pass this information as an argument to every method call but that‘s a really really ugly way to go about it. The right way to do this would be to make such information available in as a ThreadLocal context variable on the server. Lingo does not support passing of client credentials to the server out of the box.

I examined the Lingo code found that adding support for this functionality was actually quite easy. I‘ll cover most of the details here. You can download the entire source for this as well.

Lingo uses Marshaller‘s on the client and server side which basically negotiates the underlying client-server JMS communication.

Lingo Marshaller‘s have a hook for adding and extracting custom JMS header messages. So I created a custom client Marshaller which adds the users Principal (user name) to the message header and a custom server Marshaller which reads this information and makes it available as a ThreadLocal context variable.

Here‘s the code for an Acegi based client marshaller.

public class AcegiClientMarshaller extends DefaultMarshaller {
    protected void appendMessageHeaders(Message message, Requestor requestor,
                                        LingoInvocation invocation) throws JMSException {
        SecurityContext sc = SecurityContextHolder.getContext();
        Authentication auth = sc.getAuthentication();
 

        //if you‘re using a custom acegi principal, update this code accordingly
        String userName = null;
        if (auth != null) {
            Object principal = auth.getPrincipal();
            if (principal instanceof net.sf.acegisecurity.UserDetails) {
                userName = ((net.sf.acegisecurity.UserDetails) principal).getUsername();
            } else if (principal instanceof String) {
                userName = (String) principal;
            } else {
                throw new IllegalArgumentException("Invalid principal " + principal);
            }
        }

 
        //add user name info to the message header
        message.setStringProperty(Constants.JMS_CLIENT_ID_PROPERTY, userName);
    }
}

As you can see, I grab the principal (user name in our case) of the authenticated user and add it as a custom header property. (I have another simple implementation of a client Marshaller in the source distribution). Even if you‘re not using Acegi, you can basically follow a similar logic as above to add the client context info as a custom header message.

Now we need to create a server (un)Marshaller which extracts this information and puts it in a ThreadLocal context variable.

public class ServerMarshaller extends DefaultMarshaller {
 
    private static final Log log = LogFactory.getLog(DefaultMarshaller.class);

 
    protected void handleInvocationHeaders(Message message) {
        try {            
            String userName = message.getStringProperty(Constants.JMS_CLIENT_ID_PROPERTY);
            ClientContextHolder.setContext(new ClientContextImpl(userName));
        }
        catch (JMSException e) {
            log.error(e.getMessage());
            throw new RuntimeException("An Unexpected error occured " + e.getMessage(), e);
        }
    }
}

Note that in this example we are just passing the user-name String as client context data, however you‘re not limited to using String‘s. You can use message.setObjectProperty(..) and message.getObjectProperty() and pass richer context information. The Object would need to be Serializable though.

Now the final step of hooking up the pieces in the client and server Spring ApplicationContext files.

The client configuration file looks like

<?xml version="1.0" encoding="UTF-8"?> 
 
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"> 
<beans>    <!-- client side -->    <bean id="clientOne" class="org.logicblaze.lingo.jms.JmsProxyFactoryBean">        <property name="serviceInterface" value="org.sanjiv.lingo.test.ExampleService"/>        <property name="connectionFactory" ref="jmsFactory"/>        <property name="destination" ref="exampleDestination"/>        <property name="marshaller" ref="acegiClientMarshaller"/>    </bean> 
    <bean id="acegiClientMarshaller" class="org.sanjiv.lingo.client.AcegiClientMarshaller"/> 
    <!-- JMS ConnectionFactory to use -->    <bean id="jmsFactory" class="org.activemq.ActiveMQConnectionFactory">        <property name="brokerURL" value="vm://localhost"/>    </bean></beans> 

And the server configuration file looks like

<?xml version="1.0" encoding="UTF-8"?> 
 
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"> 
<beans>    <!-- the server side -->    <bean id="serverImpl" class="org.sanjiv.lingo.test.ExampleServiceImpl" singleton="true"/> 
    <bean id="server" class="org.logicblaze.lingo.jms.JmsServiceExporter">        <property name="service" ref="serverImpl"/>        <property name="serviceInterface" value="org.sanjiv.lingo.test.ExampleService"/>        <property name="connectionFactory" ref="jmsFactory"/>        <property name="destination" ref="exampleDestination"/>        <property name="marshaller" ref="serverMarshaller"/>    </bean> 
    <bean id="serverMarshaller" class="org.sanjiv.lingo.server.ServerMarshaller"/> 
    <!-- JMS ConnectionFactory to use -->    <bean id="jmsFactory" class="org.activemq.ActiveMQConnectionFactory">        <property name="brokerURL" value="vm://localhost"/>    </bean> 
    <bean id="exampleDestination" class="org.activemq.message.ActiveMQQueue">        <constructor-arg index="0" value="test.org.sanjiv.lingo.example"/>    </bean></beans>

During execution of a remote method, you can extract the client context info by looking it up in the ThreadLocal context variable as illustrated by this example :

public class ExampleServiceImpl implements ExampleService {
 
    public String whoAmI() {
        String userName = ClientContextHolder.getUserName();
        return userName != null ? userName : "annonymous";
    }
}

The source for the ClientContextHolder class which manages the ThreadLocal variables is :

public class ClientContextHolder {
 
    private static InheritableThreadLocal contextHolder = new InheritableThreadLocal();
 
    /**
     * Associates a new ClientContext with the current thread of execution.
     */

    public static void setContext(ClientContext context) {
        contextHolder.set(context);
    }
 
    /**
     * Obtains the <code>ClientContext</code> associated with the current thread of execution.
     *
     * @return the current ClientContext
     */

    public static ClientContext getContext() {
        if (contextHolder.get() == null) {
            contextHolder.set(new ClientContextImpl());
        }
 
        return (ClientContext) contextHolder.get();
    }

 
    public static String getUserName() {
        return ((ClientContext) contextHolder.get()).getUserName();
    }
}

And there you have it. You can download the complete source for this here and check out the test case to get a better feel of how all the pieces hang together. JRoller doesn‘t allow uploading .zip files so I‘ve uploaded the sample as a .jar file instead. The source distribution has a Maven 1.x project file. To build and run the tests, run "maven jar".

I like Lingo, it‘s simple and does the job well. I only wish there was a more active and responsive mailing list.

Feedback welcome.

Update 5/01/06 : I recently required to propagate the client‘s locale to the server as well and used a similar approach as above. Basically I created a composite ClientMarshaller and ServerMarshaller and added the Client and Server marshallers for propagating the principal (as shown above) and the client‘s locale declaratively in the Spring applicaiton context file. Here‘s the relevant code snippet : In LocaleClientMarshaller :

Locale locale = LocaleContextHolder.getLocale();
message.setStringProperty(OptimizerConstants.JMS_LOCALE_LANGUAGE_PROPERTY, locale.getLanguage());
message.setStringProperty(OptimizerConstants.JMS_LOCALE_COUNTRY_PROPERTY, locale.getCountry());

and in LocaleServerMarshaller

String language = message.getStringProperty(OptimizerConstants.JMS_LOCALE_LANGUAGE_PROPERTY);
String country = message.getStringProperty(OptimizerConstants.JMS_LOCALE_COUNTRY_PROPERTY);
if (language != null){
  country = country == null ? "" : country;
  Locale locale = new Locale(language, country);
  LocaleContextHolder.setLocale(locale);
}

Note that I had previously mentioned that in addition to custom String headers, you could add any object that is serializable. Unfortunately this does not work.

org.activemq.message.ActiveMqMessage.setObjectMessage() only supports String and wrappers of primitive data type. And this behavior is specified in the JMS spec.

The setObjectProperty method accepts values of class Boolean, Byte, Short, Integer, Long, Float, Double and String. An attempt to use any other class must throw a JMSException. As a result I cannot pass the java.util.Locale object directly but instead pass the country and language as separate header properties.

Update 07/21/06 : I have commited this functionality into the Lingo codebase. This feature will be available in the Lingo 1.2 release which is due any day now.

Lingo (Spring Remoting) : Passing client credentials to the server