XFire – Minimizr

Minimal Web Services with XFire, Spring and PHP

Leave a Comment / Java, PHP, Spring, Web Services, XFire / By kristian

If you have a Java web application implemented with Java 5 and Spring Framework, it is really easy to expose your POJOs as web services. In this example I use XFire and JSR 181 annotations for that. I’ll also make a small web service client example with PHP. The goal is to add web services to the existing Java code with absolute minimal code addition. I was about to add web service authentication with Acegi Security, but instead for now, there is no authentication in this example.

XFire has a quite versatile but scarce user’s guide. But it is a good start, so start with overview and quick start. Add XFire libraries and the depencies with the help of a Depency quide. This example works at least with the following libraries:

xfire-all-1.2.2
activation-1.1
commons-codec-1.3
commons-httpclient-3.0
commons.logging-1.0.4
mail-1.4
jaxen-1.1-beta-9
jdom-1.0

junit-3.8.1
servlet-api-2.3
spring-2.0
stax-api-1.0.1
wsdl4j-1.5.2
xbean-spring-2.5
wstx-3.0.1
XmlSchema-1.1

xfire-jsr181-api-1.0-M1
jaxb-xjc-2.0.1
jaxb-impl-2.0.1
jaxb-api-2.0
aopalliance-1.0
commons-beanutils-1.7.0

XFire 1.2.2 package comes with xbean-spring-2.6. There can be some problems with that version but at least version 2.5 is working with Spring 2.0.

First, add xfire-servlet.xml into WEB-INF directory. Here are the default settings from the user’s manual:

<?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 id="jaxbTypeMappingRegistry"
        class="org.codehaus.xfire.jaxb2.JaxbTypeRegistry"
        init-method="createDefaultMappings" singleton="true"/>
    <bean id="webAnnotations"
        class="org.codehaus.xfire.annotations.jsr181.Jsr181WebAnnotations"/>
    <bean id="handlerMapping"
        class="org.codehaus.xfire.spring.remoting.Jsr181HandlerMapping">
      <property name="typeMappingRegistry">
        <ref bean="jaxbTypeMappingRegistry"/>
      </property>
      <property name="xfire">
        <ref bean="xfire"/>
      </property>
      <property name="webAnnotations">
        <ref bean="webAnnotations"/>
      </property>
    </bean>
    <bean class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
      <property name="urlMap">
        <map>
          <entry key="/">
            <ref bean="handlerMapping"/>
          </entry>
        </map>
      </property>
    </bean>
</beans>

Add xfire-servlet.xml into the Spring’s contextConfigLocation and XFireServlet in web.xml file:

<context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>
    /WEB-INF/applicationContext.xml
    /WEB-INF/xfire-servlet.xml
  </param-value>
</context-param>
 
<servlet>
  <servlet-name>XFireServlet</servlet-name>
  <display-name>XFire Servlet</display-name>
  <servlet-class>org.codehaus.xfire.spring.XFireSpringServlet</servlet-class>
</servlet>
 
<servlet-mapping>
  <servlet-name>XFireServlet</servlet-name>
  <url-pattern>/servlet/XFireServlet/*</url-pattern>
</servlet-mapping>
 
<servlet-mapping>
  <servlet-name>XFireServlet</servlet-name>
  <url-pattern>/services/v1/*</url-pattern>
</servlet-mapping>

Let’s have a simply MinimizrFacade.java Java interface:

package com.minimizr.service;
 
import java.util.List;
import com.minimizr.service.domain.ExampleObject;
 
public interface MinimizrFacade {
  String getString();
  String echoString(String string);
  ExampleObject echoObject(ExampleObject exampleObject);
  List<exampleObject> loadExampleObjectList();
}

And let’s have another MinimizrService.java Java interface for web services:

package com.minimizr.service;
 
import java.util.List;
import javax.jws.WebService;
import com.minimizr.service.domain.ExampleObject;
 
@WebService
public interface MinimizrService {
  String getString();
  String echoString(String string);
  ExampleObject echoObject(ExampleObject exampleObject);
  List<exampleObject> loadExampleObjectList();
}

And for this example a ExampleObject.java Java object:

package com.minimizr.service;
 
public class ExampleObject {
  private String name;
  private Integer age;
 
  public Integer getAge() {
    return age;
  }
 
  public void setAge(Integer age) {
    this.age = age;
  }
 
  public String getName() {
    return name;
  }
 
  public void setName(String name) {
    this.name = name;
  }
}

And finally a MinimizrImpl.java Java implementation for the interfaces:

package com.minimizr.domain.logic;
 
import java.util.List;
import javax.jws.WebService;
import com.minimizr.service.ExampleObject;
import com.minimizr.service.MinimizrService;
 
@WebService(serviceName = "MinimizrService",
    endpointInterface = "com.minimizr.service.MinimizrService")
public class MinimizrImpl implements MinimizrFacade, MinimizrService {
  public String getString() {
    return "Example string";
  }
 
  public String echoString(String string) {
    return string;
  }
 
  public ExampleObject echoObject(ExampleObject exampleObject) {
    return exampleObject;
  }
 
  public List loadExampleObjectList() {
    /* Here you would get list of ExampleObjects for example from database
    and return it instead of null */
    return null;
  }
}

XFire does not support RPC-encoding but you can use XFire web services with PHP with document/literal style of SOAP.

Here is a really simple example to use all the exposed java web services in this example with NuSOAP PHP SOAP library. There are no checks for errors in the code:

<?php
require("../lib/nusoap.php");
$soapClient = new soapclient(
    "https://minimizr.com/ws/services/v1/MinimizrService?wsdl", "wsdl");
$proxyClass = $soapClient->getProxy();
 
// getString
$string = $proxyClass->getString();
print("<b>String:</b> " . $string["out"] . "<hr/>");
 
// echoString
$string = $proxyClass->echoString(array("in0" => "ABC"));
print("<b>String:</b> " . $string["out"] . "<hr/>");
 
// echoObject
$requestObject = array("name" => "John", "age" => 50);
$result = $proxyClass->echoObject(array("in0" => $requestObject));
$resultObject = $result["out"];
print("<b>Object:</b> name: " . $resultObject["name"]);
print(", age: " . $resultObject["age"] . "<hr/>");
 
// loadExampleObjectList
$exampleObjectList = $proxyClass->loadExampleObjectList();
foreach ($exampleObjectList["out"]["ExampleObject"] as $key => $value) {
  print($value["name"] . " " . $value["age"] . "<br/>");
}
?>

Authentication

Added November 14, 2006: Well, easiest and most straightforward way to secure web service is to use HTTP Authentication. It doesn’t need any additional code in the server side. While still looking for solution to use easily Acegi Security, I’ll add HTTP Authentication to this example. On the server side you’ll have to add security constraint into web.xml:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>Protected Minimizr Web Services</web-resource-name>
    <url-pattern>/services/v1/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>minimizr.webservices.client</role-name>
  </auth-constraint>
</security-constraint>
 
<login-config>
  <auth-method>BASIC</auth-method>
  <realm-name>Minimizr Realm</realm-name>
</login-config>
 
<security-role>
  <description>Required roles to use the Web Services</description>
  <role-name>minimizr.webservices.client</role-name>
</security-role>

And couple more lines into the PHP file. Credentials must be added into the wsdl url and proxy class. Notice that it is quite necessary to use SSL connection (https) with basic authentication since username and password are in clear text. You can use useHTTPPersistentConnection method to use persistent connection, if possible:

<?php
require("../lib/nusoap.php");
 
$username = "username";
$password = "password";
$method = "basic";
 
$soapClient = new soapclient(
  "https://$username:$password@www.minimizr.com/ws/services/v1/MinimizrService?wsdl",
  "wsdl");
$proxyClass = $soapClient->getProxy();
$proxyClass->setCredentials($username, $password, $method);
$proxyClass->useHTTPPersistentConnection();
...

Conclusion

It is no brainer to expose Java POJOs as web services with Spring, XFire and JSR-181 annotations. And it is as easy use those web services with Java or PHP or other platforms. I guess integrating Acegi Security with XFire web services needs a little bit more work. Any suggestions for the easiest way to implement it?

Additional recourses

Minimal Web Services with XFire, Spring and PHP Read More »