AppFuseXFire

Webservices out of AppFuse - A HowTo for providing Webservices from within AppFuse.

About this Tutorial

Table of Contents

• [0] Preface
• [1] Install the necessary artifacts from the extras package
• [2] The UserWebservice demo inspected
• [3] Testing without container

Preface [#0]

Install the necessary artifacts from the extras package [#1]

   ant install

• Copy the xfire-lib-jars from extras/xfire/lib to the AppFuse libs dir and add xfire.version, xfire.dir and xfire.test.dir to lib.properties
• Add the xfire-jars to the libs wich are included in the war (by adding the xfire.dir to the war target in build.xml)
• Add applicationContext-webservice and *.aegis.xml files to the selection of files which go into service.jar (by amending build.xml package-service target)
• Add xfire to build path (by amending properties.xml)
• Add servlet and servlet-mapping to web/WEB-INF/web.xml
• Copy xdoclet-template (aegis-mapping.xdt) to ../../metadata/templates
• Add xfire gen-aegis-mapping target to build.xml
• Copy EchoWebServiceTest to test/service/org/appfuse/service
• Adjust .classpath for eclipse

To test, if everything worked as expected you can issue

   ant test

package org.appfuse.service;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.codehaus.xfire.spring.AbstractXFireSpringTest;
import org.jdom.Document;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class EchoWebServiceTest extends AbstractXFireSpringTest {

    protected final Log log = LogFactory.getLog(getClass());

    public void setUp() throws Exception {
        super.setUp();
    }
    
    public void testGetWsdl() throws Exception {
        Document doc = getWSDLDocument("Echo");
        printNode(doc);
        
        assertValid("//xsd:element[@name=\"echo\"]", doc);
        assertValid("//xsd:element[@name=\"echoResponse\"]", doc);
    }
    
    public void testCallEcho() throws Exception {
        Document response =
            invokeService("Echo", "/org/appfuse/service/echo.xml");
        printNode(response);
        
        addNamespace("service","http://test.xfire.codehaus.org");
        assertValid("//service:echoResponse/service:out[text()=\"Hello world!\"]",response);


    }

    protected ApplicationContext createContext() {
        return new ClassPathXmlApplicationContext(new String[]{
                "org/appfuse/service/applicationContext-test.xml",
                "org/appfuse/service/applicationContext-webservice.xml"});
    }
    

}

invokeService() for example uses the LocalBinding of XFire to send the echo.xml file into the stack and assertValid() uses XPath expressions to examine the (xml)response of the service.

echo.xml

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
 <env:Body>
  <echo xmlns="http://service.appfuse.org">
    <in0>Hello world!</in0>
  </echo>
 </env:Body>
</env:Envelope>

You'll find more about testing in section [3].

The UserWebservice demo inspected [#2]

The extras package contains a demo showing how to create webservices out of AppFuse. You can install the demo by issuing

   ant install-demo

package org.appfuse.service;

import java.util.List;

import org.appfuse.dao.UserDAO;
import org.appfuse.model.User;


/**
 * WebService Interface
 *
 * <p><a href="UserWebService.java.html"><i>View Source</i></a></p>
 *
 * @author <a href="mailto:[email protected]">Mika Goeckel</a>
 * @aegis.mapping 
 */
public interface UserWebService {
    //~ Methods ================================================================

    /**
     * Retrieves a user by username.  An exception is thrown if now user 
     * is found.
     *
     * @param username
     * @return User
     */
    public User getUser(String username);

    /**
     * Retrieves a list of users, filtering with parameters on a user object
     * @param user parameters to filter on
     * @return List
     * 
     * Tell xfire, which objects it will find in the List
     * @aegis.method
     * @aegis.method-return-type componentType="org.appfuse.model.User"
     */
    public List getUsers(User user);

    /**
     * Saves a user's information
     *
     * @param user the user's information
     * @throws UserExistsException
     */
    public void saveUser(User user) throws UserExistsException;

    /**
     * Removes a user from the database by their username
     *
     * @param username the user's username
     */
    public void removeUser(String username);
}

The rationale behind the additional interface is to clearly separate the methods that you want to expose as webservice from these that you use inside your application. Actually there is no way to ignore a method of an exposed interface in xfire as of version 1.0 like the @xfire.property ignore="true" that exists on the model objects (we'll com to that later), so having a second interface is probably the best way to distinct at the moment.

Looking on the source code of the interface above, you noticed the uncommon xdoclet tags @aegis.mapping at class level and @aegis.method and @aegis.method-return-type on the getUsers() method. These are tags which are processed using the aegis-mapping.xdt xdoclet template which was added earlier into metadata/templates by the ant install task. XFire has several ways of describing the metainformation you need to create a webservice. One of them is aegis, another is JSR181-Annotations. Aegis works with xml files which contain the metadata. These files look like

<?xml version="1.0" encoding="utf-8"?>
<mappings>
	<mapping>
		<method name="getUsers">
			<return-type componentType="org.appfuse.model.User"/>
		</method>
	</mapping>
</mappings>

In this case the tag describes to xfire what objects it should expect in the List, the getUsers() method returns. This allows xfire to assign the right return type to the method in the wsdl (webservice description language) which is

<xsd:complexType name="ArrayOfUser">
   <xsd:sequence>
      <xsd:element name="User" type="ns1:User" nillable="true" minOccurs="0" maxOccurs="unbounded" />
   </xsd:sequence>
</xsd:complexType>

Exactly that problem makes it necessary to add some xdoclet tags to the model we use in AppFuse. User references a List of Roles and Role backreferences User (later more on that). So the getRoles() method on the User object needs a tag as well:

    /**
     * @hibernate.set table="user_role" cascade="save-update" lazy="false"
     * @hibernate.collection-key column="username"
     * @hibernate.collection-many-to-many class="org.appfuse.model.Role" column="role_name"
     * @aegis.property componentType="org.appfuse.model.Role"
     */
    public Set getRoles() {
        return roles;
    }

So now more on the backreference in Role.java:

    /**
     * @return Returns the users.
     * This inverse relation causes exceptions :-( drk
     * hibernate.set table="user_role" cascade="save-update"
     *                lazy="false" inverse="true"
     * hibernate.collection-key column="role_name"
     * hibernate.collection-many-to-many class="org.appfuse.model.User"
     *                                    column="username"
     * @aegis.property ignore="true"
     */
    public Set getUsers() {
        return users;
    }

What else do you need to do to expose something as a webservice. We already had the aegis xdoclet annotations, which are only necessary in case you have Collection types, but how does xfire know what service you want to expose? XFire integrates with several IoC frameworks, PicoContainer, Plexus, Loom and last but definitiely not least Spring. Besides that XFire can be configured through XFireConfigurableServlet and XFireServlet. You even don't need a servlet container, because XFire comes with a built in Jetty so that you could run completely stand alone.

In AppFuse we've got Spring and we run inside Tomcat or another ServletContainer (XFire has proven to run in Tomcat, JBoss and Weblogic in my tests, other probably work as well), so we use Spring to tell XFire what to do. You might have notices the applicationContext-webservice.xml which we copied into the src/service/org/appfuse/service directory:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
    "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>

	<import resource="classpath:org/codehaus/xfire/spring/xfire.xml"/>
	
    <bean name="echoService" class="org.codehaus.xfire.spring.ServiceBean">
        <property name="serviceBean" ref="echo"/>
        <property name="serviceClass" value="org.codehaus.xfire.test.Echo"/>
        <property name="inHandlers">
            <list>
                <ref bean="addressingHandler"/>
            </list>
        </property>
    </bean>

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

    <bean name="userService" class="org.codehaus.xfire.spring.ServiceBean">
        <property name="serviceBean" ref="userManager"/>
        <property name="serviceClass" value="org.appfuse.service.UserWebService"/>
        <property name="inHandlers">
            <list>
                <ref bean="addressingHandler"/>
            </list>
        </property>
    </bean>

    <bean id="addressingHandler" class="org.codehaus.xfire.addressing.AddressingInHandler"/>

</beans>

I chose this way, because I find it easy to understand and to use, given the structure of AppFuse. So such xml Spring beans files are not uncommon to you. The import tag at the beginning is our way to include the standard xfire bean definitions (have a look into that file, it's in xfire-spring.jar)

We use the ServiceBean from xfire-spring.jar, which is easy to configure. If you ignore the AddressingInHandler (which is to support ws-addressing header information), it's really straight forward. You define an interface (property serviceClass) which will be exposed and an implementation (in this case a reference to userManager, defined in applicationContext-service.xml). The first definition (echoService) is a simple test service which just returns the string you put in as argument (the one we called in EchoWebServiceTest above). So to create additional services, you don't need more than add another ServiceBean with your interface and implementation class.

ServiceBean is more complex than that snippet of xml suggests. You can control large portions of the behavior of xfire using your impementations of other properties ServiceBean takes. The complete processing stack (In-, Out- and Fault-Handlers), ServiceFactory, known XML-Schemas, Bindings, Scope (request, session, application) and much more. Through controlling the ServiceFactory you even got more options. But the default settings is just what we need here. Unfortunately the best way to understand the possibilities is reading the code, as there is not much documentation there right now. But be assured, the code is really understandable.

If you want to see your service live, do an

   ant deploy

and go to http://localhost:8080/appfuse/services with your browser. You should see

Services:

    * Echo
    * UserWebService

Next, you can get the wsdl of these services by calling http://localhost:8080/appfuse/services/UserWebService?wsdl which should produce some lines of xml, something like

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:ns1="http://model.appfuse.org" 
xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope" 
xmlns:soapenc11="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenc12="http://www.w3.org/2003/05/soap-encoding" 
xmlns:tns="http://service.appfuse.org" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
targetNamespace="http://service.appfuse.org">
  <wsdl:types xmlns:ns2="http://acegisecurity.org">
    <xsd:schema targetNamespace="http://model.appfuse.org" elementFormDefault="qualified" attributeFormDefault="qualified">
      <xsd:complexType name="User">
        <xsd:sequence>
          <xsd:element name="accountExpired" type="xsd:boolean" minOccurs="0" />
          <xsd:element name="accountLocked" type="xsd:boolean" minOccurs="0" />
          <xsd:element name="accountNonExpired" type="xsd:boolean" minOccurs="0" />
          <xsd:element name="accountNonLocked" type="xsd:boolean" minOccurs="0" />
          ...

Testing without container [#3]

This is an easy, but unfortunately very manual way of testing your service. As a test infected AppFuse developer you probably want to use unit tests for your services. We've seen a simple testcase above (EchoWebServiceTest) now we want to dive deeper into testing of webservices with the UserWebServiceTest:

package org.appfuse.service;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.appfuse.dao.UserDAO;
import org.appfuse.model.User;
import org.codehaus.xfire.spring.AbstractXFireSpringTest;
import org.jdom.Document;
import org.jmock.Mock;
import org.jmock.core.constraint.IsEqual;
import org.jmock.core.matcher.InvokeOnceMatcher;
import org.jmock.core.stub.ReturnStub;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class UserWebServiceTest extends AbstractXFireSpringTest {

    protected final Log log = LogFactory.getLog(getClass());

    public void setUp() throws Exception {
        super.setUp();
    }
    
    public void testGetWsdl() throws Exception {
        Document doc = getWSDLDocument("UserWebService");
        printNode(doc);
        
        assertValid("//xsd:complexType[@name=\"User\"]", doc);
        assertValid("//xsd:complexType[@name=\"Role\"]", doc);
    }
    
    public void testGetUser() throws Exception {
        // Setup testharness 
        User testData = new User("tomcat");
        testData.setEnabled(true);
        Mock userDAO = new Mock(UserDAO.class);
        
        // because we can't extend MockObjectTestCase we create new instances for once(), eq() and returnValue()
        InvokeOnceMatcher once = new InvokeOnceMatcher();
        IsEqual eq = new IsEqual("tomcat");
        ReturnStub returnValue = new ReturnStub(testData);
        userDAO.expects(once).method("getUser").with(eq).will(returnValue);
        
        UserManager service = (UserManager) getContext().getBean("userManager");
        service.setUserDAO((UserDAO)userDAO.proxy());
        
        // invoke webservice
        Document response =
            invokeService("UserWebService", "/org/appfuse/service/getUser.xml");

        //printNode(response);
        // verify result
        userDAO.verify();
        addNamespace("service","http://service.appfuse.org");
        addNamespace("model","http://model.appfuse.org");
        assertValid("//service:getUserResponse/service:out[model:username=\"tomcat\"]",response);
        assertValid("//service:getUserResponse/service:out[model:enabled=\"true\"]",response);
    }

    protected ApplicationContext createContext() {
        return new ClassPathXmlApplicationContext(new String[]{
                "org/appfuse/service/applicationContext-test.xml",
                "org/appfuse/service/applicationContext-webservice.xml"});
    }
    

}

The testGetUser shows that the test really calls through to your Manager class. It shows as well how you can use JMock even if you don't extend JMock's MockObjectTestCase which you would do if you use the BaseManagerTestCase of AppFuse. Because we need the functionality of the Spring/XFire TestCase classes, we can't use the BaseManagerTestCase but fortunately there is a way around.

I hope I could explain how to use XFire together with AppFuse a little bit. Once you started playing arounf with XFire you probably find out more and more details that aren't even mentioned in this HowTo, please feel free to extend it.

The former tutorial is available here