Using the RmiServiceExporter, we can expose the interface of our AccountService object as RMI object. The interface can be accessed by using RmiProxyFactoryBean, or via plain RMI in case of a traditional RMI service. The RmiServiceExporter explicitly supports the exposing of any non-RMI services via RMI invokers.

Of course, we first have to set up our service in the Spring BeanFactory:

<bean id="accountService" class="example.AccountServiceImpl">
    <!-- any additional properties, maybe a DAO? -->
</bean>
				

Next we'll have to expose our service using the RmiServiceExporter:

<bean class="org.springframework.remoting.rmi.RmiServiceExporter">
	<!-- does not necessarily have to be the same name as the bean to be exported -->
	<property name="serviceName" value="AccountService"/>
	<property name="service" ref="accountService"/>
	<property name="serviceInterface" value="example.AccountService"/>
	<!-- defaults to 1099 -->
	<property name="registryPort" value="1199"/>
</bean>
				

As you can see, we're overriding the port for the RMI registry. Often, your application server also maintains an RMI registry and it is wise to not interfere with that one. Furthermore, the service name is used to bind the service under. So right now, the service will be bound at rmi://HOST:1199/AccountService. We'll use the URL later on to link in the service at the client side.

Note: We've left out one property, i.e. the servicePort property, which is 0 by default. This means an anonymous port will be used to communicate with the service. You can specify a different port if you like.

Our client is a simple object using the AccountService to manage accounts:

public class SimpleObject {
  private AccountService accountService;
  public void setAccountService(AccountService accountService) {
    this.accountService = accountService;
  }
}
				

To link in the service on the client, we'll create a separate bean factory, containing the simple object and the service linking configuration bits:

<bean class="example.SimpleObject">
	<property name="accountService" ref="accountService"/>
</bean>

<bean id="accountService" class="org.springframework.remoting.rmi.RmiProxyFactoryBean">
	<property name="serviceUrl" value="rmi://HOST:1199/AccountService"/>
	<property name="serviceInterface" value="example.AccountService"/>
</bean>
				

That's all we need to do to support the remote account service on the client. Spring will transparently create an invoker and remotely enable the account service through the RmiServiceExporter. At the client we're linking it in using the RmiProxyFactoryBean.

Hessian communicates via HTTP and does so using a custom servlet. Using Spring's DispatcherServlet principles, you can easily wire up such a servlet exposing your services. First we'll have to create a new servlet in your application (this an excerpt from web.xml):

<servlet>
	<servlet-name>remoting</servlet-name>
	<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
	<servlet-name>remoting</servlet-name>
	<url-pattern>/remoting/*</url-pattern>
</servlet-mapping>
				

You're probably familiar with Spring's DispatcherServlet principles and if so, you know that now you'll have to create an application context named remoting-servlet.xml (after the name of your servlet) in the WEB-INF directory. The application context will be used in the next section.

In the newly created application context called remoting-servlet.xml, we'll create a HessianServiceExporter exporting your services:

<bean id="accountService" class="example.AccountServiceImpl">
  <!-- any additional properties, maybe a DAO? -->
</bean>

<bean name="/AccountService" class="org.springframework.remoting.caucho.HessianServiceExporter">
  <property name="service" ref="accountService"/>
  <property name="serviceInterface" value="example.AccountService"/>
</bean>
				

Now we're ready to link in the service at the client. No explicit handler mapping is specified, mapping request URLs onto services, so BeanNameUrlHandlerMapping will be used: hence, the service will be exported at the URL indicated through its bean name: http://HOST:8080/remoting/AccountService.

Using the HessianProxyFactoryBean we can link in the service at the client. The same principles apply as with the RMI example. We'll create a separate bean factory or application context and mention the following beans where the SimpleObject is using the AccountService to manage accounts:

<bean class="example.SimpleObject">
  <property name="accountService" ref="accountService"/>
</bean>

<bean id="accountService" class="org.springframework.remoting.caucho.HessianProxyFactoryBean">
	<property name="serviceUrl" value="http://remotehost:8080/AccountService"/>
	<property name="serviceInterface" value="example.AccountService"/>
</bean>
				

That's all there is to it.

We won't discuss Burlap, the XML-based equivalent of Hessian, in detail here, since it is configured and set up in exactly the same way as the Hessian variant explained above. Just replace the word Hessian with Burlap and you're all set to go.

One of the advantages of Hessian and Burlap is that we can easily apply HTTP basic authentication, because both protocols are HTTP-based. Your normal HTTP server security mechanism can easily be applied through using the web.xml security features, for example. Usually, you don't use per-user security credentials here, but rather shared credentials defined at the Hessian/BurlapProxyFactoryBean level (similar to a JDBC DataSource).

<bean class="org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping">
	<property name="interceptors">
		<list>
			<ref bean="authorizationInterceptor"/>
		</list>
	</property>
</bean>

<bean id="authorizationInterceptor" 
	class="org.springframework.web.servlet.handler.UserRoleAuthorizationInterceptor">
	<property name="authorizedRoles">
		<list>
			<value>administrator</value>
			<value>operator</value>
		</list>
	</property>	
</bean>
				

This an example where we explicitly mention the BeanNameUrlHandlerMapping and set an interceptor allowing only administrators and operators to call the beans mentioned in this application context.

Note: Of course, this example doesn't show a flexible kind of security infrastructure. For more options as far as security is concerned, have a look at the Acegi Security System for Spring, to be found at http://acegisecurity.sourceforge.net.

Setting up the HTTP invoker infrastructure for a service objects much resembles the way you would do using Hessian or Burlap. Just as Hessian support provides the HessianServiceExporter, Spring Http invoker support provides the so-called org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter. To expose the AccountService (mentioned above), the following configuration needs to be in place:

<bean name="/AccountService" class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
  <property name="service" ref="accountService"/>
  <property name="serviceInterface" value="example.AccountService"/>
</bean>

Again, linking in the service from the client much resembles the way you would do it when using Hessian or Burlap. Using a proxy, Spring will be able to translate your calls to HTTP POST requests to the URL pointing to the exported service.

<bean id="httpInvokerProxy" class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
  <property name="serviceUrl" value="http://remotehost:8080/AccountService"/>
  <property name="serviceInterface" value="example.AccountService"/>
</bean>

As mentioned before, you can choose what HTTP client you want to use. By default, the HttpInvokerProxy uses the J2SE HTTP functionality, but you can also use the Commons HttpClient by setting the httpInvokerRequestExecutor property:

<property name="httpInvokerRequestExecutor">
	<bean class="org.springframework.remoting.httpinvoker.CommonsHttpInvokerRequestExecutor"/>
</property>

Spring has a convenience base class for JAX-RPC servlet endpoint implementations - ServletEndpointSupport. To expose our AccountService we extend Spring's ServletEndpointSupport class and implement our business logic here, usually delegating the call to the business layer.

/**
 * JAX-RPC compliant RemoteAccountService implementation that simply delegates
 * to the AccountService implementation in the root web application context.
 *
 * This wrapper class is necessary because JAX-RPC requires working with
 * RMI interfaces. If an existing service needs to be exported, a wrapper that
 * extends ServletEndpointSupport for simple application context access is
 * the simplest JAX-RPC compliant way.
 *
 * This is the class registered with the server-side JAX-RPC implementation.
 * In the case of Axis, this happens in "server-config.wsdd" respectively via
 * deployment calls. The Web Service tool manages the life-cycle of instances
 * of this class: A Spring application context can just be accessed here.
 */
public class AccountServiceEndpoint extends ServletEndpointSupport implements RemoteAccountService {
    
    private AccountService biz;
	
    protected void onInit() {
        this.biz = (AccountService) getWebApplicationContext().getBean("accountService");
    }

    public void insertAccount(Account acc) throws RemoteException {
        biz.insertAccount(acc);
    }
  
    public Account[] getAccounts(String name) throws RemoteException {
        return biz.getAccounts(name);
    }

}

Our AccountServletEndpoint needs to run in the same web application as the Spring context to allow for access to Spring's facilities. In case of Axis, copy the AxisServlet definition into your web.xml, and set up the endpoint in "server-config.wsdd" (or use the deploy tool). See the sample application JPetStore where the OrderService is exposed as a Web Service using Axis.

Spring has two factory beans to create web service proxies LocalJaxRpcServiceFactoryBean and JaxRpcPortProxyFactoryBean. The former can only return a JAX-RPC Service class for us to work with. The latter is the full fledged version that can return a proxy that implements our business service interface. In this example we use the later to create a proxy for the AccountService Endpoint we exposed in the previous paragraph. You will see that Spring has great support for Web Services requiring little coding efforts - most of the magic is done in the spring configuration file as usual:

    <bean id="accountWebService" class="org.springframework.remoting.jaxrpc.JaxRpcPortProxyFactoryBean">
        <property name="serviceInterface" value="example.RemoteAccountService"/>
        <property name="wsdlDocumentUrl" value="http://localhost:8080/account/services/accountService?WSDL"/>
        <property name="namespaceUri" value="http://localhost:8080/account/services/accountService"/>
        <property name="serviceName" value="AccountService"/>
        <property name="portName" value="AccountPort"/>
    </bean>

Where serviceInterface is our remote business interface the clients will use. wsdlDocumentUrl is the URL for the WSDL file. Spring needs this a startup time to create the JAX-RPC Service. namespaceUri corresponds to the targetNamespace in the .wsdl file. serviceName corresponds to the serivce name in the .wsdl file. portName corresponds to the port name in the .wsdl file.

Accessing the Web Service is now very easy as we have a bean factory for it that will expose it as RemoteAccountService interface. We can wire this up in Spring:

    <bean id="client" class="example.AccountClientImpl">
        ...
        <property name="service" ref="accountWebService"/>
    </bean>

And from the client code we can access the Web Service just as if it was a normal class, except that it throws <exception>RemoteException</exception>.

public class AccountClientImpl {

    private RemoteAccountService service;
    
    public void setService(RemoteAccountService service) {
        this.service = service;
    }
    
    public void foo() {
       try {
           service.insertAccount(...);
        } catch (RemoteException ex) {
           // ouch
           ...
        }
     }
     
}

We can get rid of the checked RemoteException since Spring supports automatic conversion to its corresponding unchecked RemoteAccessException. This requires that we provide a non RMI interface also. Our configuration is now:

    <bean id="accountWebService" class="org.springframework.remoting.jaxrpc.JaxRpcPortProxyFactoryBean">
        <property name="serviceInterface">
            <value>example.AccountService</value>
        </property>
        <property name="portInterface">
            <value>example.RemoteAccountService</value>
        </property>
        ...
    </bean>

Where serviceInterface is changed to our non RMI interface. Our RMI interface is now defined using the property portInterface. Our client code can now avoid handling java.rmi.RemoteException:

public class AccountClientImpl {

    private AccountService service;
    
    public void setService(AccountService service) {
        this.service = service;
    }
    
    public void foo() {
        service.insertAccount(...);
     }
     
}

To transfer complex objects over the wire such as Account we must register bean mappings on the client side.

	Note
	On the server side using Axis registering bean mappings is usually done in server-config.wsdd.

We will use Axis to register bean mappings on the client side. To do this we need to subclass Spring Bean factory and register the bean mappings programmatic:

public class AxisPortProxyFactoryBean extends JaxRpcPortProxyFactoryBean {

	protected void postProcessJaxRpcService(Service service) {
		TypeMappingRegistry registry = service.getTypeMappingRegistry();
		TypeMapping mapping = registry.createTypeMapping();
		registerBeanMapping(mapping, Account.class, "Account");
		registry.register("http://schemas.xmlsoap.org/soap/encoding/", mapping);
	}

	protected void registerBeanMapping(TypeMapping mapping, Class type, String name) {
		QName qName = new QName("http://localhost:8080/account/services/accountService", name);
		mapping.register(type, qName,
		    new BeanSerializerFactory(type, qName),
		    new BeanDeserializerFactory(type, qName));
	}

}

In this section we will register our own javax.rpc.xml.handler.Handler to the Web Service Proxy where we can do custom code before the SOAP message is sent over the wire. The javax.rpc.xml.handler.Handler is a callback interface. There is a convenience base class provided in jaxrpc.jar - javax.rpc.xml.handler.GenericHandler that we will extend:

public class AccountHandler extends GenericHandler {

    public QName[] getHeaders() {
        return null;
    }

    public boolean handleRequest(MessageContext context) {
        SOAPMessageContext smc = (SOAPMessageContext) context;
        SOAPMessage msg = smc.getMessage();

        try {
            SOAPEnvelope envelope = msg.getSOAPPart().getEnvelope();
            SOAPHeader header = envelope.getHeader();
            ...
		
        } catch (SOAPException e) {
            throw new JAXRPCException(e);
        }

        return true;
    }

}

What we need to do now is to register our AccountHandler to JAX-RPC Service so it would invoke handleRequest before the message is sent over the wire. Spring has at this time of writing no declarative support for registering handlers. So we must use the programmatic approach. However Spring has made it very easy for us to do this as we can extend its bean factory and override its postProcessJaxRpcService method that is designed for this:

public class AccountHandlerJaxRpcPortProxyFactoryBean extends JaxRpcPortProxyFactoryBean {

    protected void postProcessJaxRpcService(Service service) {
        QName port = new QName(this.getNamespaceUri(), this.getPortName());
        List list = service.getHandlerRegistry().getHandlerChain(port);
        list.add(new HandlerInfo(AccountHandler.class, null, null));

        logger.info("Registered JAX-RPC Handler [" + AccountHandler.class.getName() + "] on port " + port);
    }

}

And the last thing we must remember to do is to change the Spring configuration to use our factory bean:

    <bean id="accountWebService" class="example.AccountHandlerJaxRpcPortProxyFactoryBean">
        ...
    </bean>    

XFire is a lightweight SOAP library, hosted by Codehaus. At the time of writing (March 2005), XFire is still in development. Although Spring support is stable, lots of features should be added in the future. Exposing XFire is done using an XFire context that shipping with XFire itself in combination with a RemoteExporter-style bean you have to add to your WebApplicationContext.

As with all methods that allow you to expose service, you have to create a DispatcherServlet with a corresponding WebApplicationContext containing the services you will be exposing:

<servlet>
  <servlet-name>xfire</servlet-name>
  <servlet-class>
    org.springframework.web.servlet.DispatcherServlet
  </servlet-class>
</servlet>
                

You also have to link in the XFire configuration. This is done by adding a context file to the contextConfigLocations context parameter picked up by the ContextLoaderListener (or Servlet for that matter). The configuration file is located in the XFire jar and should of course be placed on the classpath of your application archive.

<context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>
    classpath:org/codehaus/xfire/spring/xfire.xml
  </param-value>
</context-param>

<listener>
  <listener-class>
    org.springframework.web.context.ContextLoaderListener
  </listener-class>
</listener>
                

After you added a servlet mapping (mapping /* to the XFire servlet declared above) you only have to add one extra bean to expose the service using XFire. Add for example the following you xfire-servlet.xml:

<beans>
  <bean name="/Echo" class="org.codehaus.xfire.spring.XFireExporter">
    <property name="service" ref="echo">
    <property name="serviceInterface" value="org.codehaus.xfire.spring.Echo"/>
    <property name="serviceBuilder" ref="xfire.serviceBuilder"/>
    <!-- the XFire bean is wired up in the xfire.xml file you've linked in earlier
    <property name="xfire" ref="xfire"/>
  </bean>

  <bean id="echo" class="org.codehaus.xfire.spring.EchoImpl"/>
</beans>

XFire handles the rest. It introspects your service interface and generates a WSDL from it. Parts of this documentation have been taken from the XFire site. For more detailed information on XFire Spring integration, have a look at the docs.codehaus.org/display/XFIRE/Spring.