Year: 2004

Long Is Not Long

If you need to be interoperable with your Web Services you have to follow a lowest common denominator approach.

Currently I experienced an example as I tried to call a Java Web Service from VBA through a COM Wrapper and .NET (VBA->COM->.NET->SOAP->Java).
I used an long type (64 bit) in the Java Web Service interface. When I included the COM Type Library in Winword I recognized a non supported Variant type for this parameter.
Unfortunately a long in VBA is 32 bit. The Web Service died on the last mile to the client.

Web Services and Null Values – Part III

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)

Web Services and Null Values – Part II

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.

Interoperable Web Services and Null Values

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

Interoperable Web Services and Null Values

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

Maintainable Software by Inheritance of Responsibility

What is software quality all about?

In general quality means:
– That it works according to the specifications.
– It’s maintainable.

Who is responsible to meet these goals? It’s the developer and tester.
If you have a sound specification it’s easy to measure whether a software behaves according to the specifications.

The second goal is more difficult to achieve.
How can one determine whether a software is maintainable?

In general a developer should feel responsible for his/her code. This can be supported by not interchanging developer resources on a particular code or component. It is encouraged for instance by the Microsoft Solutions Framework (MSF) Team Model. Responsibility is important for a projects success.

But no developer stays in a company forever. And when he/she leaves the company it’s really getting visible whether a software is maintainable. The successor decides whether it is or not.
You might have experienced that: Usually code written by an other person is suspicious to a developer.
To avoid this responsibility is the key. In order to give software a future, responsibility has to be inherited from one person to another.

But how to achieve that?
Feeling responsible is nothing that can be decreed from outside. Responsibility grows inside a person.
In order to make a person feel responsible he/she has to feel confident with the code.

It helps if the code is well documented and more important clearly structured.
The person really has to understand the intention of the developer who created the code.
It might be a good idea to refactor existing code together with the successor and simplify it’s structure so that he/she really understands it.
Give enough time for hand over (weeks not days). It’s not sufficient just to pass the documentation and say good bye as it often happens. This can’t be enforced by the developer itself but the management which has to schedule it.

You will be good adviced to inherit responsibility in order to create maintainable software.

What is your opinion?

Document Based WebServices

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.