Category: SOA

As mentioned in Web Services and Null Values – Part I-II one should not return a Java wrapper type, e.g. Boolean, from a Web Service as this type is modeled as xsd:boolean in the WSDL file.
If the service returns a null value for an xsd:boolean the caller might get in throuble.
In .NET it’s not a problem to return a Boolean because it can’t be null. That’s because Boolean is a value type.
Whereas in Java boolean and Boolean are different types in .NET they are the same System::Boolean.

Java

boolean (native)
Boolean (java.lang.Boolean reference type)

C#

bool (System.Boolean value type)
Boolean (System.Boolean value type)

If you need to transfer an parameter in a Web Service message for which null is a legal value always use a custom complex type.

Assume you have the following Web Service method:

public bool isCompany()
{
    return true;
}

If the requested information is not known it might be good idea to use Boolean instead of the native type boolean like in the following code snippet:

public Boolean isCompany()
{
    return null; // that means unknown
}

Here null is returned to indicate that the information is not known.

If you generate the WSDL from this code you will get an xsd:boolean on the wire. The result is the same for Boolean and boolean.
That means in XML the boolean value is not nullable anymore.
If you want the transfer a nullable type wrap it in a complex type:

public class WSBoolean
{
    public boolean;
}

public WSBoolean isCompany()
{
    return null; // that means unknown
}

I experienced this behaviour on BEA Weblogic 8.1 SP3, but I expect other frameworks/platforms like .NET or Websphere to behave in the same way.
If you wrap your nullable types you are on the safe side.

The meaning of a null is “value not set”. Apparently it is a difference whether you say the credit limit is zero or not set. Therefore sometimes it is necessary to convey null values over Web Services.
Luckily Web Services provide the means to express null values.
Assume the following Web Service method:

public String getName()
{
    return null;
}

The reponse in the SOAP Message uses the xsi:nil=”true” to express the null value on the wire.

This is fine as long as we use certain types as e.g. strings.
But if we use types which have a different representation on different plattform we might run into problems. Even though they are represented by a legal XML Schema type.
For instance the java types java.util.Date and java.util.Calendar are reference types on the Java platform.
The equivalent type System.DateTime is a value type on the .NET plattform which can’t be null.
If a reference type set to null is returned from a Java Web Service it causes a System.FormatException on the .NET plattform.
As the SOAP reponse is valid it seems to be a bug in the .NET implementation.

To avoid the problem wrap the reference type in an complex type as follows:

public class ServiceCalendar
{
    public ServiceCalendar(Calendar date)
    {
        this.date=date;
    }

    public Calendar date;
}

public class Service
{
    java.util.Calendar cal= new GregorianCalendar();

    public ServiceCalendar getDate()
    {
        return new ServiceCalendar(cal); // or return null;
    }
}

Enjoy

The meaning of a null is “value not set”. Apparently it is a difference whether you say the credit limit is zero or not set. Therefore sometimes it is necessary to convey null values over Web Services.
Luckily Web Services provide the means to express null values.
Assume the following Web Service method:

public String getName()
{
    return null;
}

The reponse in the SOAP Message uses the xsi:nil=”true” to express the null value on the wire.

This is fine as long as we use certain types as e.g. strings.
But if we use types which have a different representation on different plattform we might run into problems. Even though they are represented by a legal XML Schema type.
For instance the java types java.util.Date and java.util.Calendar are reference types on the Java platform.
The equivalent type System.DateTime is a value type on the .NET plattform which can’t be null.
If a reference type set to null is returned from a Java Web Service it causes a System.FormatException on the .NET plattform.
As the SOAP reponse is valid it seems to be a bug in the .NET implementation.

To avoid the problem wrap the reference type in an complex type as follows:

public class ServiceCalendar
{
    public ServiceCalendar(Calendar date)
    {
        this.date=date;
    }

    public Calendar date;
}

public class Service
{
    java.util.Calendar cal= new GregorianCalendar();

    public ServiceCalendar getDate()
    {
        return new ServiceCalendar(cal); // or return null;
    }
}

Enjoy

An interesting article Patterns and Strategies for Building Document-Based Web Services was posted on the Sun website which explains important aspects of developing document/literal web services.

The doc/lit encoding is important when it comes to interoperable web services as shown in the WS-I Basic Profile 1.0 and Attachments Profile Version 1.0. Although doc/lit is the preferred encoding most tookits don’t use it by default.

Recently I’ve tried to implement web service attachments in BEA Weblogic Server 8.1.SP3. Although it should work, it didn’t. The problem is that the ant tasks did not emit consistent type mapping descriptors and WSDL for the client and server side. At least on the same platform it should work but it doesn’t. That’s a humbling experience.

By now the easiest way to exchange binary data is still the base64binary schema type, which is larger on the wire but can be exchanged without trouble. If the caller of the service knows the mime type of the blob it’s possible to save it in an appropriate manner.

The following code snippet does the trick:

class Doc
{
byte[] blob;
String mimeType; // e.g. image/gif
}

class MyService
{
public Doc getDocument(){…};
}

By this you can exchange binary data of any type. At least until web service attachments work as expected on all major platforms.

To sum it up – if you have to be really interoperable with your web services you need a lot of knowledge about the underlying specs and technologies. The standard examples won’t help you very much.

You’ll find some useful tips for Web Service interop at Top Ten Tips for Web Services Interoperability and in my german article Entwicklung interoperabler Web Services mit J2EE und .NET in the dotnetpro magazine (Login required).

Sometimes I hear the question “Why not decouple the service from the caller by using generic interfaces?”

To better understand this question let’s have a look at the following pseudo code example:

BookingService
{
Flight[] getAvailableFlights(date flightDate, string destination);
bool bookFlight(int flightId);
}

The Web Service BookingService has two methods, which can be called by the clients and is described in an BookingService.wsdl file.
If we would like to add a new method for instance cancelFlight(int flightId) we have to change the caller of the service. In most cases this means rebuilding the client side proxy.

Why not using a generic interface like one of the following:

Generic parameter approach:

BookingService
{
Map getAvailableFlights(Map params);
Map bookFlight(Map params);
}

This approach uses only generic parameters but no generic service operations.

Generic service approach:

GenericService
{
Map execute(int commandId,Map params);
}

This approcach uses the common command pattern. It means the client sends a command id toghether with the required parameters to the service.
Dependent of the command id the service dispatches the call to the service implementation.
In order to add the service method cancelFlight we simply have to add a new command. The contract remains unchanged and the proxy hasn’t to be rebuild.
And even better the parameters can be processed in a generic way. That’s cool, isn’t it?

At first glance this approach looks promising. But at what price?

A common misunderstanding is that the Web Service Signature described in the WSDL file forms the service contract. This is only one option.
More precisely said the name of the service operation (or command id) in conjunction with the required in and out parameters form the contract.
It doesn’t matter where this information is stored.

What really happens when using generic interfaces is that the contract is shifted from a standarized to a custom layer.
That means the contract is not described in the BookingService.wsdl file anymore. Now the service and the caller need a proprietary way to describe and exchange the contract.
Moreover the type safety is lost because only generic types are used.
The command dispatching must be implemented. This is usually handled by the Web Service infrastructure for instance by using the SoapAction in the HTTP-Header.
Generic parameter processing is not a reason to use generic interfaces. If necessary reflection can be used to process typed parameters in a generic way, but without loosing type safety.

I think the drawbacks of generic interfaces outweight the benefits.
What do you think?